teamctl
docker-compose for persistent AI agent teams.
Declare a team of long-lived Claude Code, Codex CLI, or Gemini CLI sessions in YAML. Every agent is its own real CLI running in its own tmux pane, supervised and auto-respawned (systemd and launchd backends are on the ROADMAP). They coordinate through a shared MCP mailbox. Each project has its own private org-chart with one or more managers; you talk to those managers over pluggable interfaces (Telegram, Discord, iMessage, CLI, webhook). Brand-sensitive actions pause for your approval.
curl -fsSL https://teamctl.run/install | sh
cd /path/to/your/project
teamctl init
teamctl up
Prefer to build from source? cargo install teamctl team-mcp team-bot works too. A Homebrew tap is on the way — see the ROADMAP.
Getting started
teamctl drops a .team/ folder into your existing project, brings the agents up in tmux, and supervises them. Four commands take any repo to a running team:
cd /path/to/your/project # 1. start in the repo you want a team in
teamctl init # 2. scaffold .team/ here
teamctl up # 3. bring the team up
teamctl reload # 4. apply edits to .team/team-compose.yaml
1. cd /path/to/your/project — teamctl integrates with an existing project, it doesn't replace it. The agents in your team will work alongside whatever else is in this directory, with their config and state living under a single .team/ subfolder.
2. teamctl init writes a .team/ directory in the current repo with a starter team-compose.yaml, role prompts for a manager and a dev, and a .env.example. The contents are plain YAML and Markdown — nothing hidden, nothing generated at runtime that you can't read.
3. teamctl up brings the team up. Each agent gets its own tmux pane running its CLI (Claude Code by default), wired to a shared SQLite mailbox over MCP. Runtime state — the database, rendered env files, supervisor records — lives in .team/state/, gitignored.
4. teamctl reload picks up edits to .team/team-compose.yaml and restarts only the agents whose config actually changed. No full teardown, no lost mailbox state.
Talking to the team. Run teamctl bot setup — the wizard walks BotFather → token → /start → chat id once per user-facing manager and writes everything into .team/.env and projects/<id>.yaml. Each manager gets its own Telegram bot; DM the bot in plain English and the message reaches that manager. Brand-sensitive actions (publish, deploy, release, …) pause for inline Approve / Deny.
The full onboarding tutorial lives at teamctl.run/getting-started; curated example teams (startup-team, oss-maintainer, indie-game-studio, newsletter-office, market-analysts) ship under examples/.
What's in a team
- Every node is a separate long-lived CLI — Claude Code, Codex, or Gemini — running in its own
tmux pane. No shared process, no "roles inside one LLM."
- Projects are self-contained org charts. One project can have many managers and many workers; workers are wired to one or more managers through
reports_to. Agents can call org_chart to introspect their chain of command.
- Managers talk to each other inside a project (shared
#leads channel or DM). Across projects they're isolated — a one-off bridge opens a manager-to-manager link for a limited time.
- You reach managers through any of the configured interfaces. Telegram is the first adapter; Discord, iMessage, CLI, and webhooks plug in the same way.
- Brand-sensitive actions pause. Tool calls tagged
publish, release, deploy, payment, … block on request_approval and surface on your chosen interface with Approve / Deny.
Status
Early but moving fast. v0.4.0 is the latest release (April 2026); MIT-licensed, working, and shipped in the open. See the ROADMAP and CHANGELOG for the full picture.
What you get
