Contrabass

A project-level orchestrator for AI coding agents Go + Charm stack reimplementation of OpenAI's Symphony (openai/symphony) — manage work, not agents

Contrabass is a terminal-first orchestrator for issue-driven agent runs, with an optional local web dashboard for live visibility.

Current scope

Today Contrabass ships with:

• A Cobra CLI with TUI, headless, and optional embedded web dashboard modes
• A WORKFLOW.md parser with YAML front matter, Liquid prompt rendering, and $ENV_VAR interpolation
• Issue tracker adapters for Linear, GitHub Issues, and a built-in Internal Board (local filesystem, no external service required)
• Agent runners for Codex app-server, OpenCode, oh-my-opencode, OMX (oh-my-codex), and OMC (oh-my-claudecode)
• Git-worktree-based workspace provisioning under workspaces/<issue-id> with non-git fallback for repositories without git
• Teams: multi-agent coordination with a local task board, phased pipeline (plan → exec → verify), live TUI team table, and dual worker modes (tmux-based multi-process or goroutine-based in-process)
• An orchestrator with claim/release, BlockedBy gating, orphan claim recovery, branch advance verification, stall detection, deterministic retry backoff, liveness snapshots with agent stage classification and ETA estimation
• A Charm v2 terminal UI built with Bubble Tea, Bubbles, and Lip Gloss
• Ziikoo — a React dashboard (neo-brutalism theme, shadcn + Tailwind v4) with a three-pane IDE-style layout, live SSE streaming, queue navigation, stage progression pills, completion ETAs, issue detail sheets with Linear metadata and workflow timelines, team/worker tables, agent logs, and zh-CN localization
• Go unit/integration tests, TUI snapshot tests, and dashboard component/hook tests
• A tmux-based multi-process worker mode (default) alongside the in-process goroutine mode, with JSONL event logging, file-based heartbeats, dispatch queue, governance policies, and crash recovery

Requirements

• Go 1.25+
• Bun 1.3+ for the dashboard/landing workspace
• Git (workspace creation uses git worktree)
• tmux (required for the default tmux worker mode in team runs; not needed for goroutine mode)
• A supported agent runtime:
  • codex app-server
  • opencode serve
  • oh-my-opencode
  • omx (oh-my-codex team runtime)
  • omc (oh-my-claudecode team runtime)
• Tracker credentials for the backend you use:
  • Linear: LINEAR_API_KEY
  • GitHub: GITHUB_TOKEN

From a fresh clone, run bun install once before using the JS/landing build and test commands.

Installation

Homebrew (macOS/Linux)

brew install junhoyeo/contrabass/contrabass

Download from GitHub Releases

Pre-built binaries for macOS and Linux (amd64/arm64) are available on the Releases page.

Build from source

git clone https://github.com/junhoyeo/contrabass.git
cd contrabass
bun install
make build

make build first builds packages/dashboard/dist/ and then embeds it into the Go binary.

Note: go install github.com/junhoyeo/contrabass/cmd/contrabass@latest works for the CLI and TUI, but the embedded web dashboard (--port) will be empty because go install does not run the JS build step.

Quick start

Run with the demo workflow

LINEAR_API_KEY=your-linear-token \
./contrabass --config testdata/workflow.demo.md

Run with the embedded web dashboard

LINEAR_API_KEY=your-linear-token \
./contrabass --config testdata/workflow.demo.md --port 8080

Then open http://localhost:8080.

Run headless

LINEAR_API_KEY=your-linear-token \
./contrabass --config testdata/workflow.demo.md --no-tui

CLI flags

--config string      path to WORKFLOW.md file (required)
--dry-run            exit after first poll cycle
--log-file string    log output path (default "contrabass.log")
--log-level string   log level (debug/info/warn/error) (default "info")
--no-tui             headless mode — skip TUI, log events to stdout
--port int           web dashboard port (0 = disabled)

Team subcommand flags

contrabass team run --config workflow.md [flags]

--worker-mode string   override worker mode (goroutine|tmux, default from config)

How Contrabass works

1. Poll the configured tracker for candidate issues.
2. Skip issues with unresolved BlockedBy dependencies (BlockedBy gating).
3. Claim an eligible issue, recording the workspace HEAD SHA at claim time.
4. Create or reuse a git worktree in workspaces/<issue-id> (falls back to plain directory when git is unavailable).
5. Render the prompt body from WORKFLOW.md using issue data.
6. Launch the configured agent runner.
7. Stream agent events, classify agent stage (Exploration → Editing → Testing → Reviewing → Wrapping), track token consumption, and estimate completion ETAs.
8. On completion, verify the workspace branch advanced beyond the claim HEAD before marking success.
9. On failure, retry with deterministic exponential backoff + FNV-hash jitter.
10. Recover orphaned claims on restart — issues marked Claimed but not actively running are reset to Unclaimed.
11. Mirror state into the TUI, the Ziikoo dashboard (via SSE), and the JSON snapshot API.

Orchestrator features

Runtime notes

• WORKFLOW.md is watched with fsnotify; on parse errors, Contrabass keeps the last known good config.
• The Codex runner speaks newline-delimited JSON (JSONL) to codex app-server rather than Content-Length framed messages. See docs/codex-protocol.md.
• The Codex runner handles -32001 server overload errors with exponential backoff retry (up to 5 attempts) and detects stalled streams via configurable read timeouts.
• The workflow parser already accepts more Symphony-shaped fields than the runtime fully consumes today. For example, workspace, hooks, and some codex settings are parsed, but the current runtime mainly uses tracker selection, timeouts, retry settings, binary paths, and prompt/template fields.

Team worker modes

Teams support two worker modes, configured via team.worker_mode in the workflow file or the --worker-mode CLI flag:

tmux mode (default) provides:

• Process isolation — each agent CLI runs in its own tmux pane
• JSONL event log for cross-process event streaming
• File-based heartbeat monitoring with stale detection
• Dispatch queue with ack tracking and timeout redelivery
• Governance policies with role routing heuristics
• Crash recovery with state diagnosis and automatic cleanup
• Advisory file locking via flock(2) for safe concurrent access

goroutine mode runs all workers in-process using Go's errgroup and sync.Mutex. It requires no external dependencies but shares the process address space.

Team state is persisted as JSON files under .contrabass/state/team/{teamName}/.

Workflow file format

Contrabass reads a Markdown workflow file with YAML front matter followed by the prompt template body.

---
max_concurrency: 3
poll_interval_ms: 2000
max_retry_backoff_ms: 240000
model: openai/gpt-5-codex
project_url: https://linear.app/acme/project/example
agent_timeout_ms: 900000
stall_timeout_ms: 60000
tracker:
  type: linear
linear:
  issue_details:
    enabled: true
  sync_comments:
    enabled: false
    mode: reply_thread
agent:
  type: codex
codex:
  binary_path: codex app-server
---
# Workflow Prompt

Issue title: {{ issue.title }}
Issue description: {{ issue.description }}
Issue URL: {{ issue.url }}

Produce code and tests that satisfy the issue requirements.

Linear detail and timeline sync settings

When tracker.type: linear is used, the dashboard can load richer issue metadata through the Contrabass backend without exposing Linear credentials to browser code.

linear:
  issue_details:
    enabled: true
  sync_comments:
    enabled: false
    mode: reply_thread # reply_thread by default; top_level is the fallback-safe mode

• linear.issue_details.enabled controls backend issue detail reads used by the issue detail sheet. Candidate polling remains lean.
• linear.sync_comments.enabled is opt-in and defaults to `fals