agent-tempo 1.2.0 → 1.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (98) hide show
  1. package/CLAUDE.md +219 -219
  2. package/LICENSE +21 -21
  3. package/README.md +289 -289
  4. package/assets/icon-dark.svg +9 -9
  5. package/assets/icon.svg +9 -9
  6. package/assets/logo-dark.svg +11 -11
  7. package/assets/logo-light.svg +11 -11
  8. package/dashboard/README.md +91 -91
  9. package/dashboard/dist/assets/index-D6Xyje_n.js.map +1 -1
  10. package/dashboard/dist/index.html +19 -19
  11. package/dashboard/package.json +47 -47
  12. package/dist/adapters/copilot/adapter.js +12 -1
  13. package/dist/cli/global-wrapper.d.ts +19 -0
  14. package/dist/cli/global-wrapper.js +169 -0
  15. package/dist/cli/help-text.js +97 -97
  16. package/dist/cli/startup.js +11 -0
  17. package/dist/cli/upgrade-command.js +81 -81
  18. package/dist/cli.js +12 -0
  19. package/dist/daemon.js +5 -0
  20. package/dist/scripts/verify-daemon-isolation-guard.js +24 -24
  21. package/dist/server.js +4 -0
  22. package/dist/spawn.js +12 -12
  23. package/dist/tools/coat-check-evict.js +2 -2
  24. package/dist/tools/coat-check-get.js +2 -2
  25. package/dist/tools/coat-check-put.js +4 -4
  26. package/dist/tools/fetch-state.js +2 -2
  27. package/dist/tools/save-state.js +13 -13
  28. package/dist/utils/grpc-shutdown-guard.d.ts +52 -0
  29. package/dist/utils/grpc-shutdown-guard.js +88 -0
  30. package/examples/agents/tempo-composer.md +56 -56
  31. package/examples/agents/tempo-conductor.md +117 -117
  32. package/examples/agents/tempo-critic.md +73 -73
  33. package/examples/agents/tempo-improv.md +74 -74
  34. package/examples/agents/tempo-liner.md +75 -75
  35. package/examples/agents/tempo-roadie.md +61 -61
  36. package/examples/agents/tempo-soloist.md +71 -71
  37. package/examples/agents/tempo-tuner.md +94 -94
  38. package/examples/ensembles/tempo-big-band.yaml +146 -146
  39. package/examples/ensembles/tempo-dev-team.yaml +58 -58
  40. package/examples/ensembles/tempo-headless-jam.yaml +77 -77
  41. package/examples/ensembles/tempo-jam-session.yaml +41 -41
  42. package/examples/ensembles/tempo-mock-jam.yaml +79 -79
  43. package/examples/ensembles/tempo-review-squad.yaml +32 -32
  44. package/package.json +173 -173
  45. package/packaging/launchd/com.agent.tempo.plist +46 -46
  46. package/packaging/systemd/agent-tempo.service +32 -32
  47. package/packaging/windows/install-task.ps1 +71 -71
  48. package/scenarios/conductor-recruit-mock.yaml +33 -33
  49. package/scenarios/echo-roundtrip.yaml +15 -15
  50. package/scenarios/multi-player-handoff.yaml +38 -38
  51. package/scenarios/recruit-cascade.yaml +38 -38
  52. package/scenarios/two-player-conversation.yaml +33 -33
  53. package/workflow-bundle.js +1 -1
  54. package/dist/activities/claude-stop.d.ts +0 -21
  55. package/dist/activities/claude-stop.js +0 -94
  56. package/dist/channel.d.ts +0 -3
  57. package/dist/channel.js +0 -48
  58. package/dist/copilot-bridge.d.ts +0 -22
  59. package/dist/copilot-bridge.js +0 -565
  60. package/dist/scripts/258-spotcheck.js +0 -303
  61. package/dist/tools/detach.d.ts +0 -4
  62. package/dist/tools/detach.js +0 -45
  63. package/dist/tools/encore.d.ts +0 -4
  64. package/dist/tools/encore.js +0 -31
  65. package/dist/tools/pause-ensemble.d.ts +0 -4
  66. package/dist/tools/pause-ensemble.js +0 -58
  67. package/dist/tools/resume-ensemble.d.ts +0 -4
  68. package/dist/tools/resume-ensemble.js +0 -79
  69. package/dist/tools/stop.d.ts +0 -4
  70. package/dist/tools/stop.js +0 -29
  71. package/dist/tui/client.d.ts +0 -6
  72. package/dist/tui/client.js +0 -9
  73. package/dist/tui/components/ActivityLog.d.ts +0 -16
  74. package/dist/tui/components/ActivityLog.js +0 -36
  75. package/dist/tui/components/CommandOverlay.d.ts +0 -15
  76. package/dist/tui/components/CommandOverlay.js +0 -34
  77. package/dist/tui/components/ConductorChat.d.ts +0 -16
  78. package/dist/tui/components/ConductorChat.js +0 -32
  79. package/dist/tui/components/EnsembleListView.d.ts +0 -14
  80. package/dist/tui/components/EnsembleListView.js +0 -32
  81. package/dist/tui/components/EnsemblePanel.d.ts +0 -12
  82. package/dist/tui/components/EnsemblePanel.js +0 -40
  83. package/dist/tui/components/InputBar.d.ts +0 -13
  84. package/dist/tui/components/InputBar.js +0 -58
  85. package/dist/tui/components/ScheduleOverlay.d.ts +0 -13
  86. package/dist/tui/components/ScheduleOverlay.js +0 -113
  87. package/dist/tui/components/TopBar.d.ts +0 -12
  88. package/dist/tui/components/TopBar.js +0 -15
  89. package/dist/tui/core-api.d.ts +0 -26
  90. package/dist/tui/core-api.js +0 -67
  91. package/dist/tui/hooks/useEnsembleDiscovery.d.ts +0 -3
  92. package/dist/tui/hooks/useEnsembleDiscovery.js +0 -30
  93. package/dist/tui/hooks/useMaestroPoller.d.ts +0 -3
  94. package/dist/tui/hooks/useMaestroPoller.js +0 -36
  95. package/dist/tui/hooks/useSendCommand.d.ts +0 -7
  96. package/dist/tui/hooks/useSendCommand.js +0 -29
  97. package/dist/utils/bg-preflight.d.ts +0 -25
  98. package/dist/utils/bg-preflight.js +0 -154
