claude-teams-on-sesh

Sesh-native spawn path for Claude Code's experimental Agent Teams.

What this is

claude-teams-spawn is a small CLI that adds members to a Claude Code agent team and launches them as real, NATS-wired teammates bound to their own sesh sessions. The result: a teammate that is both a first-class participant in Claude Code's agent-teams IPC (inbox messaging, SendMessage, shutdown_request protocol) and a first-class peer on the sesh hub (its own NATS subject, addressable from any client connected to the hub).

Why this lives outside sesh

Sesh provides the agent-neutral primitive — sesh up --session=<label> --exec='<cmd>' brings up a session and binds a child process to it with the full canonical env. Anything more specific would couple sesh to a particular harness's protocol details.

Claude Code's agent-teams protocol (team config schema, inbox file format, the --agent-id / --team-name claude CLI flag set) is owned by Anthropic and changes on Anthropic's release cadence. Tracking that drift belongs in a thin adapter project, not in sesh's core. This repo IS that adapter.

How it relates to other projects

                   ┌─────────────────────────────────┐
                   │  Claude Code agent-teams        │
                   │  (Anthropic-owned protocol)     │
                   │  - team config + inbox files    │
                   │  - --agent-id, --team-name CLI  │
                   └────────────┬────────────────────┘
                                │ writes/spawns
                                ▼
┌────────────────────────────────────────────────────┐
│  claude-teams-on-sesh (this repo)                  │
│  - writes team config + inbox                      │
│  - spawns claude with the right CLI flags          │
│  - tracks Anthropic-side schema/flag drift         │
└─────────────────┬──────────────────────────────────┘
                  │ invokes
                  ▼
┌────────────────────────────────────────────────────┐
│  sesh (github.com/danmestas/sesh)                  │
│  - sesh up --session=<label> --exec='...'          │
│  - canonical env: SESH_*, NATS_URL, SESH_ROLE...   │
│  - hub + per-session NATS bundles + fossil         │
└────────────────────────────────────────────────────┘

Sesh is the agent-neutral substrate. This repo adapts it for one specific harness.

Status

Phase 2 + Phase 4 complete (2026-05-23). End-to-end one-shot spawn works against a live Claude Code agent team. Sesh-spawned teammate registers as NATS Micro service per Synadia Agent Protocol v0.3, is reachable on agents.prompt.cc.<owner>.<name> with sub-4ms RTT, and is indistinguishable from harness-spawned teammates at the protocol layer.

Implementation plan at docs/SPEC.md. Spy-test reference data at docs/spy-test-2026-05-22.md. Binary built locally via go build ./cmd/claude-teams-spawn. Not yet released.

Remaining phases: Phase 3 (readiness handshake hardening), Phase 5 (operator skill), Phase 6 (CI drift detection).

Phase 0 prerequisites:

• [x] Resolved 2026-05-22. The upstream claude-nats-channel MCP at github.com/danmestas/sesh-channels/claude-nats-channel/server.ts:234 already honors SESH_SESSION env-var override. When sesh up --exec sets the env, the spawned claude's MCP auto-subscribes to agents.prompt.cc.<owner>.<name>. No upstream issue needed.
• [ ] Re-run the spy-test against the current Claude Code version to confirm the captured CLI flag set is still accurate.

Usage (planned)

claude-teams-spawn <team-name> <member-name> \
    [--prompt=STRING | --prompt-file=PATH] \
    [--agent-type=TYPE] \
    [--agent-color=COLOR] \
    [--model=MODEL] \
    [--cwd=PATH] \
    [--scope=workflow|project|session] \
    [--scope-id=ID] \
    [--backend=tmux|cmux|background] \
    [--dry-run]

Backend auto-detect: CMUX_SOCKET_PATH set → cmux; TMUX set → tmux; neither → background. Override with --backend.

Prerequisites

• sesh ≥ (version with --exec shipped — verify via sesh up --help | grep exec)
• Claude Code (any 2.1.x — older versions untested)
• tmux OR cmux OR neither (for --backend=background)
• claude-nats-channel MCP (from github.com/danmestas/sesh-channels) — env-override already shipped; no version pin needed

Design references

• docs/SPEC.md — full implementation plan, locked decisions, phased work breakdown
• docs/spy-test-2026-05-22.md — reverse-engineered Claude Code agent-teams spawn shape
• Sesh's docs/coordination-patterns.md — the --exec primitive contract this repo builds on

License

Apache 2.0 (matches the rest of the dmestas/sesh-adjacent ecosystem).