agents-in-a-box — ecosystem architecture

One diagram, the whole box: the ainb Rust TUI and its 11-crate workspace, the JSON-RPC plugin host, fleet orchestration over every live agent session, the portable toolkit that deploys 91 skills and 37 agents to 9+ AI coding tools, and the reflect GraphRAG memory loop that turns transcripts into durable learnings.

1720 × 1150 · inline SVG · no external assets · sourced from the ai-coder-rules monorepo
agents-in-a-box Ecosystem architecture - TUI orchestrator, plugin host, fleet control, portable toolkit, GraphRAG memory 1 - ainb TUI - Rust workspace (11 crates) terminal UI + CLI, single binary, tmux-persistent sessions ainb-core TUI: home - sessions - usage - inbox - code review CLI: run - list - attach - usage - plugin - fleet - doctor Docker Bollard API per-session env Git worktrees branch-per- session isolation tmux PTY attach send-keys Provider adapters claude - codex - gemini - copilot (Provider trait) ~/.agents-in-a-box/ config.toml - favorites.yaml - presets - plugin root crates: core + plugin-protocol / runtime / sdk-rust / testkit / cts-v2 / types + 4 plugin binaries 2 - Plugin host - subprocess runtime manifest v2 discovery from ~/.agents-in-a-box/plugins/ ainb-plugin-runtime spawn - lifecycle FSM - snapshot/action bus - render frames JSON-RPC 2.0 over stdio burndown usage + cost analytics session-reader JSONL parse SQLite cache notifyd notifications inbox feed witr process causality SDK + conformance: protocol - sdk-rust - testkit - cts-v2 (14 axes) 3 - Toolkit - write once, deploy to 9+ tools toolkit/ in the ai-coder-rules monorepo toolkit/packages/ 91 skills - 37 agents - 22 hooks - workflows - knowledge bootstrap.js TOOL_DIR templating external-dependencies.yaml deploy Tool homes (9+) ~/.claude - ~/.codex - ~/.copilot - ~/.gemini hermes - nanoclaw - cursor - amazon q - ... /sync-learnings 4 - Fleet orchestration - ainb fleet drive every agent session on the host discover ainb - peers db - bg jobs merge dedup by cwd read JSONL tail - pane - needs send broker first, tmux fallback verbs: standup - broadcast - sequence - needs - daemon claude-peers broker - HTTP :7899 register - heartbeat - send-message - poll 5 - reflect - GraphRAG memory correct once, never again - cross-tool learnings plugins/reflect (Claude plugin) PreCompact drain - SessionStart recall - /reflect skills ingest reflect-kb CLI (python) nano-graphrag - nano-vectordb - sidecars index - search ~/.claude/global-learnings/ documents/*.md - *.entities.yaml - graph cache recall Live agent sessions tmux panes - Docker containers - git worktrees claude Claude Code codex Codex CLI gemini Gemini CLI copilot Copilot CLI Data on disk ~/.claude/projects/ **/*.jsonl transcripts turns - usage - stop_reason ~/.codex/sessions/ rollout-*.jsonl written by codex CLI ~/.claude-peers.db peer registry (SQLite) ~/.agents-in-a-box/plugins/ manifests + plugin binaries discovered by plugin runtime 6 - Distribution + docs Homebrew tap -> ainb docs/ tree tui - toolkit - plugins - kb Starlight site website/site -> GitHub Pages spawn host fleet verbs spawn - attach write JSONL plugins read transcripts harvest transcripts -> ingest queue peer registry deliver prompt Legend data / control flow write / feedback fleet prompt delivery learning loop (reflect) active component storage / state ai-coder-rules monorepo - ainb-tui v1.5 - toolkit - reflect-kb
Full ecosystem map
Six subsystems, the live agent sessions they orchestrate, and the on-disk state that ties them together. Solid arrows are data/control flow; dashed are writes and feedback; clay is fleet prompt delivery; olive is the learning loop.

How to read it

1ainb TUI — Rust workspace

ainb-core is the single binary: ratatui screens (home, sessions, usage, inbox, code review) plus the CLI (run, list, attach, fleet, plugin, usage). It provisions Docker containers via Bollard, isolates each session in a git worktree, and keeps everything alive in tmux. Provider adapters spawn claude / codex / gemini / copilot behind one trait.

2Plugin host

Plugins are separate subprocess binaries speaking JSON-RPC 2.0 over stdio: burndown (usage + cost analytics), session-reader (JSONL parsing with a SQLite cache), notifyd (inbox feed), witr (process causality). A 14-axis conformance suite (cts-v2) keeps the ABI honest.

3Toolkit

Write a skill once in toolkit/packages/, and bootstrap.js deploys it to every tool home (~/.claude, ~/.codex, ~/.copilot, ~/.gemini, …) with TOOL_DIR templating. /sync-learnings flows user-level edits back into the repo.

4Fleet orchestration

ainb fleet discovers every session on the host (ainb list, the claude-peers SQLite registry, background jobs), merges by cwd, reads state from JSONL tails and tmux panes, then delivers prompts — peers broker (HTTP :7899) first, tmux send-keys fallback. Verbs: standup, broadcast, sequence, needs, daemon.

5reflect — GraphRAG memory

The reflect plugin drains learnings at PreCompact and recalls them at SessionStart. The reflect-kb CLI indexes them into nano-graphrag + nano-vectordb with entity sidecars, all stored under ~/.claude/global-learnings/. Correct once, never again.

6Distribution + docs

The binary ships through a Homebrew tap; the single docs/ tree feeds a Starlight site published to GitHub Pages.

Reading notes