Symphony Claude Lane

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 dispatches Codex workers through its Elixir runtime. This agent skill adds Claude Code workers to the same workflow, running as interactive sessions inside detached tmux panes in isolated git worktrees, tracked through the same Linear 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 if you need to set one up)
• Claude Code and/or Codex installed
• Linear account with an API key (LINEAR_API_KEY in your environment)
• Playwright 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 and/or 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)

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)

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:

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

60-second quickstart

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:

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:

.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
• Source: 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.