package/README.md CHANGED
@@ -1,289 +1,289 @@
1
- <p align="center">
2
- <picture>
3
- <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.svg">
4
- <source media="(prefers-color-scheme: light)" srcset="assets/logo-light.svg">
5
- <img alt="agent-tempo" src="assets/logo-light.svg" height="140">
6
- </picture>
7
- </p>
8
- <p align="center">
9
- <strong>Many agents, one tempo.</strong>
10
- </p>
11
- <p align="center">
12
- <a href="https://www.npmjs.com/package/agent-tempo"><img src="https://img.shields.io/npm/v/agent-tempo.svg" alt="npm version"></a>
13
- <a href="https://github.com/vinceblank/agent-tempo/actions/workflows/ci.yml"><img src="https://github.com/vinceblank/agent-tempo/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
14
- <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
15
- </p>
16
-
17
- Multiple Claude Code sessions discover each other, exchange messages in real time, and coordinate work — across machines, not just localhost.
18
-
19
- 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.
20
-
21
- 📖 **[Full documentation](docs/README.md)**
22
-
23
- ## Why agent-tempo?
24
-
25
- - **Crash-safe durability** — Sessions are Temporal workflows. Crashes, restarts, and network blips don't lose messages or drop coordination state.
26
- - **Instant signaling** — Temporal signals deliver messages with no polling. Players receive cues the moment they're sent, regardless of which machine they're on.
27
- - **Built-in scheduling** — One-shot and recurring message schedules without any external infrastructure.
28
- - **Extensible agent types** — Define reusable player roles as `.md` files. Ship lineups that assemble entire teams in one command.
29
-
30
- ## Features
31
-
32
- | | |
33
- |---|---|
34
- | 🔁 **Ensemble Lineups** | YAML configs that define a full team and recruit them all in one command |
35
- | ⏰ **Scheduling** | One-shot and recurring message schedules with fan-out and failure notifications |
36
- | 🎭 **Player Types** | Reusable agent definitions with 8 shipped types and three-tier lookup |
37
- | 🖥️ **Terminal UI** | Chat-focused TUI with slash commands, overlays, and interactive wizards |
38
- | 🌐 **Cross-machine** | Any session that can reach your Temporal server can join the ensemble |
39
- | ⏸️ **Hold / Pause / Resume** | Pre-warm a full team before delivering tasks; pause and resume mid-session |
40
- | 🤖 **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 |
41
-
42
- ## Installation
43
-
44
- ```bash
45
- npm install -g agent-tempo
46
- ```
47
-
48
- **Prerequisites**: [Node.js](https://nodejs.org/) 20 LTS, 22 LTS, or 24 LTS, [Temporal CLI](https://docs.temporal.io/cli), [Claude Code](https://claude.ai/code)
49
-
50
- ## Quick Start
51
-
52
- One command handles everything:
53
-
54
- ```bash
55
- cd your-project
56
- agent-tempo up
57
- ```
58
-
59
- This starts Temporal, registers the MCP server, launches the daemon, and opens a conductor session. Then add players:
60
-
61
- ```bash
62
- agent-tempo status # see who's active
63
- ```
64
-
65
- Or use the TUI to recruit players, or ask the conductor to `recruit` from inside Claude Code.
66
-
67
- ### Manual setup
68
-
69
- ```bash
70
- agent-tempo server # start Temporal dev server
71
- agent-tempo init # register MCP server globally
72
- agent-tempo preflight # verify environment
73
- agent-tempo up # launch conductor via auto-provisioning
74
- ```
75
-
76
- ## Upgrading
77
-
78
- ```bash
79
- agent-tempo upgrade
80
- ```
81
-
82
- Stops the daemon, installs the latest version, and restarts automatically. To upgrade to a specific version:
83
-
84
- ```bash
85
- agent-tempo upgrade 0.22.0
86
- ```
87
-
88
- ## Stopping & Tear Down
89
-
90
- ```bash
91
- # Terminate all sessions in an ensemble
92
- agent-tempo destroy my-ensemble
93
-
94
- # Tear down everything (all sessions, schedulers, and Maestro workflows)
95
- agent-tempo down --all
96
-
97
- # Tear down and terminate all workflows in one step
98
- agent-tempo down --destroy -y
99
-
100
- # Stop the background daemon
101
- agent-tempo daemon stop
102
- ```
103
-
104
- 📖 [Full CLI reference → docs/cli.md](docs/cli.md)
105
-
106
- ---
107
-
108
- ## Core Concepts
109
-
110
- - **Player** — A Claude Code session registered as a Temporal workflow
111
- - **Conductor** — Required orchestration hub (one per ensemble); receives `report` calls and connects to external interfaces. Lineup schema enforces its presence.
112
- - **Ensemble** — A named group of players isolated from other ensembles; defaults to `default`
113
- - **Cue** — A message sent to a player by name via Temporal signal
114
- - **Lineup** — A YAML file that defines a full team and recruits them in one step
115
- - **Player Type** — A reusable agent definition (`.md` with YAML frontmatter) that gives a player a named role
116
-
117
- 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:
118
-
119
- ```bash
120
- agent-tempo up frontend # provision and launch conductor in "frontend"
121
- agent-tempo up backend # provision and launch conductor in "backend"
122
- ```
123
-
124
- ## MCP Tools
125
-
126
- Tools available inside Claude Code sessions connected to agent-tempo:
127
-
128
- | Tool | Description |
129
- |------|-------------|
130
- | `ensemble` | Discover active sessions |
131
- | `cue` | Send a message to a player by name |
132
- | `recruit` | Spawn a new Claude Code session |
133
- | `report` | Send updates to the conductor |
134
- | `broadcast` | Send a message to all active players |
135
- | `recall` | Read your own message history |
136
- | `who_am_i` | Get your identity, role, and player type |
137
-
138
- 📖 [Full tools reference → docs/tools.md](docs/tools.md) (includes `schedule`, `stage`, `quality_gate`, `worktree`, and all others)
139
-
140
- ## CLI
141
-
142
- ```bash
143
- agent-tempo # launch TUI (auto-provisions on first run)
144
- agent-tempo up [ensemble] # provision infrastructure and launch conductor
145
- agent-tempo down [--destroy] # tear down infrastructure (--destroy also terminates workflows)
146
- agent-tempo status [ensemble] # list active sessions
147
- agent-tempo destroy <ensemble> # terminate all sessions in an ensemble
148
- agent-tempo restore <ensemble> # restore orphaned sessions on this host
149
- agent-tempo hosts # list daemons polling this Temporal namespace (--all/--json)
150
- agent-tempo recall <name> # read a player's message history (--limit/--offset/--preview/--json)
151
- agent-tempo attachment-info <name> # inspect a session's phase, holder, lease, and heartbeat age
152
- agent-tempo release [ensemble] # release held players (unlock + deliver tasks)
153
- agent-tempo daemon <sub> # manage the worker daemon
154
- agent-tempo upgrade # update to latest
155
- ```
156
-
157
- Run `agent-tempo --help` or `agent-tempo <command> --help` for all flags.
158
-
159
- 📖 [Full CLI reference → docs/cli.md](docs/cli.md)
160
-
161
- ## Ensemble Lineups
162
-
163
- Define reusable team configurations as YAML files and load them in one command:
164
-
165
- ```yaml
166
- name: my-project
167
- conductor:
168
- instructions: "Coordinate the frontend and backend teams"
169
- players:
170
- - name: frontend
171
- type: tempo-soloist
172
- workDir: /repos/my-app
173
- instructions: "Build the React dashboard"
174
- - name: backend
175
- type: tempo-soloist
176
- workDir: /repos/my-api
177
- instructions: "Implement the REST endpoints"
178
- schedules:
179
- - name: status-check
180
- message: "Report your current progress"
181
- target: all
182
- every: 30m
183
- ```
184
-
185
- ```bash
186
- agent-tempo up --lineup my-project.yaml # load from CLI
187
- ```
188
-
189
- Or from inside a session: *"Load the my-project lineup"*
190
-
191
- 📖 [Lineups, player types, and shipped examples → docs/ensembles.md](docs/ensembles.md)
192
-
193
- ## Player Types
194
-
195
- Player types are reusable agent definitions — `.md` files with YAML frontmatter. Reference them by name in lineups:
196
-
197
- ```yaml
198
- players:
199
- - name: arch
200
- type: tempo-composer
201
- - name: eng
202
- type: tempo-soloist
203
- ```
204
-
205
- 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`.
206
-
207
- ```bash
208
- agent-tempo agent-types list # discover available types
209
- agent-tempo agent-types init # copy shipped types to ~/.claude/agents/
210
- ```
211
-
212
- 📖 [Player types deep dive → docs/ensembles.md](docs/ensembles.md)
213
-
214
- ## Configuration
215
-
216
- ```bash
217
- agent-tempo config # interactive setup (Temporal address, namespace, API key)
218
- ```
219
-
220
- Settings persist in `~/.agent-tempo/config.json`. Resolution order: CLI flags → env vars → config file → Temporal CLI config → defaults.
221
-
222
- Key environment variables:
223
-
224
- | Variable | Default | Description |
225
- |----------|---------|-------------|
226
- | `TEMPORAL_ADDRESS` | `localhost:7233` | Temporal server address |
227
- | `TEMPORAL_NAMESPACE` | `default` | Temporal namespace |
228
- | `TEMPORAL_API_KEY` | *(none)* | Temporal Cloud API key |
229
- | `CLAUDE_TEMPO_ENSEMBLE` | `default` | Ensemble name |
230
-
231
- 📖 [Full configuration reference → docs/configuration.md](docs/configuration.md)
232
-
233
- ## Terminal UI
234
-
235
- ```bash
236
- agent-tempo tui # multi-ensemble home screen
237
- agent-tempo tui --ensemble my-ensemble # direct ensemble mode
238
- ```
239
-
240
- The TUI provides a chat-focused shell for managing your ensemble:
241
-
242
- - **Ensemble chat feed** — live aggregated view of conductor + player traffic; type bare text to message the conductor, `@player message` to message directly
243
- - **Slash commands** — `/recruit`, `/status`, `/schedule`, `/gates`, `/stages`, `/worktree`, `/go` (release held), `/pause`, `/play`, `/shutdown`, `/restore`, `/home`, and more; type `/help` for the full list
244
- - **Interactive overlays and wizards** — step-by-step flows for recruiting players, creating schedules, and managing ensembles
245
-
246
- 📖 [TUI reference → docs/tui.md](docs/tui.md)
247
-
248
- ## Copilot Integration
249
-
250
- > **Experimental** — subject to breaking changes.
251
-
252
- GitHub Copilot CLI sessions can join an ensemble using `--agent copilot`. Recruit one from the TUI:
253
-
254
- ```
255
- /recruit copilot-1 --agent copilot
256
- ```
257
-
258
- 📖 [Copilot bridge setup and limitations → docs/copilot.md](docs/copilot.md)
259
-
260
- ## Worker Daemon
261
-
262
- 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`.
263
-
264
- 📖 [Daemon reference → docs/daemon.md](docs/daemon.md)
265
-
266
- ## Development
267
-
268
- ```bash
269
- git clone https://github.com/vinceblank/agent-tempo.git
270
- cd agent-tempo && npm install
271
-
272
- npm run build # compile TypeScript + pre-bundle workflows
273
- npm test # run tests
274
- npm link # link CLI for local testing
275
- ```
276
-
277
- > **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.
278
-
279
- ## Contributing
280
-
281
- See [CLAUDE.md](CLAUDE.md) for project structure, conventions, and development setup. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the three-layer session model (workflow / adapter / process). Pull requests welcome — run `npm test` before submitting.
282
-
283
- ## Known Limitations
284
-
285
- - **`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.
286
-
287
- ## License
288
-
289
- MIT
1
+ <p align="center">
2
+ <picture>
3
+ <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.svg">
4
+ <source media="(prefers-color-scheme: light)" srcset="assets/logo-light.svg">
5
+ <img alt="agent-tempo" src="assets/logo-light.svg" height="140">
6
+ </picture>
7
+ </p>
8
+ <p align="center">
9
+ <strong>Many agents, one tempo.</strong>
10
+ </p>
11
+ <p align="center">
12
+ <a href="https://www.npmjs.com/package/agent-tempo"><img src="https://img.shields.io/npm/v/agent-tempo.svg" alt="npm version"></a>
13
+ <a href="https://github.com/vinceblank/agent-tempo/actions/workflows/ci.yml"><img src="https://github.com/vinceblank/agent-tempo/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
14
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
15
+ </p>
16
+
17
+ Multiple Claude Code sessions discover each other, exchange messages in real time, and coordinate work — across machines, not just localhost.
18
+
19
+ 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.
20
+
21
+ 📖 **[Full documentation](docs/README.md)**
22
+
23
+ ## Why agent-tempo?
24
+
25
+ - **Crash-safe durability** — Sessions are Temporal workflows. Crashes, restarts, and network blips don't lose messages or drop coordination state.
26
+ - **Instant signaling** — Temporal signals deliver messages with no polling. Players receive cues the moment they're sent, regardless of which machine they're on.
27
+ - **Built-in scheduling** — One-shot and recurring message schedules without any external infrastructure.
28
+ - **Extensible agent types** — Define reusable player roles as `.md` files. Ship lineups that assemble entire teams in one command.
29
+
30
+ ## Features
31
+
32
+ | | |
33
+ |---|---|
34
+ | 🔁 **Ensemble Lineups** | YAML configs that define a full team and recruit them all in one command |
35
+ | ⏰ **Scheduling** | One-shot and recurring message schedules with fan-out and failure notifications |
36
+ | 🎭 **Player Types** | Reusable agent definitions with 8 shipped types and three-tier lookup |
37
+ | 🖥️ **Terminal UI** | Chat-focused TUI with slash commands, overlays, and interactive wizards |
38
+ | 🌐 **Cross-machine** | Any session that can reach your Temporal server can join the ensemble |
39
+ | ⏸️ **Hold / Pause / Resume** | Pre-warm a full team before delivering tasks; pause and resume mid-session |
40
+ | 🤖 **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 |
41
+
42
+ ## Installation
43
+
44
+ ```bash
45
+ npm install -g agent-tempo
46
+ ```
47
+
48
+ **Prerequisites**: [Node.js](https://nodejs.org/) 20 LTS, 22 LTS, or 24 LTS, [Temporal CLI](https://docs.temporal.io/cli), [Claude Code](https://claude.ai/code)
49
+
50
+ ## Quick Start
51
+
52
+ One command handles everything:
53
+
54
+ ```bash
55
+ cd your-project
56
+ agent-tempo up
57
+ ```
58
+
59
+ This starts Temporal, registers the MCP server, launches the daemon, and opens a conductor session. Then add players:
60
+
61
+ ```bash
62
+ agent-tempo status # see who's active
63
+ ```
64
+
65
+ Or use the TUI to recruit players, or ask the conductor to `recruit` from inside Claude Code.
66
+
67
+ ### Manual setup
68
+
69
+ ```bash
70
+ agent-tempo server # start Temporal dev server
71
+ agent-tempo init # register MCP server globally
72
+ agent-tempo preflight # verify environment
73
+ agent-tempo up # launch conductor via auto-provisioning
74
+ ```
75
+
76
+ ## Upgrading
77
+
78
+ ```bash
79
+ agent-tempo upgrade
80
+ ```
81
+
82
+ Stops the daemon, installs the latest version, and restarts automatically. To upgrade to a specific version:
83
+
84
+ ```bash
85
+ agent-tempo upgrade 0.22.0
86
+ ```
87
+
88
+ ## Stopping & Tear Down
89
+
90
+ ```bash
91
+ # Terminate all sessions in an ensemble
92
+ agent-tempo destroy my-ensemble
93
+
94
+ # Tear down everything (all sessions, schedulers, and Maestro workflows)
95
+ agent-tempo down --all
96
+
97
+ # Tear down and terminate all workflows in one step
98
+ agent-tempo down --destroy -y
99
+
100
+ # Stop the background daemon
101
+ agent-tempo daemon stop
102
+ ```
103
+
104
+ 📖 [Full CLI reference → docs/cli.md](docs/cli.md)
105
+
106
+ ---
107
+
108
+ ## Core Concepts
109
+
110
+ - **Player** — A Claude Code session registered as a Temporal workflow
111
+ - **Conductor** — Required orchestration hub (one per ensemble); receives `report` calls and connects to external interfaces. Lineup schema enforces its presence.
112
+ - **Ensemble** — A named group of players isolated from other ensembles; defaults to `default`
113
+ - **Cue** — A message sent to a player by name via Temporal signal
114
+ - **Lineup** — A YAML file that defines a full team and recruits them in one step
115
+ - **Player Type** — A reusable agent definition (`.md` with YAML frontmatter) that gives a player a named role
116
+
117
+ 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:
118
+
119
+ ```bash
120
+ agent-tempo up frontend # provision and launch conductor in "frontend"
121
+ agent-tempo up backend # provision and launch conductor in "backend"
122
+ ```
123
+
124
+ ## MCP Tools
125
+
126
+ Tools available inside Claude Code sessions connected to agent-tempo:
127
+
128
+ | Tool | Description |
129
+ |------|-------------|
130
+ | `ensemble` | Discover active sessions |
131
+ | `cue` | Send a message to a player by name |
132
+ | `recruit` | Spawn a new Claude Code session |
133
+ | `report` | Send updates to the conductor |
134
+ | `broadcast` | Send a message to all active players |
135
+ | `recall` | Read your own message history |
136
+ | `who_am_i` | Get your identity, role, and player type |
137
+
138
+ 📖 [Full tools reference → docs/tools.md](docs/tools.md) (includes `schedule`, `stage`, `quality_gate`, `worktree`, and all others)
139
+
140
+ ## CLI
141
+
142
+ ```bash
143
+ agent-tempo # launch TUI (auto-provisions on first run)
144
+ agent-tempo up [ensemble] # provision infrastructure and launch conductor
145
+ agent-tempo down [--destroy] # tear down infrastructure (--destroy also terminates workflows)
146
+ agent-tempo status [ensemble] # list active sessions
147
+ agent-tempo destroy <ensemble> # terminate all sessions in an ensemble
148
+ agent-tempo restore <ensemble> # restore orphaned sessions on this host
149
+ agent-tempo hosts # list daemons polling this Temporal namespace (--all/--json)
150
+ agent-tempo recall <name> # read a player's message history (--limit/--offset/--preview/--json)
151
+ agent-tempo attachment-info <name> # inspect a session's phase, holder, lease, and heartbeat age
152
+ agent-tempo release [ensemble] # release held players (unlock + deliver tasks)
153
+ agent-tempo daemon <sub> # manage the worker daemon
154
+ agent-tempo upgrade # update to latest
155
+ ```
156
+
157
+ Run `agent-tempo --help` or `agent-tempo <command> --help` for all flags.
158
+
159
+ 📖 [Full CLI reference → docs/cli.md](docs/cli.md)
160
+
161
+ ## Ensemble Lineups
162
+
163
+ Define reusable team configurations as YAML files and load them in one command:
164
+
165
+ ```yaml
166
+ name: my-project
167
+ conductor:
168
+ instructions: "Coordinate the frontend and backend teams"
169
+ players:
170
+ - name: frontend
171
+ type: tempo-soloist
172
+ workDir: /repos/my-app
173
+ instructions: "Build the React dashboard"
174
+ - name: backend
175
+ type: tempo-soloist
176
+ workDir: /repos/my-api
177
+ instructions: "Implement the REST endpoints"
178
+ schedules:
179
+ - name: status-check
180
+ message: "Report your current progress"
181
+ target: all
182
+ every: 30m
183
+ ```
184
+
185
+ ```bash
186
+ agent-tempo up --lineup my-project.yaml # load from CLI
187
+ ```
188
+
189
+ Or from inside a session: *"Load the my-project lineup"*
190
+
191
+ 📖 [Lineups, player types, and shipped examples → docs/ensembles.md](docs/ensembles.md)
192
+
193
+ ## Player Types
194
+
195
+ Player types are reusable agent definitions — `.md` files with YAML frontmatter. Reference them by name in lineups:
196
+
197
+ ```yaml
198
+ players:
199
+ - name: arch
200
+ type: tempo-composer
201
+ - name: eng
202
+ type: tempo-soloist
203
+ ```
204
+
205
+ 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`.
206
+
207
+ ```bash
208
+ agent-tempo agent-types list # discover available types
209
+ agent-tempo agent-types init # copy shipped types to ~/.claude/agents/
210
+ ```
211
+
212
+ 📖 [Player types deep dive → docs/ensembles.md](docs/ensembles.md)
213
+
214
+ ## Configuration
215
+
216
+ ```bash
217
+ agent-tempo config # interactive setup (Temporal address, namespace, API key)
218
+ ```
219
+
220
+ Settings persist in `~/.agent-tempo/config.json`. Resolution order: CLI flags → env vars → config file → Temporal CLI config → defaults.
221
+
222
+ Key environment variables:
223
+
224
+ | Variable | Default | Description |
225
+ |----------|---------|-------------|
226
+ | `TEMPORAL_ADDRESS` | `localhost:7233` | Temporal server address |
227
+ | `TEMPORAL_NAMESPACE` | `default` | Temporal namespace |
228
+ | `TEMPORAL_API_KEY` | *(none)* | Temporal Cloud API key |
229
+ | `CLAUDE_TEMPO_ENSEMBLE` | `default` | Ensemble name |
230
+
231
+ 📖 [Full configuration reference → docs/configuration.md](docs/configuration.md)
232
+
233
+ ## Terminal UI
234
+
235
+ ```bash
236
+ agent-tempo tui # multi-ensemble home screen
237
+ agent-tempo tui --ensemble my-ensemble # direct ensemble mode
238
+ ```
239
+
240
+ The TUI provides a chat-focused shell for managing your ensemble:
241
+
242
+ - **Ensemble chat feed** — live aggregated view of conductor + player traffic; type bare text to message the conductor, `@player message` to message directly
243
+ - **Slash commands** — `/recruit`, `/status`, `/schedule`, `/gates`, `/stages`, `/worktree`, `/go` (release held), `/pause`, `/play`, `/shutdown`, `/restore`, `/home`, and more; type `/help` for the full list
244
+ - **Interactive overlays and wizards** — step-by-step flows for recruiting players, creating schedules, and managing ensembles
245
+
246
+ 📖 [TUI reference → docs/tui.md](docs/tui.md)
247
+
248
+ ## Copilot Integration
249
+
250
+ > **Experimental** — subject to breaking changes.
251
+
252
+ GitHub Copilot CLI sessions can join an ensemble using `--agent copilot`. Recruit one from the TUI:
253
+
254
+ ```
255
+ /recruit copilot-1 --agent copilot
256
+ ```
257
+
258
+ 📖 [Copilot bridge setup and limitations → docs/copilot.md](docs/copilot.md)
259
+
260
+ ## Worker Daemon
261
+
262
+ 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`.
263
+
264
+ 📖 [Daemon reference → docs/daemon.md](docs/daemon.md)
265
+
266
+ ## Development
267
+
268
+ ```bash
269
+ git clone https://github.com/vinceblank/agent-tempo.git
270
+ cd agent-tempo && npm install
271
+
272
+ npm run build # compile TypeScript + pre-bundle workflows
273
+ npm test # run tests
274
+ npm link # link CLI for local testing
275
+ ```
276
+
277
+ > **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.
278
+
279
+ ## Contributing
280
+
281
+ See [CLAUDE.md](CLAUDE.md) for project structure, conventions, and development setup. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the three-layer session model (workflow / adapter / process). Pull requests welcome — run `npm test` before submitting.
282
+
283
+ ## Known Limitations
284
+
285
+ - **`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.
286
+
287
+ ## License
288
+
289
+ MIT
@@ -1,9 +1,9 @@
1
- <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" fill="none">
2
- <!-- Ultra-minimal metronome icon: triangle + pendulum (dark mode) -->
3
- <!-- Metronome body — single-stroke triangle -->
4
- <path d="M32 8 L14 54 L50 54 Z" stroke="#FAF3EE" stroke-width="3" fill="none" stroke-linejoin="round"/>
5
- <!-- Pendulum arm (angled right) -->
6
- <line x1="32" y1="46" x2="44" y2="14" stroke="#E07A5F" stroke-width="3" stroke-linecap="round"/>
7
- <!-- Pivot dot -->
8
- <circle cx="32" cy="46" r="3" fill="#E07A5F"/>
9
- </svg>
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" fill="none">
2
+ <!-- Ultra-minimal metronome icon: triangle + pendulum (dark mode) -->
3
+ <!-- Metronome body — single-stroke triangle -->
4
+ <path d="M32 8 L14 54 L50 54 Z" stroke="#FAF3EE" stroke-width="3" fill="none" stroke-linejoin="round"/>
5
+ <!-- Pendulum arm (angled right) -->
6
+ <line x1="32" y1="46" x2="44" y2="14" stroke="#E07A5F" stroke-width="3" stroke-linecap="round"/>
7
+ <!-- Pivot dot -->
8
+ <circle cx="32" cy="46" r="3" fill="#E07A5F"/>
9
+ </svg>
package/assets/icon.svg CHANGED
@@ -1,9 +1,9 @@
1
- <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" fill="none">
2
- <!-- Ultra-minimal metronome icon: triangle + pendulum -->
3
- <!-- Metronome body — single-stroke triangle -->
4
- <path d="M32 8 L14 54 L50 54 Z" stroke="#1B2838" stroke-width="3" fill="none" stroke-linejoin="round"/>
5
- <!-- Pendulum arm (angled right) -->
6
- <line x1="32" y1="46" x2="44" y2="14" stroke="#E07A5F" stroke-width="3" stroke-linecap="round"/>
7
- <!-- Pivot dot -->
8
- <circle cx="32" cy="46" r="3" fill="#E07A5F"/>
9
- </svg>
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" fill="none">
2
+ <!-- Ultra-minimal metronome icon: triangle + pendulum -->
3
+ <!-- Metronome body — single-stroke triangle -->
4
+ <path d="M32 8 L14 54 L50 54 Z" stroke="#1B2838" stroke-width="3" fill="none" stroke-linejoin="round"/>
5
+ <!-- Pendulum arm (angled right) -->
6
+ <line x1="32" y1="46" x2="44" y2="14" stroke="#E07A5F" stroke-width="3" stroke-linecap="round"/>
7
+ <!-- Pivot dot -->
8
+ <circle cx="32" cy="46" r="3" fill="#E07A5F"/>
9
+ </svg>
@@ -1,11 +1,11 @@
1
- <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 140" fill="none">
2
- <!-- Ultra-minimal metronome: triangle outline + pendulum line (dark mode) -->
3
- <!-- Metronome body — single-stroke triangle -->
4
- <path d="M160 18 L122 100 L198 100 Z" stroke="#FAF3EE" stroke-width="3" fill="none" stroke-linejoin="round"/>
5
- <!-- Pendulum arm (angled right ~18deg) -->
6
- <line x1="160" y1="88" x2="182" y2="24" stroke="#E07A5F" stroke-width="3" stroke-linecap="round"/>
7
- <!-- Pivot dot -->
8
- <circle cx="160" cy="88" r="3.5" fill="#E07A5F"/>
9
- <!-- Text -->
10
- <text x="160" y="132" text-anchor="middle" font-family="'JetBrains Mono','SF Mono','Consolas',monospace" font-size="18" font-weight="600" fill="#FAF3EE" letter-spacing="-0.5">agent-tempo</text>
11
- </svg>
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 140" fill="none">
2
+ <!-- Ultra-minimal metronome: triangle outline + pendulum line (dark mode) -->
3
+ <!-- Metronome body — single-stroke triangle -->
4
+ <path d="M160 18 L122 100 L198 100 Z" stroke="#FAF3EE" stroke-width="3" fill="none" stroke-linejoin="round"/>
5
+ <!-- Pendulum arm (angled right ~18deg) -->
6
+ <line x1="160" y1="88" x2="182" y2="24" stroke="#E07A5F" stroke-width="3" stroke-linecap="round"/>
7
+ <!-- Pivot dot -->
8
+ <circle cx="160" cy="88" r="3.5" fill="#E07A5F"/>
9
+ <!-- Text -->
10
+ <text x="160" y="132" text-anchor="middle" font-family="'JetBrains Mono','SF Mono','Consolas',monospace" font-size="18" font-weight="600" fill="#FAF3EE" letter-spacing="-0.5">agent-tempo</text>
11
+ </svg>