```
╔═══════════════════════════════════════════════════════════════╗
║ ║
║ █████╗ ██████╗ ███████╗███╗ ██╗████████╗███████╗ ║
║ ██╔══██╗██╔════╝ ██╔════╝████╗ ██║╚══██╔══╝██╔════╝ ║
║ ███████║██║ ███╗█████╗ ██╔██╗ ██║ ██║ ███████╗ ║
║ ██╔══██║██║ ██║██╔══╝ ██║╚██╗██║ ██║ ╚════██║ ║
║ ██║ ██║╚██████╔╝███████╗██║ ╚████║ ██║ ███████║ ║
║ ╚═╝ ╚═╝ ╚═════╝ ╚══════╝╚═╝ ╚═══╝ ╚═╝ ╚══════╝ ║
║ ██╗███╗ ██╗ █████╗ ║
║ ██║████╗ ██║ ██╔══██╗ ║
║ ██║██╔██╗ ██║ ███████║ ║
║ ██║██║╚██╗██║ ██╔══██║ ║
║ ██║██║ ╚████║ ██║ ██║ ║
║ ╚═╝╚═╝ ╚═══╝ ╚═╝ ╚═╝ ║
║ ██████╗ ██████╗ ██╗ ██╗ ║
║ ██╔══██╗██╔═══██╗╚██╗██╔╝ ║
║ ██████╔╝██║ ██║ ╚███╔╝ ║
║ ██╔══██╗██║ ██║ ██╔██╗ ║
║ ██████╔╝╚██████╔╝██╔╝ ██╗ ║
║ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝ ║
║ ║
╚═══════════════════════════════════════════════════════════════╝
```
**A complete ecosystem for AI-assisted development**
Sessions, one worktree each
Every agent gets its own branch and working directory. Watch them all from one tree.
|
Hangar: work queues up
Boards, tasks, squads and autopilots. Agents pull work instead of waiting for you to start it.
|
Read the diff before you trust it
File tree, per-file blocks, word-level emphasis, hunk navigation. Or ainb diff-review, headless.
|
Spend, before the invoice
Daily activity, per-model and per-project breakdowns, live budget tracking, optimisation hints.
|
Which repo burned the budget
Input, cache, output and session counts per project and per worktree.
|
abtop: top, for agents
Quota, tokens, projects, ports, MCP servers and every live session in one pane.
|
One MCP pool, not one per session
A single server process shared across every session, with idle reaping.
|
Daemons, and their health
Every background process ainb depends on, with restart in place when one dies.
|
Every notification in one Inbox
Approvals, completions and errors from every agent, instead of scattered across panes.
|
Skills, across every tool
Browse, install, sync and remove units. Write once, deploy to nine tool homes.
|
Stop re-explaining the codebase
Search what past sessions learned, by entity, community or free text.
|
What did that process touch
Process causality, ancestry, ports and locks, without leaving the TUI.
|
Attach, detach, survive a sleep
tmux-backed. Reattach full-screen or in a pane and keep typing.
|
Start one any way you like
Local repo, clone from GitHub or GitLab, SSH to a remote box, or a favourite.
|
Pick the agent, pick the model
Claude Code, Codex, Gemini, Copilot, a raw shell or SSH. Sonnet, Opus or Haiku per session.
|
Guided first run
Dependency checks, auth, git paths, editor. Factory reset when you want to start over.
|
**Also in the box, no screenshot yet** ([#778](https://github.com/stevengonsalvez/agents-in-a-box/issues/778) tracks capturing these):
| Surface | What it gives you | Docs |
|---|---|---|
| **Fleet panel** (`f`) | See which agents are blocked on you and answer them without attaching | [cli.md](docs/tui/cli.md) |
| **ATC** | An always-on watcher that works the queue while you are away (opt-in) | [atc-plumbing.md](docs/atc-plumbing.md) |
| **Recovery** | Find sessions orphaned by a crash and resume them | [cli.md](docs/tui/cli.md) |
| **Fleet bridge** | Drive the fleet from Telegram, Slack or Discord | [fleet-bridge.md](docs/fleet-bridge.md) |
| **`ainb web`** | A read-only browser dashboard over the fleet | [web.md](docs/tui/web.md) |
| **Headroom** | Context compression so long runs stop hitting the wall | [token-optimization.mdx](docs/tui/token-optimization.mdx) |
| **`ainb claudecode statusline`** | Live rate-limit and spend inside Claude Code's own status line | [cli.md](docs/tui/cli.md) |
| **OTel to Grafana** | A wizard that wires Claude Code's telemetry into Grafana Alloy | [otel-grafana.md](docs/reference/otel-grafana.md) |
---
## What's Inside
| Component | What it does | Scale |
|-----------|-------------|-------|
| **[ainb TUI](#ainb--terminal-ui)** | Rust terminal app for managing Claude Code sessions | 34 crates |
| **[Toolkit](#toolkit)** | Portable skills, agents, and workflows for AI coding tools | 94 skills, 16 agents |
| **[Knowledge System](#knowledge-system)** | GraphRAG + QMD learning capture and retrieval | [Architecture docs](docs/knowledge/overview.md) |
---
## Why agents-in-a-box?
> ### Run a fleet. Lose nothing.
>
> Every agent gets its own worktree, its own tmux session, and a line item on your bill.
One agent is a chat window. Five agents is an operations problem, and that is the
part nothing else solves. Here is every part of it.
### Your agents stop fighting each other
| The problem | Without ainb | With ainb |
|---|---|---|
| Two agents, one branch | Index lock races, half-committed files, work silently overwritten | One git worktree and one branch per session, cleaned up when the session is killed cleanly |
| Laptop sleeps, SSH drops | Session gone, context gone, start the conversation again | tmux-backed. Reattach and keep typing where you left off |
| A crash leaves sessions behind | Hunt through `tmux ls` and guess which pane was what | `ainb recover` finds the orphans and resumes them |
### You stop babysitting them
| The problem | Without ainb | With ainb |
|---|---|---|
| Which agent needs me *right now* | Cycle through every pane in turn, repeatedly | Press `f`. The Fleet panel lists exactly who is blocked |
| An agent asked a question 20 minutes ago | Scroll back through output to find it | Answer it from the Fleet panel without attaching |
| Nobody is watching while you are away | You are the event loop | ATC wakes on a timer and works the queue for you |
### Work queues up without you
| The problem | Without ainb | With ainb |
|---|---|---|
| Every task starts with you typing | You are the scheduler | Hangar boards hold tasks agents pull from |
| One agent per job, in sequence | Long jobs serialise behind you | Squads fan a job out across several agents |
| Recurring work | A cron job you maintain by hand | Autopilots fire on a schedule and report back |
### You see what they actually changed
| The problem | Without ainb | With ainb |
|---|---|---|
| Approving diffs on autopilot | Side effects land that you never read | Hunk-by-hunk review with syntax highlighting before you trust it |
| Reviewing means opening the whole TUI | Context switch just to read a diff | `ainb diff-review` runs headless and emits JSON |
### The bill stops surprising you
| The problem | Without ainb | With ainb |
|---|---|---|
| Spend is invisible until the invoice | The provider console shows one total | Burndown by day, week, project, model and provider |
| Which repo burned the budget? | No per-repo or per-branch split anywhere | Per-project attribution, down to the worktree |
| Long runs blow the context window | The conversation resets and you start over | Headroom compresses context across opted-in sessions |
### You stop repeating yourself
| The problem | Without ainb | With ainb |
|---|---|---|
| Re-explaining the codebase every session | Every session starts cold | Learnings captured as you work, searchable next time |
| The same rule copied into four tools' configs | One copy gets updated, the rest quietly go stale | Write a skill once, deploy it to 9 tools from one source |
### The plumbing stops leaking
| The problem | Without ainb | With ainb |
|---|---|---|
| One MCP server per session | N processes, N startups, N times the memory | One pooled server shared across every session |
| Approvals and errors scattered across panes | You miss the one that mattered | One Inbox collects every notification from every agent |
| Background processes die quietly | `ps aux`, grep, guess, restart by hand | The Daemons screen shows health and restarts in place |
### It reaches further than your terminal
| The problem | Without ainb | With ainb |
|---|---|---|
| You are away from your desk | Agents stall until you get back | Bridge the fleet to Telegram, Slack or Discord |
| You want a glance without a terminal | Terminal or nothing | `ainb web` serves a read-only dashboard |
| What did that process actually touch? | Guesswork | `witr` traces process causality |
| Which agent is genuinely busy? | Open every pane and look | `abtop`, which is top for AI agents |
### What it won't do
Straight answers, so you find out here rather than twenty minutes in:
- **Worktrees isolate git state, not your environment.** Two agents still share port 3000, your database, and `node_modules`. If they need different services running, you still have to arrange that.
- **tmux is required**, not optional. Same for `git`.
- **No native Windows.** It uses PTY and POSIX file modes. WSL2 works.
- **`ainb otel` is a setup wizard for Grafana Alloy**, wiring up Claude Code's own telemetry. ainb does not emit telemetry of its own.
- **Memory starts empty.** The learnings browser is only as useful as what `reflect` has written into it.
- **ATC and headroom are opt-in** and need extra setup: a hook plugin and an external binary respectively.
---
## Quick Start
```bash
# 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
# Launch the TUI
ainb
# Register the toolkit as a source, then install the units you want into your
# real tool homes. Install is purely ADDITIVE — units land alongside your
# existing config; your CLAUDE.md, settings, projects/ history and custom
# agents are never touched.
ainb source add gh:stevengonsalvez/ainb-toolkit
AINB_USE_REAL_HOMES=1 ainb skill install gh:stevengonsalvez/ainb-toolkit/skills/commit
```
> **The easy way:** just run `ainb`, press `m` for the Skill Manager, and
> browse + install units with `[i]`. If you already have skills on disk
> (`~/.claude/skills/`, etc.), the first open offers one-keystroke adoption —
> no manual setup. `ainb skill sync` then keeps installed units reconciled with
> the manifest.
>
> To uninstall a unit, run `ainb skill remove