Multiple Claude Code sessions discover each other, exchange messages in real time, and coordinate work — across machines, not just localhost.

Each session registers as a player in Temporal. Players discover each other with ensemble, send messages with cue, and coordinate via a conductor that connects to external interfaces like Discord, Telegram, or the built-in TUI.

📖 Full documentation

Why agent-tempo?

• Crash-safe durability — Sessions are Temporal workflows. Crashes, restarts, and network blips don't lose messages or drop coordination state.
• Instant signaling — Temporal signals deliver messages with no polling. Players receive cues the moment they're sent, regardless of which machine they're on.
• Built-in scheduling — One-shot and recurring message schedules without any external infrastructure.
• Extensible agent types — Define reusable player roles as .md files. Ship lineups that assemble entire teams in one command.

Features

| | | |---|---| | 🔁 Ensemble Lineups | YAML configs that define a full team and recruit them all in one command | | ⏰ Scheduling | One-shot and recurring message schedules with fan-out and failure notifications | | 🎭 Player Types | Reusable agent definitions with 8 shipped types and three-tier lookup | | 🖥️ Terminal UI | Chat-focused TUI with slash commands, overlays, and interactive wizards | | 🌐 Cross-machine | Any session that can reach your Temporal server can join the ensemble | | ⏸️ Hold / Pause / Resume | Pre-warm a full team before delivering tasks; pause and resume mid-session | | 🤖 Headless adapters | Copilot bridge, Claude API, OpenCode, and Claude Code headless (claude -p subprocess — bills against your Claude Code subscription, no Console API key needed) — mix providers and headless agents in the same ensemble |

Installation

npm install -g agent-tempo

Prerequisites: Node.js 20 LTS, 22 LTS, or 24 LTS, Temporal CLI, Claude Code

Quick Start

One command handles everything:

cd your-project
agent-tempo up

This starts Temporal, registers the MCP server, launches the daemon, and opens a conductor session. Then add players:

agent-tempo status         # see who's active

Or use the TUI to recruit players, or ask the conductor to recruit from inside Claude Code.

Manual setup

agent-tempo server         # start Temporal dev server
agent-tempo init           # register MCP server globally
agent-tempo preflight      # verify environment
agent-tempo up             # launch conductor via auto-provisioning

Upgrading

agent-tempo upgrade

Stops the daemon, installs the latest version, and restarts automatically. To upgrade to a specific version:

agent-tempo upgrade 0.22.0

Stopping & Tear Down

# Terminate all sessions in an ensemble
agent-tempo destroy my-ensemble

# Tear down everything (all sessions, schedulers, and Maestro workflows)
agent-tempo down --all

# Tear down and terminate all workflows in one step
agent-tempo down --destroy -y

# Stop the background daemon
agent-tempo daemon stop

📖 Full CLI reference → docs/cli.md

Core Concepts

• Player — A Claude Code session registered as a Temporal workflow
• Conductor — Required orchestration hub (one per ensemble); receives report calls and connects to external interfaces. Lineup schema enforces its presence.
• Ensemble — A named group of players isolated from other ensembles; defaults to default
• Cue — A message sent to a player by name via Temporal signal
• Lineup — A YAML file that defines a full team and recruits them in one step
• Player Type — A reusable agent definition (.md with YAML frontmatter) that gives a player a named role

Players in one ensemble cannot see or message players in another. Launch agent-tempo to open the TUI and switch between ensembles, or target a specific ensemble directly:

agent-tempo up frontend        # provision and launch conductor in "frontend"
agent-tempo up backend         # provision and launch conductor in "backend"

MCP Tools

Tools available inside Claude Code sessions connected to agent-tempo:

| Tool | Description | |------|-------------| | ensemble | Discover active sessions | | cue | Send a message to a player by name | | recruit | Spawn a new Claude Code session | | report | Send updates to the conductor | | broadcast | Send a message to all active players | | recall | Read your own message history | | who_am_i | Get your identity, role, and player type |

📖 Full tools reference → docs/tools.md (includes schedule, stage, quality_gate, worktree, and all others)

CLI

agent-tempo                    # launch TUI (auto-provisions on first run)
agent-tempo up [ensemble]      # provision infrastructure and launch conductor
agent-tempo down [--destroy]   # tear down infrastructure (--destroy also terminates workflows)
agent-tempo status [ensemble]  # list active sessions
agent-tempo destroy <ensemble> # terminate all sessions in an ensemble
agent-tempo restore <ensemble> # restore orphaned sessions on this host
agent-tempo hosts              # list daemons polling this Temporal namespace (--all/--json)
agent-tempo recall <name>      # read a player's message history (--limit/--offset/--preview/--json)
agent-tempo attachment-info <name> # inspect a session's phase, holder, lease, and heartbeat age
agent-tempo release [ensemble] # release held players (unlock + deliver tasks)
agent-tempo daemon <sub>       # manage the worker daemon
agent-tempo upgrade            # update to latest

