╔═══════════════════════════════════════════════════════════════╗
   ║                                                               ║
   ║     █████╗  ██████╗ ███████╗███╗   ██╗████████╗███████╗       ║
   ║    ██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝██╔════╝       ║
   ║    ███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║   ███████╗       ║
   ║    ██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║   ╚════██║       ║
   ║    ██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║   ███████║       ║
   ║    ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚══════╝       ║
   ║              ██╗███╗   ██╗    █████╗                              ║
   ║              ██║████╗  ██║   ██╔══██╗                             ║
   ║              ██║██╔██╗ ██║   ███████║                             ║
   ║              ██║██║╚██╗██║   ██╔══██║                             ║
   ║              ██║██║ ╚████║   ██║  ██║                             ║
   ║              ╚═╝╚═╝  ╚═══╝   ╚═╝  ╚═╝                             ║
   ║            ██████╗  ██████╗ ██╗  ██╗                              ║
   ║            ██╔══██╗██╔═══██╗╚██╗██╔╝                              ║
   ║            ██████╔╝██║   ██║ ╚███╔╝                               ║
   ║            ██╔══██╗██║   ██║ ██╔██╗                               ║
   ║            ██████╔╝╚██████╔╝██╔╝ ██╗                              ║
   ║            ╚═════╝  ╚═════╝ ╚═╝  ╚═╝                              ║
   ║                                                               ║
   ╚═══════════════════════════════════════════════════════════════╝

A complete ecosystem for AI-assisted development

115 Rust Modules · 91 Skills · 37 Agents · 9 AI Tools · Knowledge Graph

A terminal-native ecosystem for managing AI coding agents. Built around a Rust TUI that orchestrates Claude Code, Codex, Gemini, and Copilot sessions with git worktree isolation, and a portable toolkit of skills, agents, and workflows that plug into 9 different AI coding tools.

The portable skills, the bootstrap.js installer, and the catalog live in a separate, standalone repo — ainb consumes it as a pinned external source.

Live dashboard: multi-workspace sidebar, session preview pane, and tmux-backed persistent sessions

Burndown dashboard: daily activity, per-project & per-model breakdowns, top sessions, live budget tracking, and optimisation hints — all in one view

Most AI coding setups are a loose collection of dotfiles. This project treats the problem as an engineering system:

• One toolkit, many tools — Write a skill once, deploy it to Claude Code, Codex, Gemini, Cursor, Copilot, Amazon Q, Cline, Roo, or Clawdhub
• Session isolation — Each coding session gets its own git worktree and tmux session. No cross-contamination
• Agents that compose — 37 specialized agents (backend-developer, security-agent, architecture-reviewer, etc.) that can be orchestrated into swarms
• Memory that persists — A two-tier knowledge system (GraphRAG + QMD) that captures learnings and retrieves them across sessions and projects
• Production Rust — The TUI isn't a shell script. It's 115 modules of typed, tested, async Rust with clippy pedantic/nursery lints

# Install the TUI (macOS / Linux)
brew tap stevengonsalvez/agents-in-a-box && brew install ainb
# newer Homebrew gates third-party taps — if it says "untrusted tap", run:
#   brew trust stevengonsalvez/agents-in-a-box

# Seed the manifest from the toolkit and deploy units into your tool home.
# The toolkit is a separate repo — clone it, then point --toolkit-root at it.
git clone https://github.com/stevengonsalvez/ainb-toolkit.git
ainb migrate --from-bootstrap --toolkit-root ./ainb-toolkit
AINB_USE_REAL_HOMES=1 ainb migrate --clean --backup --yes

# Launch the TUI
ainb

A Rust-based terminal application for managing AI coding sessions with git worktree isolation, model selection, and persistent tmux sessions. Every operation is available as both an interactive TUI view and a scriptable CLI subcommand with JSON output — so humans drive it from a dashboard and agents drive it from shell scripts.

• Multi-provider — Run Claude Code, Codex CLI, Gemini CLI, or GitHub Copilot in the same workflow, with Sonnet / Opus / Haiku selection per session
• Git worktree isolation — Each session runs in its own branch and working directory. No cross-contamination, no stash dance
• tmux persistence — Sessions survive terminal disconnects, SSH drops, and laptop sleep. Reattach any time
• Usage analytics — Built-in token + session tracking by day, week, provider, and project. Know where your budget went
• Easy onboarding — First-run setup wizard checks dependencies, configures auth, and gets you creating sessions in minutes
• Live log streaming — Real-time viewer with level filtering and search across all running sessions
• Scriptable CLI — 30+ commands (every TUI action, plus headless witr, learnings search, diff-review --format json, …) with --format json output for every piece of state. 📘 Full CLI reference → — a generated, multi-hierarchy man page covering every subcommand.

