Trinity Lite

The bus that lets your AI agents talk to each other.

中文 README

The problem

You already use Claude Code. Maybe you just installed Codex. You want them to collaborate — but there's no built-in way to route tasks between them, remember who did what, or stop them from stepping on each other. Trinity Lite is the missing layer.

What it does

• Route by capability, not name. You describe the task. The router matches it to the right agent — no hardcoded agent names, no fragile dispatch logic. "Implement a rate limiter" lands on the agent you tagged implement. "Review the auth module" goes to the agent tagged review.
• Give every agent a pull queue. Workers read pending tasks from the shared bus, execute them via CLI, and write results back. Each agent polls on its own schedule. You never copy-paste an output between terminals again.
• Remember every decision. Every task, status change, result, error, and inter-agent message lands in a local SQLite database. Query who did what, when, and what happened — without setting up a logging pipeline.
• Block footguns before they fire. Self-delegation loops are rejected. Delegation depth has a hard cap. Working directories must be in the allowlist. You ship features, not incident reports.

Quick start

30 seconds, no agents required:

pip install trinity-lite
trinity-lite doctor
trinity-lite dispatch-auto "implement a hello-world function"
trinity-lite worker codex --once
trinity-lite tasks

Mock agents are built in. You see the full dispatch → execute → result cycle before you wire up anything real.

Not another framework

Trinity Lite doesn't build agents. It connects the agents you already have.

LangGraph and CrewAI give you primitives for building agents from scratch — graph definitions, role abstractions, tool wrappers. Trinity Lite starts from the opposite end: Claude Code is running in one terminal, Codex is running in another, and they need a shared task bus, durable state, and safety boundaries. No SDK to learn. No new agent abstraction. Just a bus that works with the CLIs you already use.

Who this is for

Features

• Route by capability. Tag agents with implement, review, audit — the router matches tasks to the agent that can do them. No agent names in your dispatch logic.
• Dispatch directly when you need control. Bypass the router and send a task straight to claude_code or codex. Best of both worlds.
• Persist everything in SQLite. Tasks, statuses, results, errors, and messages in one local file. Query it with sqlite3 or any tool that speaks SQL.
• Accept with evidence, not vibes. The review flow records route decisions, review links, verification results, acceptance reasons, and accepted_at in SQLite. A reviewed task is accepted only after the local verifier passes.
• Run CLI workers on demand. trinity-lite worker codex --once pulls one queued task, executes the agent's command, and writes the result. Run it in a loop, in cron, or by hand.
• Execute safely, no shell injection. Agent commands are JSON arrays run with shell=False. No string interpolation into a shell. No surprises.
• Test with mock agents. Mock agents simulate the full cycle without real CLIs. Prototype routing, persistence, and review handoffs first. Wire up real agents later.
• Guard against runaway delegation. Self-delegation is blocked. Delegation depth is capped. Working directories are allowlisted. Safe by default.
• Check health in one pass. trinity-lite doctor verifies Python, SQLite, route config, agent config, and publish readiness.
• Zero dependencies. Runtime is Python standard library only. Nothing to install but Python 3.10+.
• 130+ tests guarding the surface area. Mock workflows, safety checks, routing, persistence, MCP, and acceptance gates — all covered.
• Smart model selection. Automatically picks the right LLM for each task. Simple CRUD → cheap model. Architecture design → strong reasoning model. Define your own model pool with tiers and strength tags.

Install

pip install trinity-lite

Python 3.10+. Zero runtime dependencies. Standard library only.

Optional extras

pip install trinity-lite[mcp]           # MCP server — 12 tools + 3 resources
pip install trinity-lite[agent-skill]   # agent-skill-system integration

Workflow example

Hermes routes → Codex implements → Claude Code reviews. Five commands, one audit trail.

# Hermes sends the task. The router picks Codex automatically.
trinity-lite dispatch-auto "implement a rate limiter for the API" --source-agent hermes

# Codex pulls the task and runs it.
trinity-lite worker codex --once --agents agents.local.json

# Claude Code reviews the result.
trinity-lite send claude_code "please review task <task_id>" --source-agent hermes
trinity-lite worker claude_code --once --agents agents.local.json

# Read the full trail.
trinity-lite status <task_id>

Works immediately with mock agents. Ready for real CLIs when you are:

cp examples/agents.command.example.json agents.local.json

MCP server

Turn the task bus into an MCP server. Let any MCP client dispatch, query, and route tasks.

pip install trinity-lite[mcp]
trinity-lite mcp serve

12 tools:

3 resources: trinity://health, trinity://tasks/recent, trinity://tasks/{task_id}

Acceptance Evidence (NEW in v0.5.0)

trinity-lite orchestrate now writes a local acceptance trail to the task row:

• route_json: JSON-encoded route decision used for primary dispatch
• review_task_id and parent_task_id: links between primary work and secondary review
• gate_status: primary_pending, review_pending, review_passed, review_attention, verification_failed, or accepted
• verification_json: JSON-encoded local verifier result, defaulting to trinity-lite doctor
• acceptance_status, acceptance_reason, and accepted_at

If the reviewer reports P0/P1 findings, the flow stops at review_attention. If local verification fails, it stops at verification_failed. accepted_at is written only after the required review and verification pass.

Model Selector (NEW in v0.4.0)

Auto-pick the best LLM for each task based on complexity:

# Auto-detect your available models (zero config)
trinity-lite detect-models

# Or set up interactively (no JSON needed)
trinity-lite setup-models

How it works: Define your model pool with tiers (budget / standard / premium) and strength tags. The selector picks automatically:

Manual call (API usage):

from trinity_lite.model_selector import select_model

result = select_model("Design a rate limiter", task_type="architecture_design")
print(result["model"])  # → gpt-5.5
print(result["reason"]) # → hard_signal:architecture

Custom pool — create ~/.trinity/model_pool.json:

{
  "your-cheap-model": {"tier": "budget", "strengths": ["coding"], "api_type": "anthropic"},
  "your-strong-model": {"tier": "premium", "strengths": ["reasoning", "architecture"], "api_type": "openai"}
}

Works with 1 model, 2 models, or 10 models. No agent names hardcoded.

Links

• PyPI
• Documentation
• Changelog
• Contributing
• Architecture
• Real agent setup

License

MIT