Run agent-tempo --help or agent-tempo <command> --help for all flags.

📖 Full CLI reference → docs/cli.md

Ensemble Lineups

Define reusable team configurations as YAML files and load them in one command:

name: my-project
conductor:
  instructions: "Coordinate the frontend and backend teams"
players:
  - name: frontend
    type: tempo-soloist
    workDir: /repos/my-app
    instructions: "Build the React dashboard"
  - name: backend
    type: tempo-soloist
    workDir: /repos/my-api
    instructions: "Implement the REST endpoints"
schedules:
  - name: status-check
    message: "Report your current progress"
    target: all
    every: 30m

agent-tempo up --lineup my-project.yaml   # load from CLI

Or from inside a session: "Load the my-project lineup"

📖 Lineups, player types, and shipped examples → docs/ensembles.md

Player Types

Player types are reusable agent definitions — .md files with YAML frontmatter. Reference them by name in lineups:

players:
  - name: arch
    type: tempo-composer
  - name: eng
    type: tempo-soloist

Eight types ship out of the box: tempo-conductor, tempo-composer, tempo-soloist, tempo-tuner, tempo-critic, tempo-roadie, tempo-improv, tempo-liner. Five lineup presets are included: tempo-big-band, tempo-dev-team, tempo-review-squad, tempo-jam-session, tempo-mock-jam.

agent-tempo agent-types list   # discover available types
agent-tempo agent-types init   # copy shipped types to ~/.claude/agents/

📖 Player types deep dive → docs/ensembles.md

Configuration

agent-tempo config   # interactive setup (Temporal address, namespace, API key)

Settings persist in ~/.agent-tempo/config.json. Resolution order: CLI flags → env vars → config file → Temporal CLI config → defaults.

Key environment variables:

| Variable | Default | Description | |----------|---------|-------------| | TEMPORAL_ADDRESS | localhost:7233 | Temporal server address | | TEMPORAL_NAMESPACE | default | Temporal namespace | | TEMPORAL_API_KEY | (none) | Temporal Cloud API key | | CLAUDE_TEMPO_ENSEMBLE | default | Ensemble name |

📖 Full configuration reference → docs/configuration.md

Terminal UI

agent-tempo tui                          # multi-ensemble home screen
agent-tempo tui --ensemble my-ensemble   # direct ensemble mode

The TUI provides a chat-focused shell for managing your ensemble:

• Ensemble chat feed — live aggregated view of conductor + player traffic; type bare text to message the conductor, @player message to message directly
• Slash commands — /recruit, /status, /schedule, /gates, /stages, /worktree, /go (release held), /pause, /play, /shutdown, /restore, /home, and more; type /help for the full list
• Interactive overlays and wizards — step-by-step flows for recruiting players, creating schedules, and managing ensembles

📖 TUI reference → docs/tui.md

Copilot Integration

Experimental — subject to breaking changes.

GitHub Copilot CLI sessions can join an ensemble using --agent copilot. Recruit one from the TUI:

/recruit copilot-1 --agent copilot

📖 Copilot bridge setup and limitations → docs/copilot.md

Worker Daemon

The daemon runs Temporal workers as a background process — it starts automatically on first use. Manage it explicitly with agent-tempo daemon start|stop|status|logs.

📖 Daemon reference → docs/daemon.md

Development

git clone https://github.com/vinceblank/agent-tempo.git
cd agent-tempo && npm install

npm run build   # compile TypeScript + pre-bundle workflows
npm test        # run tests
npm link        # link CLI for local testing

Important: Run npm run build after changing workflow code (src/workflows/). The build pre-bundles workflows into workflow-bundle.js so all workers use identical code.

Contributing

See CLAUDE.md for project structure, conventions, and development setup. See docs/ARCHITECTURE.md for the three-layer session model (workflow / adapter / process). Pull requests welcome — run npm test before submitting.

Known Limitations

• recruit requires manual acknowledgment — Recruited sessions show a Claude Code confirmation prompt that must be acknowledged in the spawned terminal. This will be resolved once agent-tempo is a published approved channel plugin. Copilot bridge sessions are not affected.

License

MIT