📊 Unified dashboard Sidebar navigation across Agents, Catalog, Sessions, Recovery, Logs, Stats, Skills, Changelog, and Setup. Keyboard-driven throughout.	🤖 Pick your agent, pick your model Choose between Claude Code, Shell Only, SSH, Codex CLI, Gemini CLI, GitHub Copilot, or Kiro. Model toggle — Sonnet · Opus · Haiku — right below.
🚀 Start a session any way you want Local repo, clone from GitHub/GitLab, SSH into a remote box, or pull from your Favorites. One-key shortcuts: L / R / S / F.	🛠️ Guided first-time setup Re-run the wizard, verify dependencies, configure git paths, set auth, pick your editor — or factory-reset in one click.
📈 Burndown analytics, built in Multi-panel dashboard: daily activity, top sessions, per-project + per-model token attribution, live budget tracking, and inline optimisation hints.	🎯 Per-project attribution See exactly which repos and worktrees consume your context budget. Input, cache, output, and session counts per project.
🔍 Warp-style Code Review diff Press g on a session (or run ainb diff-review) for a cohesive review surface — file sidebar, per-file collapsible blocks in one scroll, Dracula syntax highlighting, word-level intra-line emphasis, a line-number gutter with green/red change bars, expandable context, and n/N hunk navigation. Docs →

For agents, automation, and scripts, ainb ships a full CLI. Every command supports --format json for piping to jq.

ainb --help                             # Top-level overview
ainb run --repo . --worktree --tool claude --model sonnet
ainb list --format json | jq .
ainb logs my-session --follow
ainb recover list                       # Find orphaned sessions
ainb config set authentication.default_model opus
ainb completion zsh > ~/.zsh/completions/_ainb

20 top-level commands — tui, run, list, logs, attach, status, kill, auth, recover, config, git, favorites, init, presets, usage, claudecode, completion, plugin, fleet, help — with nested subcommands for recover / config / git / favorites / presets / plugin / fleet.

📘 Full CLI reference → docs/tui/cli.md

Recommended — Homebrew (macOS / Linux):

brew tap stevengonsalvez/agents-in-a-box
brew install ainb

Newer Homebrew versions refuse formulas from untrusted third-party taps. If brew install/brew upgrade errors with "Refusing to load formula … from untrusted tap", trust the tap once and retry: brew trust stevengonsalvez/agents-in-a-box

The tap lives at stevengonsalvez/homebrew-agents-in-a-box and is auto-updated by the release workflow on every tagged release — brew upgrade ainb always pulls the latest.

curl -fsSL https://raw.githubusercontent.com/stevengonsalvez/agents-in-a-box/main/ainb-tui/install.sh | bash

cargo install --git https://github.com/stevengonsalvez/agents-in-a-box --branch main ainb

wsl --install                                                                         # 1. Install WSL2
# Inside Ubuntu/Debian:
curl -fsSL https://raw.githubusercontent.com/stevengonsalvez/agents-in-a-box/main/ainb-tui/install.sh | bash
sudo apt update && sudo apt install -y tmux
ainb

sudo rm -rf /Library/Developer/CommandLineTools
sudo xcode-select --install

brew untap stevengonsalvez/ainb   # only if you tapped this earlier
brew install stevengonsalvez/agents-in-a-box/ainb

brew trust stevengonsalvez/agents-in-a-box
brew install ainb   # or brew upgrade ainb

ainb boots a plugin host at startup. Some screens — notably Analytics / Usage (the burndown dashboard) — are provided by subprocess plugins that the host discovers and loads automatically. All plugins are enabled by default; you only need the controls below to turn them off or scope which ones load.

