Trinity Lite

Local-first multi-agent workflow infrastructure for CLI-based AI agents.

Trinity Lite gives Codex, Claude Code, Hermes, Qwen, Gemini, Aider, and any CLI-based agent a shared task bus: route work, persist state in SQLite, run workers, capture results, and inspect the whole workflow from the command line.

中文 README

Why Trinity Lite

AI coding agents are powerful on their own, but multi-agent work is often still coordinated by hand:

Trinity Lite turns "several AI tools on one machine" into a small, reproducible agent workflow layer.

Who It Is For

30-Second Demo

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

The default agents are mock agents, so this demo works even if Codex, Claude Code, or Hermes are not installed.

How It Works

                  +----------------+
user task ------> | router         |
                  +-------+--------+
                          |
                          v
                  +-------+--------+
                  | SQLite task bus|
                  +-------+--------+
                          |
          +---------------+----------------+
          v                                v
   +------+-------+                 +------+-------+
   | Codex worker |                 | review worker|
   +------+-------+                 +------+-------+
          |                                |
          v                                v
   agent adapter                    agent adapter
          |                                |
          +---------------+----------------+
                          v
                  status / result / inbox

Codex, Claude Code, and Hermes are default presets, not requirements. Roles are configurable:

Core Capabilities

• Routing: resolve task types to explicit agents or agents selected by declared capabilities.
• Durable bus: store tasks, status, results, errors, and messages in SQLite.
• Worker model: pull queued tasks and execute mock agents or real local CLIs.
• Command adapters: connect Codex, Claude Code, Hermes, Qwen, Gemini, Aider, or any CLI through JSON-array commands.
• Local health checks: verify Python, SQLite, route config, agent config, publish readiness, and optional runtime hygiene.
• Safety boundaries: block self-delegation, cap delegation depth, enforce allowed working directories, and scan public trees.

Technical Highlights

• Zero runtime dependencies: standard-library Python package.
• SQLite-first state: local, inspectable, transactional task storage.
• Shell-safe command execution: command adapters use JSON arrays and shell=False.
• Mock-to-real upgrade path: run the full demo before installing real agent CLIs.
• Capability routing: agents can declare roles, capabilities, and priority for name-agnostic routing.
• CI-backed public release: tests, compile checks, doctor checks, and a PyPI publish workflow run in GitHub Actions.
• Designed for extension: orchestrator ships in v0.1.x for primary task plus review flows; MCP server is planned as an optional layer.

Product Positioning

Trinity Lite sits between "single-agent CLI tools" and "full agent frameworks":

Codex / Claude Code / custom CLI
        |
        v
Trinity Lite: route -> bus -> worker -> result
        |
        v
future layers: MCP server, orchestrator, tracing, dashboard

It does not try to replace agent frameworks. It provides a lightweight coordination layer for the AI tools developers already use.

Quick Start

python3 -m pip install trinity-lite

# Run a local health check
trinity-lite doctor

# Dispatch a task using the built-in route resolver
trinity-lite dispatch-auto "implement a hello-world function"

# Run one mock Codex worker cycle
trinity-lite worker codex --once

# Check recent tasks
trinity-lite tasks

Upgrading

python3 -m pip install --upgrade trinity-lite

Trinity Lite follows semantic versioning. Patch releases (0.1.x) are backward-compatible and require no configuration or data migration. Check your version:

trinity-lite doctor
# or
python3 -m pip show trinity-lite | grep Version

See CHANGELOG.md for what changed between versions.

Quick Start (from source)

git clone https://github.com/Yomiracle/trinity-lite.git
cd trinity-lite
python3 -m pip install -e .

# Run a source-tree health check
trinity-lite doctor --scan-root .

# Dispatch a task using the built-in route resolver
trinity-lite dispatch-auto "implement a hello-world function"

# Run one mock Codex worker cycle
trinity-lite worker codex --once

# Check recent tasks
trinity-lite tasks

Use Real Agent Commands

Copy the command example and edit it for your machine:

cp examples/agents.command.example.json agents.local.json
trinity-lite dispatch-auto "write a unit test"
trinity-lite worker codex --once --agents agents.local.json

Agent commands are configured as JSON arrays and run with shell=False.

See docs/REAL_AGENTS.md for Codex, Claude Code, and generic CLI examples.

For name-agnostic routing, copy the generic capability examples:

cp examples/agents.generic.example.json agents.local.json
cp examples/routes.capabilities.example.json routes.local.json
trinity-lite dispatch-auto "fix the parser bug" --agents agents.local.json --routes routes.local.json

Roadmap

• v0.1.x: harden the public local bus, docs, examples, tests, and orchestrator.
• v0.2: add a minimal MCP server so AI clients can call Trinity Lite directly.
• v1.0: stabilize CLI, schema, and packaging.

See ROADMAP.md.

Core Commands

trinity-lite route "review this patch" --previous-agent codex
trinity-lite dispatch codex "implement X"
trinity-lite dispatch-auto "audit this project"
trinity-lite status <task_id>
trinity-lite tasks
trinity-lite worker codex --once
trinity-lite send claude_code "please review task abc"
trinity-lite inbox claude_code
trinity-lite orchestrate "implement X"
trinity-lite doctor --scan-root .

For long-running local installs that maintain a metrics log, add runtime hygiene checks:

trinity-lite doctor --runtime-root ~/.trinity-lite --retired-port 9797

Architecture

See docs/ARCHITECTURE.md.

Project Docs

• Trinity Lite tutorial
• Real agent command setup
• Agent capabilities
• Product positioning
• Operations guide
• Security notes
• Roadmap
• Changelog
• Contributing

License

MIT