# Symphony Claude Lane

> Long-horizon multi-agent orchestration for Claude Code workers. Mix and match with Codex workers via Symphony, tracked through Linear. An optional goal layer pursues durable goals across many waves.

- **Type:** MCP server
- **Install:** `agentstack add mcp-jvogan-symphony-claude-lane`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jvogan](https://agentstack.voostack.com/s/jvogan)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jvogan](https://github.com/jvogan)
- **Source:** https://github.com/jvogan/symphony-claude-lane
- **Website:** https://github.com/jvogan/symphony-claude-lane

## Install

```sh
agentstack add mcp-jvogan-symphony-claude-lane
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Symphony + Claude Lane

[](LICENSE)
[](https://github.com/jvogan/symphony-claude-lane/actions/workflows/test.yml)
[](#install)

**Long-horizon multi-agent orchestration for Claude Code workers, run subscription-billed in attachable tmux sessions and tracked through Linear. Mix and match with Codex workers via Symphony.**

[Symphony](https://github.com/openai/symphony) dispatches [Codex](https://openai.com/index/codex/) workers through its Elixir runtime. This [agent skill](https://agentskills.io/specification) adds [Claude Code](https://docs.anthropic.com/en/docs/claude-code) workers to the same workflow, running as **interactive sessions inside detached tmux panes** in isolated git worktrees, tracked through the same [Linear](https://linear.app) backlog, with smart routing that sends each task to the agent best suited for it.

You install the skill, point it at a repo, and your orchestrator agent learns how to route tasks between models, launch Claude workers securely, verify frontend output with Playwright, and close out work through Linear.

```
                     Orchestrator
                    /            \
            Symphony              claude (tmux)
            (Elixir)              (interactive session)
               |                      |
          Codex workers          Claude workers
          (sandbox, fast,        (browser, reasoning,
           parallel)              tools, review)
               |                      |
               \________Linear________/
                (shared issues & state)
```

> **Current release candidate: v3.0.0-rc3.** The default backend runs Claude workers as interactive sessions in tmux panes instead of `claude -p` subprocesses. This bills against the operator's Claude subscription, matches the normal interactive session model, and gives operators attachable long-running workers. Teams that prefer API-priced / headless `claude -p` can adapt the launcher intentionally; see [`docs/backend-options.md`](docs/backend-options.md).

## Why this exists

Long-horizon AI work needs more than "send one prompt and hope." Complex product, infrastructure, and research tasks need a harness: durable issue state, isolated worktrees, observable workers, model-specific routing, validation evidence, closeout checks, and cleanup rules. This skill turns Linear into the shared control plane for that harness, with Claude Code handling work that benefits from visual judgment, deep reasoning, browser verification, or external tools, and Codex/Symphony handling bounded parallel implementation when that is the better fit.

## Why run both?

Different AI agents have different strengths. Running both against the same Linear backlog, each claiming tasks that match what it's best at, produces better output than either alone.

| Claude Code | Codex |
|---|---|
| Browser verification, visual judgment | Bounded, sandbox-compatible implementation |
| Deep reasoning (architecture, debugging) | Config, schema, type, migration changes |
| External tools (APIs, databases, MCP) | Test infrastructure (unit tests, fixtures) |
| Security review, code review | Mechanical refactors |
| Documentation, product copy | Parallelizable batch of similar tasks |
| E2E tests (sandbox-incompatible) | Fast execution where speed > judgment |

The skill also supports **Claude-only** setups for teams that don't use Codex. With the default tmux backend, no API plumbing is required, since both Codex and Claude Code are subscription tools with built-in agent capabilities.

## Backend choice

The bundled reference launcher defaults to **tmux-backed interactive Claude Code** because it is attachable, observable, and subscription-billed. It is the recommended path for long-running workers.

If your team prefers API-priced or fully headless execution, keep the same routing profile, Linear state machine, prompt-injection boundary, outcome block, and cleanup rules, then adapt the launcher back to a deliberate `claude -p` subprocess backend. The skill includes migration notes for both directions in [`docs/backend-options.md`](docs/backend-options.md); the important part is choosing one backend explicitly and keeping its billing, observability, and completion semantics documented.

## Prerequisites

**Full mode (Symphony + Linear).** Make sure you have:

- An **existing Symphony + Linear workflow** (see [symphony-linear-starter](https://github.com/jvogan/symphony-linear-starter) if you need to set one up)
- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** and/or **[Codex](https://openai.com/index/codex/)** installed
- **[Linear](https://linear.app)** account with an API key (`LINEAR_API_KEY` in your environment)
- **[Playwright](https://playwright.dev/)** or equivalent browser automation for visual verification (recommended)
- A target git repo with orchestration configured
- On the dispatcher host: **`tmux`**, `jq`, `git`, `curl`, `python3` (run `bin/claude-doctor` after install to verify)

**GitHub-only mode (minimum).** For the worker→release-manager flow with no tracker:

- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** and/or **[Codex](https://openai.com/index/codex/)** installed
- the **`gh` CLI** authenticated (`gh auth status`)
- a GitHub repo where you can create labels (for the `release:*` handoff state machine)
- `gh`, `jq`, `git` for the release manager itself; **`tmux` + `claude` only if you use the bundled worker launcher** (driving workers yourself doesn't need them)

No Linear or Symphony required for GitHub-only mode. See [`docs/github-only-quickstart.md`](docs/github-only-quickstart.md). Use `bin/release-manager-doctor` (not `bin/claude-doctor`) as the GitHub-only preflight.

## Install

### Skills CLI (recommended)

```bash
npx skills add jvogan/symphony-claude-lane
```

This clones the skill into your local skills directory (e.g. `~/.codex/skills/`) so your agent can discover it.

### Codex (manual)

```bash
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R skills/symphony-claude-lane "${CODEX_HOME:-$HOME/.codex}/skills/"
```

Restart Codex after installing so the skill is discoverable.

### Claude Code (manual)

Copy the skill folder into your project, then add it as a context reference in your `CLAUDE.md`:

```markdown

See @skills/symphony-claude-lane/SKILL.md for multi-model routing.
```

## 60-second quickstart

```bash
git clone https://github.com/jvogan/symphony-claude-lane.git
cd symphony-claude-lane
export LINEAR_API_KEY=""
source ./env.sh
bin/claude-doctor
```

Then install the skill into your agent, add the `lane:claude` label in Linear, and ask the agent to configure your target repo:

```text
Use $symphony-claude-lane to set up long-horizon multi-agent routing for this
Symphony + Linear repo. Use tmux-backed Claude workers by default, preserve
Codex/Symphony for bounded parallel work, and document closeout and cleanup.
```

For the expanded setup path, see [`docs/quickstart.md`](docs/quickstart.md).

## How it works

**Setup** (the skill helps your orchestrator do this):

1. Inspect a repo that already uses Symphony + Linear.
2. Confirm the base workflow has guardrails (bootstrap assertions, stop-loss) before adding Claude workers.
3. Analyze the repo's work patterns and ask about routing preferences.
4. Create a routing profile (`.orchestration/claude-lane.yaml`) with model selection criteria, label overrides, privacy rules, and cleanup policy.
5. Set up the Claude worker launcher: the secure process for dispatching interactive `claude` sessions in tmux panes against Linear issues in isolated git worktrees.
6. Add the release-manager contract if workers will say "deploy": workers mark PRs `release:ready`, and one release manager owns queue/merge/deploy/Done closeout.
7. Document the routing contract so both human operators and agents know how tasks get dispatched and released.

**Dispatch** (how it runs after setup):

1. The orchestrator plans issues in Linear with routing labels or task analysis.
2. Symphony picks up Codex-routed issues and dispatches Codex workers through its Elixir runtime.
3. The Claude launcher picks up Claude-routed issues and dispatches interactive Claude sessions in tmux panes in isolated worktrees.
4. Both types of workers post structured outcomes back to Linear when done and, when ready to release, put the GitHub PR in `release:ready`.
5. A single release manager consumes `release:ready` PRs, queues or merges them, optionally waits for deploy evidence, and posts evidence-based closeout to Linear.
6. The orchestrator reviews all output in one place and promotes learnings.

**Routing strategies:**

- **task-characteristic** (default): The orchestrator analyzes each issue and picks the best model based on what the task requires. Labels serve as overrides.
- **label-only**: Routing is determined entirely by Linear labels. Simpler but less adaptive.

The skill includes a [reference launcher script](skills/symphony-claude-lane/assets/claude-worker.reference.sh) and [worker launch docs](skills/symphony-claude-lane/references/worker-launch.md) with a full security checklist you can adapt to your environment.

## Long-horizon goals (the goal layer)

The release lane executes and merges a backlog. The optional **goal layer** decides what the next wave of work should be. You give it a durable goal: a north star, acceptance criteria, and a budget. It then drives the lane through many waves until the goal is met or a guard stops it, so a goal can be pursued for hours without a human curating each wave.

- **`/goal ""`** frames the goal and wires the loop.
- **`bin/goal-manager`** holds durable goal state in a Linear project and owns every termination guard: dedup, task and pass budgets, a no-new-work halt, and a single-writer lock. It mints work tickets and planner passes, never launching agents or merging. Dry-run by default; `--apply` to mutate.
- Planning runs as an ephemeral agent: a `goal:planner` ticket that re-derives the next wave from durable state each pass, then exits. This mirrors the merge lane's stateless, idempotent design one level up, so there is no long-running planning process to keep alive.
- A heartbeat (`goal-manager tick --loop`) merges what's ready through the release lane and mints the next planner when the backlog runs low, stopping itself when acceptance is met (`done`) or a guard trips (`halted`).

Dispatch (who launches the agents) stays external: Symphony, the launcher, or you. Merging stays in the single CI-gated release lane. See [`docs/goal-layer.md`](docs/goal-layer.md).

## Example prompts

```
Use $symphony-claude-lane to set up smart multi-model routing for this repo.
Analyze what types of work appear in the backlog and recommend which agent
handles what.
```
```
Use $symphony-claude-lane to add task-characteristic routing to this
Symphony + Linear repo with label overrides for UI and infra work.
```
```
Use $symphony-claude-lane to configure this repo for Claude-only workers
without Codex.
```
```
Use $symphony-claude-lane to update the routing profile so Claude also handles
security reviews and complex debugging.
```
```
Use $symphony-claude-lane to review the current routing and recommend changes
based on how the last wave performed.
```

## What the skill produces

The skill creates or updates a repo-local routing file:

```text
.orchestration/claude-lane.yaml
```

That file records the adopter's decisions about:

- routing strategy: task-characteristic analysis or label-only
- backend selection: tmux by default, `claude -p` by deliberate adaptation, or a hybrid split
- model selection criteria: what task characteristics prefer Claude vs Codex
- label overrides: which labels always route to a specific model
- whether this is a mixed-model or Claude-only setup
- whether visual verification is mandatory for frontend work
- preferred Claude models
- which base-workflow guardrails all workers inherit
- closeout and retry behavior
- release-manager ownership of merge-to-main and deploy closeout when workers are allowed to prepare deployable PRs
- cleanup and retention policy for worktrees, snapshots, and repo-specific storage hotspots
- privacy rules for issue bodies, comments, screenshots, traces, and other artifacts

Those decisions belong in the adopter repo, not in this shared skill.

## What's inside

| Path | Purpose |
|---|---|
| `skills/symphony-claude-lane/SKILL.md` | Main routing and dispatch skill |
| `skills/.../references/` | Setup, routing, dispatch, worker launch, visual verification, closeout, troubleshooting, examples |
| `skills/.../assets/claude-lane-profile.example.yaml` | Example repo-local routing profile |
| `skills/.../assets/claude-lane-guidance.snippet.md` | Starter snippet for adopter repo orchestration docs |
| `skills/.../assets/claude-worker.reference.sh` | Reference tmux-backed launcher (adapt to your environment) |
| `skills/.../assets/review-audit.reference.py` | Reference parser for current and legacy outcome comments |
| `skills/.../assets/worker-prompt.template.md` | Worker prompt template with trust boundary, capabilities, and closeout protocol |
| `skills/.../assets/linear-outcome-block.example.md` | Example machine-readable closeout comments |
| `skills/.../assets/goal-planner-prompt.template.md` | Goal-layer planner prompt; outputs the next wave of work tickets |
| `skills/.../agents/openai.yaml` | Skill metadata |
| `bin/claude-doctor` | Preflight battery: verify env, deps, Linear connectivity, lane state |
| `bin/claude-version` | Print install root, branch/commit, default model env, and `claude` CLI version |
| `bin/claude-tmux-finalize` | Worker-invoked helper that writes the completion sentinel JSON |
| `bin/release-manager` | Single-owner release lane for `release:ready` PRs: serialize merge-to-main, closed-loop rebase recovery (`--on-conflict redispatch`), decoupled deploy-evidence (`--reconcile-deploys`), and per-PR JSONL metrics; dry-run by default, explicit `--apply` to mutate |
| `bin/release-manager-doctor` | Preflight battery for GitHub CLI auth, Merge Queue config, Linear reachability, repo remotes, release-manager env, and stale locks |
| `bin/release-status` | Read-only snapshot of `release:ready`/`queued`/`merged`/`failed` PR counts and time-to-main (p50/p90) from the metrics log; never mutates |
| `bin/routing-feedback` | Read-only analyzer of worker outcomes (model, pass-rate, latency) that proposes routing-profile edits for human review; never writes |
| `bin/goal-manager` | Goal-layer engine: durable goal state in a Linear project plus all termination guards (dedup, task/pass budgets, no-new-work halt, single-writer lock); mints work tickets and planner passes; dry-run by default, `--apply` to mutate |
| `commands/goal.md` | `/goal`: bootstrap a long-horizon goal and wire the heartbeat loop above the release lane |
| `env.sh` | Source to set lane defaults (paths, model, routing label, MCP config, env allowlist) |
| `mcp/worker-mcp.json` | Default MCP config (Linear only) |
| `mcp/worker-mcp-runpod.json` | Opt-in MCP config (Linear + RunPod) |
| `settings/claude-settings.tmux.json` | Per-worktree `.claude/settings.json` with `bypassPermissions` |
| `tests/` | Nine fully-isolated regression tests (sentinel-malformed, MCP opt-in, env isolation, release-manager, release-status, routing-feedback, release-manager-doctor, launcher-recovery, goal-manager) |
| `docs/architecture.md` | Sentinel JSON contract, dispatch lock semantics, autoset-marker pattern |
| `docs/backend-options.md` | How to choose tmux, `claude -p`, or a hybrid backend intentionally |
| `docs/lessons.md` | Bug-by-bug postmortems from the tmux backend build |
| `docs/linear-setup.md` | How to set up `lane:claude` + `model:*` labels in a Linear workspace |
| `docs/migration-v2-to-v3.md` | What changes if you adopted v2.0.1 |
| `docs/github-only-quickstart.md` | Run the worker→release-manager flow with only Claude Code/Codex + GitHub (no Linear/Symphony) |
| `docs/r

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [jvogan](https://github.com/jvogan)
- **Source:** [jvogan/symphony-claude-lane](https://github.com/jvogan/symphony-claude-lane)
- **License:** MIT
- **Homepage:** https://github.com/jvogan/symphony-claude-lane

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-jvogan-symphony-claude-lane
- Seller: https://agentstack.voostack.com/s/jvogan
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.