How it works (in brief): a v2 plugin is a native subprocess that speaks JSON-RPC 2.0 over Content-Length-framed stdio — no wasm, no in-process linking. The host (ainb-core) discovers each plugin from dist/plugins/<id>/, spawns it, and exchanges messages: plugin/render (the plugin returns a WireBuffer of cells the host blits), plugin/handle_key, plugin/cli_dispatch (routes ainb <namespace> …), plus reverse host/snapshot/publish calls over an event bus. Each plugin declares its [capabilities] in manifest.toml; the runtime denies any ungranted host call with JSON-RPC -32001. A plugin screen can render two ways: in-process via a WireBuffer (host owns the terminal — e.g. burndown), or as a host-embedded foreign TTY where ainb suspends and hands the terminal to an external interactive program (e.g. witr's witr -i browser). Full walkthrough: docs/plugins/.

There are four ways to filter plugins, with the following precedence (most specific wins):

Resolution order: AINB_DISABLE_PLUGINS → AINB_ONLY_PLUGINS → AINB_DISABLE_PLUGIN → config enabled → config disabled → default all-on. Env always beats config, and an allowlist always beats a denylist.

Config lives at ~/.agents-in-a-box/config/config.toml under a [plugins] table — see example.config.toml for the annotated block. When a screen's plugin is disabled, the TUI shows a placeholder naming the exact variable that turned it off, rather than hanging.

• tmux — persistent session management
• git — worktree operations
• Claude Code CLI — the claude command

Why the asymmetry: only Anthropic publishes rate-limit windows over OAuth, and only the Claude Code CLI exposes them to statusline hooks. Wiring ainb claudecode statusline brings the OAuth-grade signal into ainb-tui's Burndown panel and session-window top bar.

A portable AI coding agent toolkit: skills, agents, workflows, and configurations that deploy to 9 different AI coding tools from a single source.

Full toolkit documentation → stevengonsalvez/ainb-toolkit

Skills are reusable capabilities that any supported AI tool can invoke.

Specialized AI agents organized by domain. Each agent has a defined persona, tool access, and area of expertise.

A two-tier learning system that captures insights during development and retrieves them across sessions and projects.

The /reflect skill captures learnings. The /research and /prime skills retrieve them. The reflect Python library (installed as the reflect CLI) manages the knowledge base directly — it lives in its own repo, stevengonsalvez/ainb-reflect-memory, and installs via uv tool install --upgrade 'git+https://github.com/stevengonsalvez/ainb-reflect-memory.git[graph]'.

How the knowledge system works →

agents-in-a-box/
│
├── ainb-tui/                   # Rust Cargo workspace
│   ├── crates/
│   │   ├── ainb-core/          #   TUI application (app, components, tmux, git, claude, config)
│   │   ├── ainb-plugin-runtime/        #   Plugin host runtime
│   │   ├── ainb-plugin-protocol/       #   Plugin JSON-RPC protocol
│   │   ├── ainb-plugin-sdk-rust/       #   Rust plugin SDK
│   │   ├── ainb-plugin-types-sessions/ #   Shared session types
│   │   ├── ainb-plugin-burndown/       #   v2 analytics plugin
│   │   ├── ainb-plugin-notifyd/        #   v2 notifications plugin
│   │   ├── ainb-plugin-session-reader/ #   v2 data-backend plugin
│   │   ├── ainb-plugin-cts-v2/         #   Conformance test suite (14 axes)
│   │   └── ainb-plugin-testkit/        #   Plugin author test harness
│   ├── config/                 #   Homebrew formula & packaging
│   └── install.sh              #   One-liner installer
│
# reflect (the `reflect` CLI + GraphRAG/QMD engine and its Claude Code plugin)
# now lives in a SEPARATE repo: github.com/stevengonsalvez/ainb-reflect-memory
# — flattened, with the engine at its repo root and the plugin under plugin/.
#
├── plugins/                    # Claude Code plugins (root-level)
│   ├── ainb-fleet/             #   Backs the `ainb fleet` CLI (standup/broadcast/sequence/needs/daemon)
│   └── ainb-hooks/             #   ainb lifecycle hooks
│
# The portable toolkit (91 skills, 37 agents, workflows, utilities,
# bootstrap.js, external-dependencies.yaml, catalog.yaml) lives in a
# SEPARATE repo: github.com/stevengonsalvez/ainb-toolkit — flattened at
# its repo root. `ainb` consumes it as a pinned external source.
#
├── ainb-tui/                   # `ainb` binary (Rust) — TUI + skill-manager CLI
│   ├── crates/
│   │   ├── ainb-cli/           #   ainb source/skill/migrate/doctor subcommands
│   │   ├── ainb-core/          #   ratatui app + manifest/lockfile/URI types
│   │   ├── ainb-fetch/         #   git2 / http / local fetchers
│   │   ├── ainb-adapters-source/  # marketplace / manifest / raw / single
│   │   ├── ainb-adapters-tool/    # 9 tool adapters (claude/codex/copilot/…)
│   │   ├── ainb-diff/          #   Diff render + pager driver
│   │   ├── ainb-skill-core/    #   Manifest/lockfile/URI/paths/error
│   │   └── ainb-usage/         #   JSONL invocation parser + cache
│   └── plans/skill-manager/spec.md   # v1 design + acceptance criteria
│
├── docs/                       # Documentation hub (Markdown source of truth)
│   ├── README.md               #   Docs TOC
│   ├── product/                #   What ainb is, value, architecture
│   ├── tui/                    #   ainb CLI reference, FAQ, keyboard shortcuts
│   ├── toolkit/                #   ainb-toolkit reference (skills/agents/bootstrap)
│   ├── plugins/                #   v2 plugin overview, user guide, authoring, spec
│   ├── knowledge/              #   reflect/recall (GraphRAG + QMD)
│   ├── contributing/           #   Build, CI/CD, release
│   └── reference/              #   Architecture deep-dive, glossary
│
├── website/                    # Website source (Astro + Starlight)
│   └── BRIEF.md                #   Design instruction for stevengonsalvez.github.io
│
└── .github/workflows/
    ├── ci.yml                  #   Rust CI (fmt, clippy, test, deny, machete)
    ├── toolkit-validation.yml  #   Skill Manager & Catalog CI (ainb + ainb-toolkit)
    ├── release.yml             #   Cross-platform binary releases
    └── deploy-pages.yml        #   Build & deploy the website to GitHub Pages

The Rust codebase enforces unsafe_code = "forbid" and runs clippy with pedantic, nursery, and cargo lint groups enabled.

cd ainb-tui
cargo build --release
./target/release/ainb

cd ainb-tui
cargo test                              # Unit tests
cargo test --features visual-debug      # With terminal output
cargo test --features vt100-tests       # VT100 screen verification
cargo nextest run                       # With nextest (parallel)

cd ainb-tui
cargo fmt --check                       # Format check
cargo clippy --all-targets              # Lint
cargo deny check                        # Security + licenses

# Seed your manifest from the toolkit on first run. The toolkit is a
# separate repo — clone it and point --toolkit-root at the checkout.
git clone https://github.com/stevengonsalvez/ainb-toolkit.git
ainb migrate --from-bootstrap --toolkit-root ./ainb-toolkit

# Deploy into the real tool home dirs (opt-in via env).
AINB_USE_REAL_HOMES=1 ainb skill sync --yes

# Or scope the install to specific tools (passed to every mutating verb):
ainb skill install local:./toolkit@main/packages/skills/commit --targets claude,codex
ainb skill update --check                     # report drift across sources
ainb skill update --all --yes                 # re-fetch + apply
ainb doctor                                   # health-check the deployment

See ainb-tui/plans/skill-manager/spec.md for the full §8 CLI surface (source, skill, migrate, doctor, usage).

If you already have skills under ~/.<tool>/skills/ (Claude, Codex, Gemini, …) or plugins installed via Claude Code's /plugin install, you don't have to migrate by hand any more. v1.1 layers a read-only discovery walker + a one-keystroke adoption banner on top of v1. Open SkillManager (m on Home) with an empty manifest and ainb offers to import what's already on disk — marketplace plugins, orphan skills, the lot — including a conflict matrix when the same name shows up in two places.

A new ainb skill promote <unit> --to gh:user/repo command turns a hand-edited orphan into a git-backed source in one shot: clones the target repo, copies the unit, commits + pushes, and rewrites the manifest URI from local: to gh:.

• Discovery flow reference → — walker classes, reconciler conflict matrix, banner UX
• ainb skill promote reference → — command surface, locked design, failure modes
• ainb skill usage reference → — per-unit invocation counts + last-used in the Detail pane (v1.2)
• ainb skill sync reference → — bidirectional home ↔ repo reconciliation with [s] keybind (v1.2)
• ainb skill check reference → — drift detection + Units-panel status column (v1.2)

Full spec at .agents/goals/ainb-skill-manager-v1.1-discovery-spec.md and .agents/goals/ainb-skill-manager-v1.2-rollup-plan.md.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

• Website
• Releases
• Homebrew Tap
• Issues
• Knowledge System Architecture
• Toolkit Repository (ainb-toolkit)

MIT — see LICENSE for details.