Bottle your agent setup. Run it, share it, remix it like a recipe.

You configure the perfect Claude Code or Codex session setup, then it dies with the session. You can't run it again, can't hand it to a teammate, can't pass it on.

You describe your team in YAML: who the agents are, what each one owns, and how they talk to each other. Each agent is a real Claude Code, Codex, or Gemini session with its own memory. teamctl up brings them up. Hand it to a teammate and they get the same team, not a screenshot of yours.

I built this for myself. Experiments worth sharing, so here we are :)

curl -fsSL https://teamctl.run/install | sh

Installs teamctl in your command line.

🚀 Start a team

Then, inside your project directory:

$ cd /path/to/your/project
$ teamctl init

init opens a short conversation that surfaces the domains in your work and proposes a team shape. You can let it design the team with you (guided), start from a small essentials scaffold, or take an empty tree and hand-wire it yourself. By the time you're done, .team/team-compose.yaml is on disk and the team is running in tmux.

🍒 Extras on top

Because teamctl runs your sessions, it can hand them tools they would not have on their own. A session can call compact_self to compact its own context and keep going, and that is just the start:

Orchestration and a shared mailbox: agents coordinate and message each other through durable channels you can audit.
Per-agent settings: give each agent its own runtime, model, role, and tools.
Cascading role prompts: layer a shared _base.md and group files like _engineer.md under each agent's own role, so the rules they share live in one place.
One terminal UI for the whole team: watch every agent in one place with teamctl ui.
Easy Telegram hookup: steer your team from your phone (more interfaces on the way).
(soon) Auto-recovery from rate limits: teamctl can let your session know when its rate limit has cleared so it picks the work back up.

These extras are optional. They are here to help fill the gaps as you design different agent setups.

🧩 Examples

Real teams running on teamctl. Copy any of them as a starting point.

More under examples/.

🧱 What a team looks like

A project YAML with two managers you talk to and two engineers who build (illustrative, not a full config):

version: 2

project:
  id: product-team

# 📡 Slack-like channels: agents in a channel can post messages and receive notifications
channels:
  - name: product             # 🧭 the Product Manager hands requirements.md to the Engineering Manager here
    members: [pm, em]

  - name: eng                 # 🛠️ the Engineering Manager routes build work to the engineers
    members: [em, eng-claude, eng-codex]

  - name: code_review         # 🔀 the two engineers review each other's PRs (cross-model)
    members: [eng-claude, eng-codex]

managers:
  # 🧭 you talk to the Product Manager about *what* to build — it owns requirements.md
  pm:
    display_name: "Product Manager"
    runtime: claude-code
    model: claude-opus-4-8
    role_prompt:               # 🧬 cascading roles: _base.md layers into every agent
      - roles/_base.md
      - roles/pm.md
    subagents:                # 🧩 give an agent its own sub-agents (claude-code)
      - subagents/product-researcher.md
      - subagents/prd-drafter.md
    interfaces:
      telegram:               # 📱 tap to talk to your team from your phone
        bot_token_env: TEAMCTL_TG_PM_TOKEN
        chat_ids_env: TEAMCTL_TG_PM_CHATS

  # 🛠️ you talk to the Engineering Manager about *how* it ships — it routes work and gates merges
  em:
    display_name: "Engineering Manager"
    runtime: claude-code
    model: claude-opus-4-8
    role_prompt:
      - roles/_base.md
      - roles/em.md
    interfaces:
      telegram:               # 📱 a separate bot: two conversations, product & delivery
        bot_token_env: TEAMCTL_TG_EM_TOKEN
        chat_ids_env: TEAMCTL_TG_EM_CHATS

workers:
  # 🤖 a Claude engineer: builds, and reviews the Codex engineer's PRs
  eng-claude:
    display_name: "Engineer (Claude)"
    runtime: claude-code
    model: claude-sonnet-4-6
    role_prompt:
      - roles/_base.md
      - roles/_engineer.md     # 🧬 group layer shared by both engineers
      - roles/eng.md
    reports_to: em
    subagents:
      - subagents/implementer.md
      - subagents/test-author.md
    hooks:                    # 🪝 fmt+lint gate on every Edit/Write (claude-code)
      - event: PreToolUse
        matcher: "Edit|Write"
        command: hooks/fmt-lint.sh

  # 🤖 a Codex engineer: the other half of the cross-model review loop
  eng-codex:
    display_name: "Engineer (Codex)"
    runtime: codex
    model: gpt-5-codex
    role_prompt:
      - roles/_base.md
      - roles/_engineer.md
      - roles/eng.md
    reports_to: em

$ teamctl validate    # check the YAML
$ teamctl up          # bring the team up
$ teamctl ui          # watch them work
$ teamctl status      # is everyone alive?

All of this lives in a .team/ folder in your project, so you can read it, version it, and share it.

🔍 Inspect your setup (`teamctl ui`)

A super lightweight UI, built in Rust, for inspecting your agents and their actual Claude Code sessions. See which agents you have, the messages they have exchanged, and work with a live session right from the UI. Each agent runs in a tmux session in the background, so when you close the UI the sessions keep working.

You can view all your teams, their actual sessions, their mailbox

You can inspect each message exchanged between agents

You can also connect to the actual tmux sessions by pressing Ctrl+E and take control of the session

📚 Learn more