Skip to main content
Glama

Trinity Lite

Tests Python 3.10+ License: MIT Release PyPI Yomiracle/trinity-lite MCP server

Local AgentOps for cross-vendor CLI coding agents. Route work, recover state, and accept only with evidence.

Trinity Lite is a local control plane for Codex, Claude Code, Hermes, and custom CLI agents. It connects the tools you already use; it does not ask you to rebuild them inside another framework.

中文 README · Docs · Why Trinity Lite? · Recipes

The problem

You already use more than one capable coding agent. The hard part is no longer starting another agent; it is preserving task truth across tools, recovering after a client disconnects, preventing duplicate work, and deciding when a result is actually accepted. Trinity Lite is that local operations layer.

Related MCP server: BrowserStack MCP server

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.

  • Review, verify, then accept. orchestrate runs primary work, routes the required review, runs local verification, and writes acceptance evidence back to SQLite.

  • Block footguns before they fire. Self-routes become explicit local-work decisions instead of creating loops. Delegation depth has a hard cap. Working directories must be in the allowlist.

Quick start

30 seconds, no agents required:

pip install trinity-lite
trinity-lite doctor
trinity-lite orchestrate "implement a hello-world function"

Mock agents are built in. You see the full route → work → review → verify → accept cycle before you wire up anything real.

Not another framework

Trinity Lite does not build agents. It operates the agents you already have.

LangGraph and CrewAI give you primitives for building agents from scratch — graph definitions, role abstractions, and tool wrappers. Trinity Lite starts from the opposite end: Claude Code is running in one terminal, Codex is running in another, and their work needs reliable handoff, recovery, independent review, and an acceptance trail. No new agent abstraction. Just local AgentOps for the CLIs you already use.

Who this is for

You are...

Trinity Lite helps you...

An advanced solo developer using two or more agent CLIs

Replace manual terminal handoffs with one durable workflow and evidence trail

A small AI-native engineering team

Separate implementation, review, verification, and acceptance without deploying a control server

A local-first or privacy-sensitive developer

Keep task state in an inspectable SQLite database on your machine

An agent-tool integrator

Connect existing CLIs through a neutral bus and MCP surface

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.

  • Export proof bundles. trinity-lite proof <task_id> writes one task's route, result, review, verification, and acceptance evidence as a portable JSON bundle and a human-readable Markdown summary. Missing stages are marked explicitly, never fabricated.

  • Isolate agent code edits with git worktrees. Released as a v0.6 preview: trinity-lite worktree creates managed branches and checkouts, records the base commit, and returns diff evidence without touching your main checkout.

  • 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. trinity-lite doctor --onboarding grades every check as blocker or optional, probes for agent CLIs, and fails only on blockers.

  • Zero core dependencies. The default runtime is Python standard library only. YAML pipelines are available through an optional extra.

  • 150+ tests guarding the surface area. Mock workflows, safety checks, routing, persistence, MCP, and acceptance gates — all covered.

  • Optional model selection hints. Select from your declared model pool with transparent task, tier, and capability rules; no claim of a universal best or cheapest model.

Install

pip install trinity-lite

Python 3.10+. Zero core runtime dependencies. Standard library only unless an optional extra is installed.

Optional extras

pip install "trinity-lite[yaml]"          # YAML pipeline files
pip install "trinity-lite[mcp]"           # MCP server — 14 tools + 3 resources
pip install "trinity-lite[agent-skill]"   # agent-skill-system integration

Workflow example

Route primary work → run the worker → run the reviewer → verify → accept. One command, one audit trail.

trinity-lite orchestrate "implement a rate limiter for the API"

The primary task row records route_json, review_task_id, verification_json, acceptance_status, acceptance_reason, and accepted_at.

Ready for real CLIs when you are — auto-detect what is installed and generate a safe starter config:

trinity-lite init
trinity-lite orchestrate "implement a rate limiter for the API" --agents agents.local.json

trinity-lite init probes PATH for Codex, Claude Code, and Hermes, writes agents.local.json with JSON-array commands for the CLIs it finds, keeps the rest in mock mode, and never writes credentials or overwrites an existing config without --force. Prefer hand-editing? cp examples/agents.command.example.json agents.local.json still works.

