Yomiracle
Local AgentOps control plane for dispatching, routing, orchestrating, and monitoring CLI coding agents.
Dispatch a durable task to a specific agent or let the capability router choose one.
Orchestrate multi-step pipelines or the built-in review/verification flow.
Check task status and list recent task history.
Run one worker cycle or manage background worker daemons.
Run health, configuration, database, and hygiene diagnostics.
Read and send durable inter-agent messages.
Search and load skills from the optional agent-skill-system.
Trinity Lite
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 taggedreview.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.
orchestrateruns 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_codeorcodex. Best of both worlds.Persist everything in SQLite. Tasks, statuses, results, errors, and messages in one local file. Query it with
sqlite3or any tool that speaks SQL.Accept with evidence, not vibes. The review flow records route decisions, review links, verification results, acceptance reasons, and
accepted_atin 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 worktreecreates 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 --oncepulls 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 doctorverifies Python, SQLite, route config, agent config, and publish readiness.trinity-lite doctor --onboardinggrades 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-litePython 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 integrationWorkflow 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.jsontrinity-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 tasksWorktree 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 serve14 tools:
Tool | What it does |
| Dispatch a task to a specific agent |
| Dispatch and let the capability router pick the agent |
| Run the default review flow or a YAML pipeline |
| Get the state and result of any task by ID |
| Recover the latest task submitted by an agent |
| Read a task's full evidence chain as a proof bundle |
| List recent tasks, filterable by agent |
| Run one worker cycle for an agent |
| Start, stop, or inspect a daemon worker |
| Run health and diagnostic checks |
| Read durable messages for an agent |
| Send a message from one agent to another |
| Search agent-skill-system for relevant skills |
| 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 dispatchreview_task_idandparent_task_id: links between primary work and secondary reviewgate_status:primary_pending,review_pending,review_passed,review_attention,verification_failed, oracceptedverification_json: JSON-encoded local verifier result, defaulting totrinity-lite doctoracceptance_status,acceptance_reason, andaccepted_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-modelsHow 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:architectureCustom 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
License
MIT
Available Tools
14 toolstrinity_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_doctorARead-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_latestARead-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_proofARead-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_loadARead-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_skill_searchARead-onlyIdempotent
Search the optional agent-skill-system index for skills relevant to a task or keyword query. Use this before loading a full skill when the exact skill name is unknown; use trinity_skill_load after selecting a result. This is read-only and returns ranked skill metadata, or an installation hint if agent-skill-system is not installed.
Inputs: query (required), limit.
trinity_statusARead-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_tasksARead-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
Scored across 14 tools
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.
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.
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.
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
Related MCP Connectors
MCP-ready hosting provider for Minecraft, BungeeCord, TeamSpeak, VPS and many other game servers.
Cloud-hosted MCP server for URnetwork VPN and Proxy
Related MCP Servers
- MIT
- AlicenseBqualityBmaintenanceBrowserStack's Official MCP Server528,276 npm153AGPL 3.0
- -
- AGPL 3.0