Repository navigation
Description
Phase 1 — Headless OpenCode adapter (THIS ISSUE — `approved`)
Add a new adapter src/adapters/opencode/ (peer of claude-code/, copilot/, and the planned claude-api/ from #131) that bridges to a local opencode serve process. This unlocks the multi-LLM story: an ensemble can mix players running on Claude, GPT-4o, local Ollama, etc., all coordinated through the same Temporal hub.
Adapter target
SST's OpenCode — https://opencode.ai, https://github.com/sst/opencode
Actively maintained, multi-provider native, has both TUI and `opencode serve` HTTP API modes.
Pattern: server/HTTP-bridge (NOT TUI-wrap)
`opencode serve` exposes a clean HTTP/streaming API. Adapter mirrors the `copilot` SDK-bridge pattern via `SdkAttachment` — own the message loop, no terminal lifecycle baggage.
Headless-first is deliberate: TUI-wrap would inherit the same TTY-bypass / dev-channels / terminal-process constraints we already paid for in `claude-code`. Server mode skips all of that.
Provider strategy: provider-agnostic
claude-tempo does NOT choose the LLM. Users configure OpenCode with whatever provider/model they want — Anthropic, OpenAI, Bedrock, Ollama, etc. — and claude-tempo just routes messages to the OpenCode session. The adapter exposes provider/model as opaque config strings passed through to OpenCode.
This makes the multi-LLM story real: an ensemble can run mixed sessions where some players use Claude, some use GPT-4o, some use local Ollama, all coordinating through the same Temporal hub.
Phase 1 scope (THIS ISSUE)
- New `src/adapters/opencode/` directory
- `adapter.ts` — `OpenCodeAttachment extends SdkAttachment` (matches Copilot adapter pattern — owns its own message loop)
- `server-bridge.ts` — HTTP/SSE client for local `opencode serve` process
- `index.ts` — registry descriptor
- Spawn path: `recruit` tool's `adapter:` parameter (introduced by feat(adapters): Claude API adapter (Phase 1 — headless, no advisor) #131) accepts `'opencode'` as another value
- Provider/model config passed through to OpenCode (not interpreted by us)
- Auth: whatever OpenCode expects (provider-agnostic — `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc., resolved by OpenCode itself)
- Bridges MCP tools (cue, report, recall, ensemble, …) into OpenCode's tool-calling surface each turn
- Full lifecycle compliance (claim, heartbeat, phase progression, graceful detach) — same as existing adapters
- Streaming: maps OpenCode's streaming events to the existing message delivery shape
- `opencode serve` process lifecycle: spawn-on-claim, terminate-on-detach, restart-on-crash (mirrors how Copilot bridge handles its subprocess)
Out of scope for Phase 1
- Cost/usage telemetry per-provider — Phase 2 (separate issue, not yet filed)
- Provider-aware throttling/quota tracking — Phase 2
- Cross-provider parity testing (do all providers honor the same MCP tool surface? cue/report/recall etc.) — Phase 2
- TUI-mode adapter — out entirely. If needed later, file as separate issue.
Acceptance criteria (Phase 1)
- `recruit` with `adapter: 'opencode'` spawns a player that connects via local `opencode serve` instead of CLI/Messages-API
- The player participates correctly in cue/report/broadcast/recall/destroy/restart/restore/shutdown lifecycle
- Turns are observable in standard claude-tempo telemetry (heartbeat, phase, attachment)
- Existing claude-code, copilot, and claude-api (post-feat(adapters): Claude API adapter (Phase 1 — headless, no advisor) #131) adapters unaffected
- Documentation: `src/adapters/README.md` + `docs/concepts.md` updated to describe the four adapter types
- Tests: vitest unit + mocha integration covering spawn → claim → turn → detach lifecycle
Implementation phases
Same flow as #131 / #318 / #319 / #334:
- Phase A (research) — tempo-researcher: SST OpenCode `opencode serve` API surface, lifecycle behavior, streaming event shape, multi-provider config conventions, dependency stability assessment
- Phase B (design) — tempo-architect: design doc + ADR for adapter shape, spawn integration, tool bridging, streaming model, subprocess lifecycle, provider config plumbing
- Phase C (implementation) — engineer: ~600-1000 LoC across new adapter directory + recruit tool extension + tests + docs
Risk callout
Third-party dependency surface area. SST's OpenCode is actively maintained but not Anthropic-owned — claude-tempo inherits the lifecycle risk:
- Abandonment risk (smaller upstream community than Anthropic)
- Breaking changes in `opencode serve` HTTP API
- Security bugs in the bridge process
#131's Claude API adapter is the in-house alternative if this risk ever bites — claude-tempo retains a first-party path. Worth documenting in the ADR that OpenCode-first multi-LLM is a deliberate choice with a known fallback.
Sequencing
- Gated on feat(adapters): Claude API adapter (Phase 1 — headless, no advisor) #131 (Claude API adapter Phase 1) — both PRs would otherwise add the `adapter:` parameter to the `recruit` tool. feat(adapters): Claude API adapter (Phase 1 — headless, no advisor) #131 introduces the parameter, this issue extends the union.
- Researcher → Architect → Engineer flow, same as feat(adapters): Claude API adapter (Phase 1 — headless, no advisor) #131.
- Implementation starts after feat(adapters): Claude API adapter (Phase 1 — headless, no advisor) #131's Phase A research lands at minimum (so we know the `recruit` parameter shape before designing OpenCode's slot in it).
Closes / supersedes
- N/A — net-new issue. Companion to feat(adapters): Claude API adapter (Phase 1 — headless, no advisor) #131. Together they unlock the multi-adapter, multi-provider future of claude-tempo.
🎼 Posted by claude-tempo[bot] —
an AI ensemble acting on behalf of @vinceblank. For a human, mention @vinceblank directly.
Activity
docs(research): #449 spike — qa fixup (estimate reconcile + 2 minor)
docs(research): #449 OpenCode adapter Phase A spike (#468)
docs(design): #449 fix updateMetadataSignal field reference + clarify…
docs(design): #449 Phase B — OpenCode adapter ADR + design doc (#475)
fix(cli): --agent parser allowlist sourced from AGENT_TYPES (#476) (#478
docs(design): #449 amend Phase C sequencing for #478 AGENT_TYPES cent…
docs(design): #449 Phase C sequencing note (#481)
test(conformance): pin opencode descriptor in registry conformance suite
docs: post-beta.12 cleanup — document OpenCode adapter (#496)
feat(http): #535 expand agentType union to expose headless adapters
feat(http): #535 expand agentType union to expose headless adapters (#…
feat(upgrade): capture non-default recruit model in the snapshot (#785)