Prefer manual control? Use the lower-level bus commands:

trinity-lite dispatch-auto "implement a parser"
trinity-lite worker codex --once
trinity-lite tasks

Worktree Preview

This is a v0.6 preview. It manages isolated worktree lifecycle and diff evidence while keeping automatic merge-back out of scope.

Create an isolated checkout for an agent:

trinity-lite worktree create "fix parser bug" --repo . --agent codex
trinity-lite worktree list
trinity-lite worktree diff <task_id>
trinity-lite worktree cleanup <task_id>

Worktree preview records branch, base commit, path, agent id, task id, and diff evidence. It does not merge branches or delete branches by default. See Worktree Parallelism Preview.

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

14 tools:

Tool

What it does

trinity_dispatch

Dispatch a task to a specific agent

trinity_dispatch_auto

Dispatch and let the capability router pick the agent

trinity_orchestrate

Run the default review flow or a YAML pipeline

trinity_status

Get the state and result of any task by ID

trinity_latest

Recover the latest task submitted by an agent

trinity_proof

Read a task's full evidence chain as a proof bundle

trinity_tasks

List recent tasks, filterable by agent

trinity_worker

Run one worker cycle for an agent

trinity_worker_daemon

Start, stop, or inspect a daemon worker

trinity_doctor

Run health and diagnostic checks

trinity_inbox

Read durable messages for an agent

trinity_send

Send a message from one agent to another

trinity_skill_search

Search agent-skill-system for relevant skills

trinity_skill_load

Load the full content of a named skill

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

If an MCP client disconnects or times out before it displays the task id, call trinity_latest for the source agent, then call trinity_status with the returned primary task id. By default trinity_latest skips secondary review children so recovery lands on the user-facing task.

Acceptance Evidence

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.

Proof Bundles

Export one task's full evidence chain as portable files:

trinity-lite proof <task_id>                 # JSON + Markdown into the current directory
trinity-lite proof <task_id> --out bundles/  # choose an output directory
trinity-lite proof <task_id> --format json   # or: md, both (default)

The JSON bundle carries a proof_bundle_version field for schema evolution; the Markdown file summarizes each stage and ends with a timeline table. Stages that were never recorded are exported as explicit nulls and marked "Not recorded" — never fabricated. See Proof Bundles.

Optional Model Selector

Select from a model pool you control using task complexity and declared capabilities. This is a transparent routing helper, not a universal cost optimizer:

# 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:

Task

→ Tier

→ Model

"Fix typo in README"

budget

cheap model

"Add search endpoint"

budget

cheap model

"Refactor auth module"

standard

mid-tier

"Design microservice architecture"

premium

strongest

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"])  # → a premium model from your configured pool
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.

License

MIT

Available Tools

14 tools
trinity_dispatchA

Create a durable task for one explicit Trinity agent and run one worker cycle for that agent. Use this when the caller already knows the target agent; use trinity_dispatch_auto when routing should choose the agent. This writes to the local task database and may execute the configured agent command; with wait=true it returns the final compact task or a timeout error.

Inputs: task (required), target_agent (required), cwd, wait, +3 more.

trinity_dispatch_autoA

Resolve the best Trinity agent with the local route table, create a durable task, and run one worker cycle. Use this when the caller has a task but should not pick the agent manually; use trinity_dispatch for an explicit target. This writes route evidence and task state to the local database and may execute the selected agent command; the result includes compact task and route metadata.

Inputs: task (required), cwd, wait, task_type, +3 more.

trinity_doctorA
Read-onlyIdempotent

Run Trinity Lite health, configuration, database, publish-readiness, and runtime hygiene checks. Use this before release, after setup changes, or when routing and worker behavior looks wrong. This is read-only: it scans configured files, database state, optional repository roots, and retired ports, then returns a structured health report.

Inputs: scan_root, runtime_root, retired_ports.

trinity_inboxA

Read durable inter-agent messages addressed to one agent from the local Trinity database. Use this to recover completed work, review notes, or follow-up messages; use trinity_send to create a new message. By default it reads unread messages, but mark_read=true updates message read state; it returns message records.

