agents-in-a-box — documentation

Canonical source of truth for the monorepo. Everything published to the website under /docs/* is rendered from these files.

If you’re looking for a specific topic, start here:

Section	What’s in it
Product	What agents-in-a-box is, value, high-level architecture
TUI	The `ainb` terminal app
CLI	Every subcommand, every flag
Fleet	Running many agents at once: attention, the chat bridge, ATC, cost
Hangar	The managed-agents control plane
Skill manager	Install, sync and promote units across tool homes
Toolkit	Portable skills, agents, workflows (external repo)
Plugins	v2 subprocess plugin system
Observability	Usage/cost, live processes, causality, telemetry
Knowledge	`reflect` / `recall` GraphRAG + QMD
Contributing	Build, test, ship
Reference	Architecture, glossary, repositories
Internal	Plans, specs and research, not published to the site

Product

TUI

The ainb terminal app.

Overview
Install
First session quickstart — start here
Starting a new session
Attaching to sessions — full-screen and in-pane tmux attach
Code review (diff)
Shared MCP pool
Token optimisation — Headroom & RTK
Daemons overlay
Inbox & notifications
Browser dashboard (ainb web)
Keyboard shortcuts
Architecture
FAQ

CLI

Full CLI reference — generated from --help, drift-checked in CI

Fleet

Running more than one agent at a time.

Chat bridge — drive the fleet from Telegram, Slack or Discord
ATC — the always-on watcher and its session-lifecycle plumbing
Fleet cost rollups — spend across every session, with budget alerts

Hangar

The managed-agents control plane: boards, tasks, squads, autopilots.

Architecture & features

The rest of hangar/ is the build record — the original proposal, phase plans, verification goals and the Multica research that produced them. It is kept for provenance and is not published to the site. See hangar/README.md.

Skill manager

Install, sync and promote skills, agents and commands across your tool homes.

Guide — start here
Discovery & import — adopt what is already on disk
Catalog browse
Sync — reconcile home and repo
Drift check
Usage tracking
Promote — turn a local unit into a git-backed source
Sandbox testing

Toolkit

Portable AI-coding agent toolkit. Skills, agents and workflows deployed to 9 AI tools. The canonical source is the standalone stevengonsalvez/ainb-toolkit repo; ainb consumes it as a pinned external source.

Claude Code plugins that ship alongside it:

Overview — how these differ from ainb plugins
reflect — learning capture and recall
ainb-fleet — the fleet orchestration skills
ainb-hooks — lifecycle events into Hangar and the Inbox

Plugins

Read this first if the word is confusing: plugins/README.md. “Plugin” means two different things in this repo, and that page disambiguates.

The v2 subprocess plugin system for the ainb TUI:

What is an ainb plugin?
User guide — install, configure, troubleshoot
Authoring guide — write your own
Wire spec v2 — the JSON-RPC contract
Changelog

In-tree plugins:

burndown — the analytics screen and ainb usage
session-reader — the silent backend behind burndown’s numbers
witr — process-causality tracing
learnings — browse and search the knowledge base
abtop — live agent-process monitor

Observability

See what your agents are doing, spending and running.

Overview — which tool answers which question
Usage analytics (burndown) — spend by day, project and model
Fleet cost rollups — spend across the whole fleet
abtop — live agent-process monitor
witr — process-causality tracing
OpenTelemetry to Grafana Cloud — ship metrics, logs and traces off-box

Knowledge

The two-tier learning capture and retrieval system.

How reflection works
reflect CLI reference
Hooks & platform — Claude, Codex and Copilot wiring

Reflect memory, in depth:

Contributing

Reference

Architecture deep-dive
Glossary
Repositories — which repo holds what

Internal

Written for whoever is building the thing, not for a reader of the site, so these are excluded from the site build. They stay in the repo for provenance.

Directory	What it holds
`plans/`	Dated implementation plans for in-flight work
`contracts/`	Implementer specs, e.g. the macOS fleet daemon contract
`explorations/`	Comparative research notes
`solutions/`	Troubleshooting and postmortem notes
`hangar/`	The Hangar build record, except `hangar/architecture.md`

Current plans:

Buzz port part 1 — daemon chat bus + ACP adapter
Buzz port part 2 — fleet chat + copilot · spec
Research: porting block/buzz into ainb (discussion #570)
Explainer: buzz to ainb port research

How this tree maps to the legacy layout

The pre-restructure layout had docs scattered across three places. Here’s the mapping:

New location	Source (legacy)
`docs/tui/cli.md`	`ainb-tui/docs/CLI.md`
`docs/tui/faq.md`	`ainb-tui/docs/FAQ.md`
`docs/toolkit/overview.md`	`toolkit/README.md` (TOC + intro — the toolkit itself has since moved to the standalone `stevengonsalvez/ainb-toolkit` repo)
`docs/plugins/overview.md`	new — disambiguates
`docs/plugins/user-guide.md`	`docs/plugins.md`
`docs/plugins/authoring.md`	`docs/plugin-authoring.md`
`docs/plugins/spec-v2.md`	`docs/plugin-spec/v2.md`
`docs/plugins/changelog.md`	`docs/plugin-spec/CHANGELOG.md`
`docs/knowledge/overview.md`	`docs/how-reflection-works.md`

The migration is complete: every page in this tree is now authoritative and the legacy paths have been removed. The table above is retained only to document provenance.

Editing rules

Markdown is the source format. Astro Starlight renders to HTML at build time.
Code blocks: always tag the language for syntax highlighting.
Cross-link other docs with relative paths, resolved from the linking file ([…](plugins/spec-v2.md) from here, […](../plugins/spec-v2.md) from inside tui/).
Heading style: # once per file (title), then ## and below for sections.
Frontmatter (Starlight-style) only on files that override the title or sidebar position:
```
---
title: "Plugin authoring guide"
sidebar:
  order: 2
---
```
Use admonitions sparingly: > [!note], > [!warning], > [!tip].