Contrabass
🎸 A project-level orchestrator for AI coding agents — Go & Charm stack implementation of OpenAI's Symphony
Last verified:
What is Contrabass?
Contrabass is a project-level orchestrator for AI coding agents, designed for issue-driven agent runs with a terminal-first approach. It is a Go + Charm stack reimplementation of OpenAI's Symphony (openai/symphony), with the philosophy of
Contrabass pricing
Pricing model: Freemium
Contrabass is open source and free to use. Pre-built binaries for macOS and Linux (amd64/arm64) are available on the GitHub Releases page. Installation is available via Homebrew (macOS/Linux) with 'brew install junhoyeo/contrabass/contrabass', or by building from source. There are no paid tiers or subscription plans mentioned on the website. The tool requires tracker credentials for external services you use (LINEAR_API_KEY for Linear, GITHUB_TOKEN for GitHub), but these are your existing service credentials, not payments to Contrabass.
Contrabass pros
- Terminal-first orchestrator with Charm v2 TUI built on Bubble Tea, Bubbles, and Lip Gloss
- Optional embedded web dashboard (Ziikoo) with real-time SSE streaming
- Supports multiple issue trackers: Linear, GitHub Issues, and built-in Internal Board
- Multiple agent runner support: Codex, OpenCode, oh-my-opencode, OMX, OMC
- Git-worktree-based workspace provisioning with non-git fallback
- Multi-agent coordination with team task board and phased pipeline
- Dual worker modes: tmux-based multi-process (default) and goroutine-based in-process
- BlockedBy gating defers issues with unresolved dependencies
- Orphan claim recovery automatically reclaims claimed-but-not-running issues on restart
- Branch advance verification ensures agents made commits before marking success
- Agent stage classification with 5-stage monotonic progression (Exploration→Editing→Testing→Reviewing→Wrapping)
- Completion ETA with confidence bands (requires 3+ min elapsed, stage ≥ 3 for high confidence)
- Deterministic exponential backoff with FNV-hash jitter for reproducible retries
- Live config reload via fsnotify watching WORKFLOW.md
- JSON snapshot API + SSE for programmatic access to orchestrator state
- Full Simplified Chinese (zh-CN) localization in dashboard
- Stop agent button to terminate running agents directly from dashboard
- Board view with CRUD interface for internal board tracker
- Graceful shutdown drains running agents before process exit
- Homebrew installation available for macOS/Linux
Contrabass cons
- Requires Go 1.25+ which is a future version not yet widely adopted
- Requires Bun 1.3+ for dashboard/landing workspace installation
- tmux required for default tmux worker mode in team runs
- go install does not embed web dashboard (empty because JS build step not run)
- Some workflow file fields parsed but not fully consumed by runtime (workspace, hooks, some codex settings)
- Linear sync_comments is opt-in and defaults to false, requiring manual configuration
- Comment sync is best-effort and asynchronous, may fail temporarily
- OMC/OMX team runners require underlying toolchain prerequisites especially tmux-based team support
- Codex runner requires Codex 0.128+ for thread/tokenUsage shape support
- Internal Board is file-based local tracking, no cloud synchronization
Frequently asked questions about Contrabass
What is Contrabass?
Contrabass is a project-level orchestrator for AI coding agents. It is a Go + Charm stack reimplementation of OpenAI's Symphony (openai/symphony) with the philosophy of 'manage work, not agents.' It is a terminal-first orchestrator for issue-driven agent runs, with an optional local web dashboard for live visibility.
What issue trackers does Contrabass support?
Contrabass supports three issue tracker adapters: Linear (GraphQL-based issue fetch, claim, release, state update, and comment posting), GitHub Issues (REST-based issue fetch, assign/unassign, comment, and close-on-release behavior), and a built-in Internal Board which is file-based local issue tracking under .contrabass/board/ with no external service required.
Which AI agent runtimes are supported?
Contrabass supports five agent runners: Codex app-server (launches codex app-server with JSONL protocol), OpenCode (starts or reuses opencode serve process), oh-my-opencode (wraps the oh-my-opencode agent binary), OMX/oh-my-codex (launches omx team with workspace-scoped task file), and OMC/oh-my-claudecode (launches omc team with workspace-scoped task file).
How do I install Contrabass?
Contrabass can be installed three ways: (1) Homebrew on macOS/Linux with 'brew install junhoyeo/contrabass/contrabass', (2) Download pre-built binaries from GitHub Releases for macOS and Linux (amd64/arm64), or (3) Build from source by cloning the repo, running 'bun install', then 'make build' which builds the dashboard and embeds it into the Go binary.
What are the system requirements?
Contrabass requires Go 1.25+, Bun 1.3+ for the dashboard/landing workspace, Git (for workspace creation using git worktree), tmux (required for the default tmux worker mode in team runs, not needed for goroutine mode), and a supported agent runtime such as codex app-server, opencode serve, oh-my-opencode, omx, or omc.
What is the Ziikoo dashboard?
Ziikoo is the React web dashboard embedded in the Contrabass Go binary, featuring a neo-brutalism theme with shadcn + Tailwind v4. It has a three-pane IDE-style layout with left sidebar for queue navigation, main content with responsive data tables, and right detail sheet with issue metadata. Features include 5-step agent stage pills, completion ETA with confidence bands, live metrics, team/worker tables, agent logs, board view with CRUD, stop agent button, and zh-CN localization.
What are the two worker modes for teams?
Teams support two worker modes: (1) tmux mode (default) where each worker runs in a separate tmux pane with process isolation, cross-process IPC via JSONL events, and file-based heartbeats; and (2) goroutine mode where workers run as goroutines within the contrabass process, which is lighter weight with no tmux dependency but shares the process address space.
How does the WORKFLOW.md file work?
Contrabass reads a Markdown workflow file with YAML front matter followed by a prompt template body. The YAML front matter contains configuration like max_concurrency, poll_interval_ms, model, tracker settings, and agent settings. The prompt body uses Liquid template bindings like {{ issue.title }}, {{ issue.description }}, and {{ issue.url }}. The file is watched with fsnotify for live config reload, and on parse errors Contrabass keeps the last known good config.
What orchestrator features does Contrabass include?
Key orchestrator features include: BlockedBy gating (issues with unresolved blockers are deferred), orphan claim recovery (claimed-but-not-running issues reclaimed on restart), branch advance verification (verifies agents made commits before marking success), agent stage classification (monotonic 5-stage progression), completion ETA with confidence bands, liveness snapshots (per-agent heartbeat age, activity timestamps, diff stats), stall detection (flags runs lacking recent events), deterministic backoff (exponential growth with FNV-hash jitter), and graceful shutdown (drains running agents before exit).
How do I run Contrabass with the web dashboard?
To run Contrabass with the embedded web dashboard, use: 'LINEAR_API_KEY=your-linear-token ./contrabass --config testdata/workflow.demo.md --port 8080', then open http://localhost:8080 in your browser. The --port flag enables the dashboard (0 = disabled). For headless mode without TUI, use '--no-tui' flag instead.