# Agent Teams — user guide Mission control for your AI agent team. This guide gets you from zero to a running board, and explains the two ways to put agents to work. GitHub: https://github.com/bankung/agent-teams --- ## What it is Agent Teams is a self-hosted orchestration and governance layer that turns **Claude Code** or **OpenAI Codex** into a persistent, governed, multi-domain agent team. A single coding CLI is a powerful brain with no memory across sessions, no project structure, and no safety rails. Agent Teams closes that gap. It wraps your CLI with: - a **Postgres-backed Kanban** that holds the plan, - a **Lead orchestrator** that spawns a fresh domain specialist per task, - a **five-zone context model** that keeps state scoped, and - a **defense-in-depth safety layer**: acceptance criteria, human-in-the-loop gates, and hard budget caps. Everything runs locally in Docker. No cloud sign-up, no SaaS subscription, no code leaving your network. It is also dogfooded: Agent Teams builds Agent Teams, and the repo's own commit history and Kanban are the proof. **It is** a layer on top of a coding CLI. **It isn't** a frontier autonomous agent that replaces your CLI, an IDE, or a from-scratch agent framework. It orchestrates the coding agent you already use. --- ## Requirements - **Docker Desktop**: install it and restart your computer. - A coding CLI: **Claude Code** or **OpenAI Codex** (for real end-to-end work). Both products ship VS Code extensions, so you can run them in the terminal or inside VS Code - either way works with Agent Teams. - A model provider of your choice: Anthropic, OpenAI, Google Gemini, or **Ollama** for fully local inference (no API key, no network egress). --- ## Install ### Quick start (npx) 1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop/) and restart your computer. 2. With Docker running, open a terminal and run: ``` npx @bankung/agent-teams up ``` This clones the repo, builds the stack, and seeds a demo project. Pass `--images` to pull pre-built GHCR images instead of cloning: ``` npx @bankung/agent-teams up --images ``` 3. Open **http://localhost:5431** to see your Kanban board. npm package: https://www.npmjs.com/package/@bankung/agent-teams Services keep running after you close the terminal. To stop: `npx @bankung/agent-teams down`. To wipe and start fresh: `npx @bankung/agent-teams reset`. ### Alternative: clone and run the installer If you prefer to work directly with the source: ``` git clone https://github.com/bankung/agent-teams cd agent-teams ``` Then run the installer for your platform: - **macOS / Linux / WSL:** `./bin/install.sh` - **Windows (PowerShell):** `.\bin\install.ps1` (If scripts are blocked, run `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` once first.) --- ## Your first project The installer seeds a **demo-tour** project so you have something to explore. 1. Open **http://localhost:5431** and click the **demo-tour** project. 2. You will see a few sample tasks across the board lanes. 3. Switch between **Board**, **List**, **Calendar**, and **Gantt** using the view switcher to see the same work from different angles. 4. Create your own project from the project list with **New Project**, pick a domain (dev / content / data / general), and add a first task. ### Why file a task instead of just chatting? - **Chat** is great for questions and exploration, but has no clear "done". - **A task** carries acceptance criteria, so the agent knows exactly what done looks like, the work is queueable and auditable, and another agent can resume it if one gets stuck. Use tasks for real work (features, bugs, refactors). Use chat for questions. --- ## The two execution modes **Mode A - on your subscription (production today).** Open the repo in Claude Code or OpenAI Codex (in the terminal or inside VS Code via their extensions). The Lead asks which project you are working on; answer with the project name (for example, demo-tour). It then binds the session, loads the team playbook, and orchestrates specialists end-to-end with per-action approval. Runs on the subscription you already pay for. No API key needed for this path. You keep control. This is the path for real end-to-end work today. **Mode B - headless via API (actively in development).** Flip a task to auto-run and the headless engine handles it with no terminal open. Tasks are billed through your API key with metered usage and hard budget caps keeping spend visible and bounded. Full autonomous end-to-end execution is **actively in development**, so don't rely on it for critical work yet. To see agents do real work today, use Mode A. --- ## Slash-command skills (tn-*) These are reusable Claude Code commands that encode the Kanban API conventions so you don't trip over common mistakes. They activate after a Claude Code restart. | Command | What it does | |---|---| | `/tn-task-create ` | Create a Kanban task correctly (project + acceptance criteria at creation). | | `/tn-task ` | Show one task with its acceptance criteria (read-only). | | `/tn-tasks-next [N]` | List the next N actionable tasks (current milestone first, blockers first). | | `/tn-task-done ` | Verify every acceptance criterion, then flip the task to DONE. | | `/tn-task-update ` | Guarded status / priority update. | | `/tn-task-attach ` | Attach a task to a milestone. | | `/tn-milestone-create ` | Create a milestone. | | `/tn-milestone-done <id>` | Release a milestone after checking its child tasks. | | `/tn-milestones` | List milestones with their task rollup. | | `/tn-intense-review <scope>` | Two-round adversarial review + test-hardening pass. | | `/tn-spec <idea>` | Two rounds of spec pushback before creating a task. | | `/tn-bind <project>` | Bind the session to a project by name. | | `/tn-audit [project]` | On-demand project health audit. | --- ## When things look stuck - **Browser stuck loading for >30s** → reload the page (Ctrl+R or Cmd+R). - **A task says "waiting" for too long** → check Docker is healthy with `docker compose ps`; if anything is unhealthy, `docker compose restart api`. - **An agent did something you didn't want** → click **Halt** on the task, note what went wrong, and file a bug. --- ## Learn more - **Source, issues, and the live commit history:** https://github.com/bankung/agent-teams Self-hosted. Open source. Runs on your machine.