Claude Tempo

Multi-session Claude Code coordination via Temporal.

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 claude-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 claude-tempo

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

Quick Start

One command handles everything:

cd your-project
claude-tempo up

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

claude-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

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

Upgrading

claude-tempo upgrade

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

claude-tempo upgrade 0.22.0

Stopping & Tear Down

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

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

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

# Stop the background daemon
claude-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 claude-tempo to open the TUI and switch between ensembles, or target a specific ensemble directly:

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

MCP Tools

Tools available inside Claude Code sessions connected to claude-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

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

Run claude-tempo --help or claude-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

claude-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.

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

📖 Player types deep dive → docs/ensembles.md

Configuration

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

Settings persist in ~/.claude-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

claude-tempo tui                          # multi-ensemble home screen
claude-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 claude-tempo daemon start|stop|status|logs.

📖 Daemon reference → docs/daemon.md

Development

git clone https://github.com/vinceblank/claude-tempo.git
cd claude-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 claude-tempo is a published approved channel plugin. Copilot bridge sessions are not affected.

License

MIT