Inputs: agent (required), limit, mark_read, unread_only.

trinity_latestA
Read-onlyIdempotent

Recover the newest task submitted by one source agent when the task id is unknown. Use this after an interrupted MCP wait or lost client response, then call trinity_status for the returned primary task id. By default it skips secondary review children so the returned task is the user-facing parent; set include_reviews=true to inspect review tasks.

Inputs: agent (required), include_reviews.

trinity_orchestrateA

Run a multi-step Trinity workflow from a pipeline file or the built-in implement-then-review flow. Use this for work that needs sequencing, review gates, or multiple task records; use dispatch tools for a single agent task. This creates and updates local task records and may execute one or more configured agent commands; it returns pipeline or review-flow evidence.

Inputs: task (required), cwd, wait, pipeline, +4 more.

trinity_proofA
Read-onlyIdempotent

Read one task's full evidence chain as a structured proof bundle: route, work result, review, verification, acceptance, and a stage timeline. Use this to audit or export why a task was accepted or blocked; stages without recorded evidence are returned as explicit nulls. This is read-only and does not write files or run workers; use the trinity-lite proof CLI command to write JSON and Markdown bundle files.

Inputs: task_id (required).

trinity_sendA

Write a durable message from one Trinity agent to another agent's inbox. Use this for follow-up context, review handoffs, or task-linked notes; use trinity_dispatch to create executable work. This writes to the local message database, does not run a worker, and returns the stored message record.

Inputs: message (required), target_agent (required), task_id, source_agent.

trinity_skill_loadA
Read-onlyIdempotent

Load the full SKILL.md, memory, schema, keywords, and generated system prompt for one exact skill name. Use this after trinity_skill_search identifies the correct skill; do not use it for broad discovery. This is read-only and returns the skill bundle, or a not-found response with available skill names when possible.

Inputs: skill_name (required).

trinity_statusA
Read-onlyIdempotent

Read the current state, result, route evidence, and acceptance metadata for one task id. Use this after dispatch or orchestration to poll progress or recover a result after a timeout. This is read-only and does not run workers or mark messages as read; it returns a compact task object or task-not-found error.

Inputs: task_id (required).

trinity_tasksA
Read-onlyIdempotent

List recent durable task records, optionally filtered by source or target agent. Use this to inspect queue history or find a task id before calling trinity_status. This is read-only, does not run workers, and returns compact task objects in recent-first order.

Inputs: agent, limit.

trinity_workerA

Run one local worker cycle for a named agent and process one queued task if available. Use this to manually drain the queue or retry a specific queued task; use trinity_worker_daemon for a background worker. This may execute the agent command and update task state; it returns no_task or the compact processed task.

Inputs: agent (required), task_id.

trinity_worker_daemonA

Start, stop, or check the local background worker process for one agent. Use status for a process check, start to keep an agent queue draining, and stop to terminate that daemon. Start and stop modify local process state and PID files; responses include running, started, stopped, pid, and pid_file fields.

Inputs: agent (required), action (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 14 tools

    Disambiguation5/5

    Each tool targets a distinct operation within the Trinity workflow: orchestration, dispatch (explicit vs auto), worker processing (foreground vs daemon), task inspection (status/latest/proof/tasks), messaging, health, and skills. Descriptions explicitly cross-reference alternatives and specify when to use one over another, leaving no material ambiguity.

    Naming Consistency5/5

    All tool names use the same trinity_ prefix and lowercase snake_case, with clear suffixes for variants (dispatch_auto, worker_daemon, skill_search/load). Although some names are noun-based read operations and others are verb-based actions, the convention is uniform and predictable.

    Tool Count5/5

    The 14 tools are well-scoped for a multi-agent orchestration server, covering dispatch, orchestration, inspection, workers, messaging, health, and skills without obvious bloat. Each tool appears to earn its place by serving a specific workflow role.

    Completeness4/5

    Core task, worker, message, and skill-discovery workflows are well covered, including create/read/update-adjacent operations and evidence auditing. Minor gaps remain, such as no explicit task cancellation/deletion or agent/route table listing, but agents can work around these for most workflows.

    Maintenance

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers