README.md

Contrabass

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

Contrabass Demo (TUI in Action)

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

contrabass