{"id":51319894,"url":"https://github.com/sashabogi/trantor","last_synced_at":"2026-07-01T12:02:17.641Z","repository":{"id":363941620,"uuid":"1263491405","full_name":"sashabogi/trantor","owner":"sashabogi","description":"The hub-world for AI agent crews — orchestrate Claude Code, Codex, Gemini, Kimi \u0026 DeepSeek as live crews with a plan-aware Advisor, a Kanban/flow command center, a testing gate, and an economics brain (Scrooge).","archived":false,"fork":false,"pushed_at":"2026-06-27T04:00:16.000Z","size":1109,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-27T04:03:05.179Z","etag":null,"topics":["agent-crew","ai-agents","claude-code","kanban","llm-routing","mcp","multi-agent","orchestration"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sashabogi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-09T02:17:33.000Z","updated_at":"2026-06-27T04:00:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sashabogi/trantor","commit_stats":null,"previous_names":["sashabogi/trantor"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sashabogi/trantor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sashabogi%2Ftrantor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sashabogi%2Ftrantor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sashabogi%2Ftrantor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sashabogi%2Ftrantor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sashabogi","download_url":"https://codeload.github.com/sashabogi/trantor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sashabogi%2Ftrantor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35005413,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-crew","ai-agents","claude-code","kanban","llm-routing","mcp","multi-agent","orchestration"],"created_at":"2026-07-01T12:02:16.684Z","updated_at":"2026-07-01T12:02:17.619Z","avatar_url":"https://github.com/sashabogi.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n```\n████████╗██████╗  █████╗ ███╗   ██╗████████╗ ██████╗ ██████╗\n╚══██╔══╝██╔══██╗██╔══██╗████╗  ██║╚══██╔══╝██╔═══██╗██╔══██╗\n   ██║   ██████╔╝███████║██╔██╗ ██║   ██║   ██║   ██║██████╔╝\n   ██║   ██╔══██╗██╔══██║██║╚██╗██║   ██║   ██║   ██║██╔══██╗\n   ██║   ██║  ██║██║  ██║██║ ╚████║   ██║   ╚██████╔╝██║  ██║\n   ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝   ╚═╝    ╚═════╝ ╚═╝  ╚═╝\n```\n\n### The hub-world for AI agent crews.\n\n**One Advisor decides how your work runs — solo, cheap inline calls, or a live crew of\nClaude Code, Codex, GLM, Kimi \u0026 DeepSeek in their own terminal windows — routed by your\nactual plans, supervised on a live + historical board you can scroll back through, learning\nfrom every failure.**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)\n![Node](https://img.shields.io/badge/node-%E2%89%A518-339933?logo=node.js\u0026logoColor=white)\n![Agents](https://img.shields.io/badge/crew-Claude%20%C2%B7%20Codex%20%C2%B7%20Gemini%20%C2%B7%20Kimi%20%C2%B7%20DeepSeek-D97757)\n![Tests](https://img.shields.io/badge/tests-80%2F80-2DD4BF)\n\n\u003c/div\u003e\n\n---\n\n## Install\n\n```bash\nnpm install -g trantor\ntrantor setup        # hub becomes an always-on service + config + wires your AI CLIs + doctor\n```\n\nThen give Claude Code (the orchestrator) the plugin:\n\n```bash\nclaude plugin marketplace add sashabogi/trantor\nclaude plugin install trantor\n```\n\nThat's it. (Prefer source? `git clone https://github.com/sashabogi/trantor \u0026\u0026 cd trantor \u0026\u0026\nnpm install \u0026\u0026 bash deploy/setup.sh` — identical result.)\n\n## What gets installed — footprint \u0026 safety\n\nTrantor is a **local-first multi-agent orchestrator with a built-in cost router** — not a cloud\nservice, and not an agent that runs off on its own. Here is *exactly* what the two steps above put\non your machine, so you (or an agent installing it for you) can see the whole footprint up front:\n\n**`npm install -g trantor` + `trantor setup`**\n- The `trantor` CLI — one global npm package.\n- `~/.agent-bus/` — a single local directory holding **all** state: `config.json`, the board data\n  (`bus.json`), and `.env` for any **provider API keys you choose to add** (e.g. `DEEPSEEK_API_KEY`).\n  Nothing in here ever leaves your machine.\n- A local **hub** at `http://127.0.0.1:4477` — **loopback only**, not reachable from the network. On\n  macOS it's a launchd agent (`com.trantor.hub`) so it restarts at login; on Linux you run it yourself.\n- The economics engine (Scrooge) into `~/.local/bin` — the cost ledger and cheap-model router.\n\n**`claude plugin install trantor`** adds, inside Claude Code only:\n- An MCP server (`relay`) exposing the `relay_*` tools, plus the `/trantor:*` skills.\n- Hooks on four events — local Node scripts that only POST to the loopback hub: **SessionStart**\n  (register the session + show the live roster), **PostToolUse** (presence heartbeat + mirror your\n  TodoWrite list onto the board), **PreCompact** (write a handoff before the context window compacts),\n  **SubagentStop** (record each sub-agent's notional cost on the board).\n\n**What it does *not* do:** no cloud, no accounts, no telemetry, nothing phones home; it never uploads\nyour code or keys; it doesn't touch other CLIs' credentials — Codex, Gemini, Kimi and DeepSeek are\nones *you* already installed and signed into, and Trantor just coordinates them locally. The optional\nAPI keys in `~/.agent-bus/.env` are used only to call the cheap models *you* opted into for routing.\n\n**Remove everything, anytime:**\n```bash\nclaude plugin uninstall trantor                  # drop the MCP tools, skills, and hooks\nlaunchctl bootout gui/$(id -u)/com.trantor.hub   # stop the hub service (macOS)\nrm -f ~/Library/LaunchAgents/com.trantor.hub.plist\nrm -rf ~/.agent-bus                              # delete all local state + keys\n```\n\n## What to expect on first run\n\n`trantor setup` ends with the **doctor** — an honest map of where you stand:\n\n```\nTRANTOR DOCTOR\n\ncore\n  ✓ node 22.x\n  ✓ hub up at http://127.0.0.1:4477\nclaude (the orchestrator)\n  ✗ plugin not installed\n      → claude plugin marketplace add sashabogi/trantor \u0026\u0026 claude plugin install trantor\ncrew CLIs (install any subset — seats follow the work)\n  ✓ codex: wired to the bus\n  ✗ codex: NOT authenticated — it will join the bus but fail on its first turn\n      → codex   (sign in with your ChatGPT account on first run)\n  – kimi: not installed (optional)\nthe brain\n  ✗ quota profile not set → trantor profile set claude=max codex=plus deepseek=api\n```\n\nFix the `→` lines (each CLI's own sign-in happens once, in that CLI) and re-run `trantor doctor`\nuntil it's clean.\n\nProvider API keys (e.g. `DEEPSEEK_API_KEY`) live in one file: **`~/.agent-bus/.env`** — the\ncrew runners source it automatically.\n\n## Your first build\n\nOpen Claude Code in the project you want built and say it in plain words:\n\n\u003e **fire up the crew** — build me a 2-player asteroids game with power-ups\n\nAny phrasing works (\"build it with the crew\", \"build this with trantor\"), or invoke the\nskill directly: **`/trantor:crew`**. Claude becomes the architect: it cuts the work into\ndifficulty-tagged packages, asks the Advisor, and shows you the routing table with a\nreal-money estimate **before spending anything**. You say go — terminal windows open, the\nboard fills, and you watch it live:\n\n```bash\ntrantor ui\n```\n\nNo crew CLIs installed yet? It still works — the Advisor routes the work `solo` or to cheap\ninline `scrooge` calls instead of seats. Seats follow the work *and* what's actually installed.\n\nRunning low on context mid-build? Say **`/trantor:handoff`** — a fresh session in the same\nproject takes over with a full window (and a PreCompact hook does this automatically).\n\n## What happens when you fire up a crew\n\n1. **The Advisor moment.** Your Claude cuts the work into difficulty-tagged packages, calls\n   `relay_advise`, and shows you the full picture *before spending anything*: mode\n   (`solo | scrooge | crew | hybrid`), a routing table with a **reason per package**, why\n   that many seats (\"seats follow the work, not the install list\"), and a real-money estimate\n   with quota-pool accounting. You say go.\n2. **Windows open.** `trantor up codex kimi deepseek:deepseek glm:zai-coding-plan` spawns one titled\n   terminal window per agent. `agent:model` pins a model; `agent:provider --difficulty hard`\n   picks the **best live model** for the work at spawn (capability × cost), enumerated from the\n   CLI itself — never a guessed endpoint. **Serialized and then verified on the bus** — the\n   launcher ends with \"crew verified\" or names the no-shows loudly. The orchestrator never gets\n   a green lie.\n3. **Work flows over the bus.** Contracts arrive as messages; each agent owns its own files;\n   coordination happens in \u003c280-char messages you can read on the dashboard. Crew members\n   live under a **runner**: the CLI works one turn and exits, the runner long-polls the bus\n   for free (it's also the heartbeat) and resumes the CLI — with full context — when the next\n   message lands. **Idle agents cost zero tokens and never die.**\n4. **The board tells the truth.** Cards flow `todo → doing → testing → done` — `testing` is a\n   real gate (tests/typecheck run there); failures turn the card **pulsing red** until the\n   orchestrator bounces them back; demoted cards wear an \"↩ bounced\" mark with full history.\n5. **Failures surface in real time.** A crew agent whose turn fails (credits exhausted, auth,\n   crash) no longer re-parks silently — it classifies the failure, posts a ⚠️ to the bus, and\n   flips its dashboard chip **red** (escalating to 🛑 if it keeps failing). `trantor swap \u003cold\u003e\n   \u003cnew\u003e` tears down an exhausted agent and spawns a live-selected replacement, ready for a fresh\n   contract.\n6. **It learns.** Failures become lessons (`relay_lesson`), stored on the hub and **injected\n   into every future crew's prompts** — global or per-CLI. Your crew gets smarter every run.\n\n## The dashboard — `trantor ui`\n\nA live command center at `http://127.0.0.1:4477`, grouped by **project** — and a *durable,\nself-maintaining record*, not just a snapshot. Dead sessions self-prune (no more graveyard of\nstale boards), and the project order is **stable**: a working board updates in place instead of\njumping to the top while you're reading it.\n\nThree views per project (your choice sticks):\n\n- **BOARD** — Kanban with the testing gate, difficulty + model badges per card, agent chips with\n  provider logos, live status, quota-pool tags, and **red / 🛑 chips for errored / down agents**.\n- **FLOW** — a **development timeline**: every card laid left→right in **build order** across\n  **agent lanes**, each card a readable block segmented by the time it spent in each status, with\n  dependency edges converging where parallel work merged. Scroll the project's whole history\n  left/right. **Click any card** to open its full story — the contract it was given, the agent's\n  plan, its build report, the files it changed — reconstructed from that agent's own bus messages.\n- **TIMELINE** — the same history as a chronological event log.\n\nPlus:\n\n- **🧠 Learning sidebar** — the self-learning loop, made visible: lessons (global / per-agent /\n  per-project), **per-LLM reliability** (turns, fail-rate, trend charts) from real turn telemetry,\n  and the guardrails baked into each model's prompts. Watch the platform get smarter over time.\n- **🪙 savings pill** — a lifetime running total of what cheap-model routing has saved vs running\n  the frontier model, with a selectable window (24h / week / month / quarter / year).\n- **Per-project conversation lanes** — watch agents negotiate interfaces in context — plus a\n  global live feed and a composer so *you* can message the bus (or any single agent).\n\nEvery session registers automatically — **crew or not** — and a solo session's own todo list\nshows up on the board as cards, so the dashboard reflects *all* the work on a project, not just\ncrew runs.\n\n## The brain — plan-aware economics\n\nTrantor's economics engine ([Scrooge](https://github.com/sashabogi/token-scrooge) — installed\nautomatically by `trantor setup`) knows model capabilities, per-1M costs, and keeps the\nledger; Trantor turns that into decisions:\n\n- **Declare your plans once:** `trantor profile set claude=max codex=plus zai=coding-plan kimi=coding-plan deepseek=api`\n- The Advisor routes by **your economics**: API-billed orchestrator → offload everything;\n  $20-tier plan → the crew *is* the only way a real build fits; max-tier → context horizon\n  decides. **Quota pooling**: one build spread across your separate subscription buckets —\n  measured example: a five-vendor 3D game build, API-equivalent $200–600, **actual spend $2.29**.\n- **Fractal delegation** (`relay_scrooge`): the architect *and* crew members push stateless\n  grunt work to cheap models, with ledger receipts.\n\n## Context handoff — sessions that never hit the wall\n\nA PreCompact hook writes a rich handoff before Claude Code compacts; a fresh session in the\nsame project **takes over with a brand-new full context window**. Works manually from any\nagent via `relay_handoff`. Optional macOS auto-prompt (`autoHandoffPrompt` in\n`~/.agent-bus/config.json`) offers to open the fresh session for you, with a timeout.\n\nWhy crews never exhaust the orchestrator: bus messages are **by reference** (~70 tokens),\nwork products stay in each agent's own context — the orchestrator burns at coordination\nrate, not work rate.\n\n## The tools (MCP — every agent on the bus gets these)\n\n| Tool | What it does |\n|---|---|\n| `relay_advise(task, packages, horizon?)` | **The Advisor** — mode + reasoned per-package routing + cost estimate + ready-to-use card args |\n| `relay_send(to, text)` / `relay_inbox` / `relay_wait(t)` | Live messaging: direct, read-new, long-poll wake |\n| `relay_peers` / `relay_status(text)` / `relay_whoami` | Presence: who's alive (honest, heartbeat-backed), doing what |\n| `relay_project_brief(text)` | The project's what/why on the dashboard |\n| `relay_task_add(title, …, difficulty, model, deps, project?)` | Cards with difficulty/model badges + DAG edges; `project` targets another board when you orchestrate from elsewhere |\n| `relay_task_move(id, status)` | `todo → doing → testing → done` (the gate), `failed`, `blocked` |\n| `relay_board` | The project's full board, as text |\n| `relay_scrooge(prompt, task?, difficulty?)` | Fractal cheap-model delegation, with the ledger receipt |\n| `relay_lesson(text, scope?)` | Record a failure lesson — auto-injected into all future crews |\n| `relay_handoff(summary)` | Full-window session succession |\n\n## The CLI\n\n```\ntrantor setup | doctor | connect | profile | up \u003cagents…\u003e | swap \u003cold\u003e \u003cnew\u003e | down | ui | advise | hub | watch\n```\n\n`trantor up` notes: `agent:model` pins a model (`deepseek:deepseek-v4-pro`); `agent:provider\n--task \u003ck\u003e --difficulty \u003cd\u003e` picks the **best live model** for the work at spawn\n(`glm:zai-coding-plan --difficulty hard`); spawns are verified on the bus with one retry;\ngeometry auto-detects the screen you're working on (`CREW_RECT=\"X,Y,W,H\"` to override). `trantor\nswap \u003coldAgent\u003e \u003cnewSpec\u003e` replaces an exhausted agent with a live-selected one. `trantor down`\nkills crew processes via their ttys and closes windows without macOS \"Terminate?\" dialogs.\n\n## Works with any MCP agent\n\nClaude Code, Codex CLI, Gemini CLI, Kimi Code CLI, OpenCode (DeepSeek) are wired by\n`trantor connect` automatically (idempotent, backed-up, never overwrites your customizations).\nAnything else that speaks MCP: point it at `mcp.mjs` with `RELAY_AGENT=\u003cbrand\u003e` — loading the\nserver auto-registers the session, so presence works before the model says a word.\n\n## How it works\n\n```\n Claude (architect/plugin)   codex ─ runner   gemini ─ runner   kimi ─ runner   deepseek ─ runner\n        │ advise/contracts        │ one turn, exit; runner long-polls (free) + resumes with context\n        └───────────┬─────────────┴──────────────┴────────────────┴────────────────┘\n                    ▼\n              hub.mjs  ←— plain HTTP + SSE · presence/messages/board/history/lessons/learning/economics\n              (Node built-ins only · state in ~/.agent-bus/bus.json · loopback by default)\n                    ▲\n              dashboard (ui.html) · BOARD/FLOW/TIMELINE · 🧠 Learning · 🪙 savings · conversation lanes\n```\n\nConfig: `RELAY_URL` env → `~/.agent-bus/config.json` → `http://127.0.0.1:4477`.\nIdentity: `RELAY_SESSION` → `RELAY_AGENT:\u003cproject-folder\u003e` → `\u003chostname\u003e:\u003cproject-folder\u003e`.\n\n**Local-first and safe:** the hub binds loopback; no accounts, no cloud, no exposure. An\nalways-on/remote hub (private tailnet, or public with auth) is on the roadmap — never expose\nthe hub publicly without auth.\n\n*Heritage note: Trantor grew out of **agent-bus**. As of v0.17 the plugin and skills are\nnamed `trantor` (formerly `agent-bus` — if you installed before v0.17:\n`claude plugin uninstall agent-bus \u0026\u0026 claude plugin marketplace update \u0026\u0026 claude plugin install trantor`).\nThe `relay_*` tool names and the `~/.agent-bus` state dir remain until a later release.*\n\n## Honest limits\n\n- You can't interrupt an agent **mid-turn**; messages land when its current turn ends (idle\n  agents wake instantly via their runner).\n- Window spawning is macOS (Terminal.app); on Linux the launcher prints per-agent commands\n  to run in your own terminals. Hub/MCP/dashboard are cross-platform.\n- The hub is deliberately tiny (in-memory + JSON file) — a coordination bus, not a message queue.\n- Each CLI's sign-in is its own (ChatGPT, Google, Kimi accounts) — the doctor detects state\n  and names the fix, but can't log in for you.\n\n## Tests\n\n```bash\nnpm test    # 80 checks: unit + protocol-level scenario drills with mock agents (no LLMs, seconds, $0):\n            # honest presence + TTL prune, spawn no-shows, the testing gate, bounce trails, lessons,\n            # /history + backfill, /learning shape, /todos sync, /card detail, advisor decisions across\n            # plan tiers, deps validation, virgin-machine doctor, and failure-classification drills\n```\n\n## License\n\n[MIT](./LICENSE) © 2026 Sasha Bogojevic · Built with [Claude Code](https://claude.com/claude-code) ·\nBrain by [Scrooge](https://github.com/sashabogi/token-scrooge)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsashabogi%2Ftrantor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsashabogi%2Ftrantor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsashabogi%2Ftrantor/lists"}