### Install Contrabass

Source: https://context7.com/junhoyeo/contrabass/llms.txt

Install Contrabass using Homebrew or build from source. Building from source requires Go 1.25+ and Bun 1.3+.

```bash
# Homebrew (macOS/Linux)
brew install junhoyeo/contrabass/contrabass

# Build from source (requires Go 1.25+ and Bun 1.3+)
git clone https://github.com/junhoyeo/contrabass.git
cd contrabass
bun install
make build          # builds dashboard JS, then embeds into Go binary

# Run directly from source
go run ./cmd/contrabass --config testdata/workflow.demo.md --port 8080
```

--------------------------------

### Contrabass Workflow File Example

Source: https://github.com/junhoyeo/contrabass/blob/main/README.md

Example of a Contrabass workflow file, combining YAML front matter for configuration with a Markdown prompt template. Supports environment variable interpolation for sensitive values.

```markdown
---
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
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.

```

--------------------------------

### Set Up Development Environment

Source: https://github.com/junhoyeo/contrabass/blob/main/CONTRIBUTING.md

Clone the repository, install JavaScript dependencies with Bun, and fetch Go module dependencies.

```bash
git clone https://github.com/<your-fork>/contrabass.git
cd contrabass

bun install

go mod download
```

--------------------------------

### Development Server Commands for Contrabass Project

Source: https://context7.com/junhoyeo/contrabass/llms.txt

Start local development servers for the dashboard and landing page using Vite and Astro respectively.

```bash
make dev-dashboard    # Vite dev server for packages/dashboard
```

```bash
make dev-landing      # Astro dev server for packages/landing
```

--------------------------------

### Install Contrabass via Homebrew

Source: https://github.com/junhoyeo/contrabass/blob/main/README.md

Use this command to install Contrabass on macOS or Linux systems with Homebrew.

```bash
brew install junhoyeo/contrabass/contrabass
```

--------------------------------

### Develop Landing Site with Hot-Reload

Source: https://github.com/junhoyeo/contrabass/blob/main/CONTRIBUTING.md

Start the Astro development server for the landing site with hot-reloading enabled.

```bash
make dev-landing
```

--------------------------------

### Build Contrabass from Source

Source: https://github.com/junhoyeo/contrabass/blob/main/README.md

Follow these steps to clone the repository, install dependencies, and build Contrabass from its source code. This process includes building the dashboard assets.

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

--------------------------------

### Example Commit Messages

Source: https://github.com/junhoyeo/contrabass/blob/main/CONTRIBUTING.md

Examples of valid commit messages following the specified format.

```git
feat(config): add WORKFLOW.md parser with YAML front matter support
```

```git
fix(agent): handle JSON-RPC error code -32001 for server overload
```

```git
docs(project): add CONTRIBUTING.md with contributor guidelines
```

```git
test(orchestrator): port state machine transition tests
```

--------------------------------

### Develop Dashboard with Hot-Reload

Source: https://github.com/junhoyeo/contrabass/blob/main/CONTRIBUTING.md

Start the Vite development server for the React dashboard with hot-reloading enabled.

```bash
make dev-dashboard
```

--------------------------------

### Team Coordination Configuration Example

Source: https://github.com/junhoyeo/contrabass/blob/main/README.md

Configuration for team coordination in Contrabass, including maximum workers, claim lease duration, state directory, execution mode, and worker mode.

```yaml
team:
  max_workers: 5
  max_fix_loops: 3
  claim_lease_seconds: 300
  state_dir: .contrabass/state/team
  execution_mode: team    # team | single | auto
  worker_mode: tmux       # tmux (default) | goroutine

```

--------------------------------

### Start Turn with Rendered Prompt

Source: https://context7.com/junhoyeo/contrabass/llms.txt

Initiates a new turn within a session thread, providing the rendered prompt and context.

```json
{"method":"turn/start","id":3,"params":{"threadId":"thread-abc123","input":[{"type":"text","text":"Issue title: Fix login bug\n..."}],"cwd":"/repo/workspaces/ABC-42","title":"ABC-42: Fix login bug","approvalPolicy":"never","sandboxPolicy":{"type":"workspaceWrite","networkAccess":false}}}
```

--------------------------------

### Run Contrabass with Embedded Web Dashboard

Source: https://github.com/junhoyeo/contrabass/blob/main/README.md

Launch Contrabass with the embedded web dashboard enabled. Access the dashboard by navigating to http://localhost:8080 in your browser after starting.

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

--------------------------------

### Symphony Thread Start Request

Source: https://github.com/junhoyeo/contrabass/blob/main/docs/codex-protocol.md

Request sent by Symphony to start a new thread, specifying sandbox and dynamic tool configurations. The 'approvalPolicy' and 'sandbox' fields accept specific string or object variants.

```json
{
  "method": "thread/start",
  "id": 2,
  "params": {
    "approvalPolicy": "never | on-request | ...",
    "sandbox": "read-only | workspace-write | danger-full-access | object variant",
    "cwd": "/abs/workspace/path",
    "dynamicTools": [
      {
        "name": "linear_graphql",
        "description": "...",
        "inputSchema": { "type": "object", "required": ["query"] }
      }
    ]
  }
}
```

--------------------------------

### Create Feature Branch

Source: https://github.com/junhoyeo/contrabass/blob/main/CONTRIBUTING.md

Create a new branch for your feature starting from the main branch.

```bash
git checkout -b feat/my-feature
```

--------------------------------

### Start Session Thread Request

Source: https://context7.com/junhoyeo/contrabass/llms.txt

Requests the creation of a new session thread on the server, specifying sandbox and working directory.

```json
{"method":"thread/start","id":2,"params":{"approvalPolicy":"never","sandbox":"workspace-write","cwd":"/repo/workspaces/ABC-42"}}
```

--------------------------------

### OMx Agent Configuration Example

Source: https://github.com/junhoyeo/contrabass/blob/main/README.md

Configuration for the OMx agent type within a Contrabass workflow. Specifies the binary path, team specification, polling interval, and startup timeout.

```yaml
agent:
  type: omx
omx:
  binary_path: omx
  team_spec: 2:executor
  poll_interval_ms: 1500
  startup_timeout_ms: 22000
  ralph: true

```

--------------------------------

### Create and Run Orchestrator with Components

Source: https://context7.com/junhoyeo/contrabass/llms.txt

NewOrchestrator wires together tracker, workspace manager, agent runner, and config provider. Run polls for issues, claims them, creates workspaces, renders prompts, starts agents, and handles retries. Consume events from the Events() channel and handle graceful shutdown signals.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"
    "os/signal"
    "syscall"

    "github.com/junhoyeo/contrabass/internal/config"
    "github.com/junhoyeo/contrabass/internal/orchestrator"
    "github.com/junhoyeo/contrabass/internal/tracker"
    "github.com/junhoyeo/contrabass/internal/workspace"
    "github.com/junhoyeo/contrabass/internal/agent"
)

func main() {
    cfg, _ := config.ParseWorkflow("workflow.md")
    watcher, _ := config.NewWatcher("workflow.md")
    defer watcher.Stop()

    // Build tracker
    linearTracker, _ := tracker.NewLinearClient(tracker.LinearConfig{
        APIKey:      os.Getenv("LINEAR_API_KEY"),
        ProjectSlug: "my-project",
        AssigneeID:  cfg.TrackerAssigneeID(),
    })

    // Build workspace manager (git worktrees under cwd/workspaces/<issue-id>)
    repoPath, _ := os.Getwd()
    workspaceMgr := workspace.NewManager(repoPath)

    // Build agent runner
    codexRunner := agent.NewCodexRunner(cfg)

    // Build orchestrator
    orch := orchestrator.NewOrchestrator(linearTracker, workspaceMgr, codexRunner, watcher, nil)

    // Consume events in the background
    go func() {
        for event := range orch.Events() {
            switch event.Type {
            case orchestrator.EventAgentStarted:
                data := event.Data.(orchestrator.AgentStarted)
                fmt.Printf("Agent started: issue=%s pid=%d session=%s\n",
                    data.IssueIdentifier, data.PID, data.SessionID)
            case orchestrator.EventAgentFinished:
                data := event.Data.(orchestrator.AgentFinished)
                fmt.Printf("Agent finished: issue=%s tokensIn=%d tokensOut=%d err=%q\n",
                    event.IssueID, data.TokensIn, data.TokensOut, data.Error)
            case orchestrator.EventBackoffEnqueued:
                data := event.Data.(orchestrator.BackoffEnqueued)
                fmt.Printf("Retry scheduled: issue=%s retryAt=%s\n",
                    event.IssueID, data.RetryAt)
            case orchestrator.EventStatusUpdate:
                data := event.Data.(orchestrator.StatusUpdate)
                fmt.Printf("Status: running=%d/%d backlog=%d\n",
                    data.Stats.Running, data.Stats.MaxAgents, data.BackoffQueue)
            }
        }
    }()

    // Handle SIGINT/SIGTERM gracefully
    ctx, cancel := context.WithCancel(context.Background())
    sigCh := make(chan os.Signal, 1)
    signal.Notify(sigCh, os.Interrupt, syscall.SIGTERM)
    go func() {
        <-sigCh
        cancel()
    }()

    if err := orch.Run(ctx); err != nil {
        log.Fatal(err)
    }
}
```

--------------------------------

### Commit Message Format Example

Source: https://github.com/junhoyeo/contrabass/blob/main/AGENTS.md

Illustrates the conventional commit format used for messages. Adhering to this format ensures consistency and clarity in the commit history.

```git
feat(config): add WORKFLOW.md parser with YAML front matter support
test(orchestrator): port state machine transition tests from Elixir
fix(agent): handle JSON-RPC error code -32001 for server overload
refactor(tui): split model into header and table sub-components
docs(project): add AGENTS.md with commit convention
chore(project): initialize go.mod with Charm v2 dependencies
perf(tracker): cache workspace state to reduce file I/O
```

--------------------------------

### OMc Agent Configuration Example

Source: https://github.com/junhoyeo/contrabass/blob/main/README.md

Configuration for the OMc agent type within a Contrabass workflow. Specifies the binary path, team specification, polling interval, and startup timeout.

```yaml
agent:
  type: omc
omc:
  binary_path: omc
  team_spec: 2:claude
  poll_interval_ms: 1200
  startup_timeout_ms: 21000

```

--------------------------------

### Initialize a new contrabass board

Source: https://context7.com/junhoyeo/contrabass/llms.txt

Use `contrabass board init` to set up a new local filesystem-backed issue board. Specify a prefix for issue identifiers.

```bash
# Initialize a new board in .contrabass/board with prefix "CB"
contrabass board init --prefix CB
```

--------------------------------

### contrabass board init

Source: https://context7.com/junhoyeo/contrabass/llms.txt

Initializes a new local filesystem-backed issue board.

```APIDOC
## contrabass board init

### Description
Initializes a new local filesystem-backed issue board in the `.contrabass/board/` directory.

### Usage
`contrabass board init --prefix <prefix>`

### Parameters
#### Flags
- `--prefix` (string) - Required - The prefix to use for new issue IDs (e.g., `CB`).
```

--------------------------------

### Get Orchestrator Snapshot

Source: https://github.com/junhoyeo/contrabass/blob/main/README.md

Retrieves a full snapshot of the current orchestrator state.

```APIDOC
## GET /api/v1/state

### Description
Retrieves a full snapshot of the orchestrator state.

### Method
GET

### Endpoint
/api/v1/state

### Response
#### Success Response (200)
- **state** (object) - The complete state of the orchestrator.
```

--------------------------------

### Run Quick Tests

Source: https://github.com/junhoyeo/contrabass/blob/main/CONTRIBUTING.md

Execute a quick test suite that includes Go tests, dashboard tests, and landing page checks.

```bash
make test-quick
```

--------------------------------

### Linting Commands for Contrabass Project

Source: https://context7.com/junhoyeo/contrabass/llms.txt

Run Go vet for linting and a comprehensive CI pass that includes linting, quick testing, and building.

```bash
make lint             # go vet ./...
```

```bash
make ci               # full CI pass: lint + test-quick + binary + dashboard + landing
```

--------------------------------

### Configure OpenCode Agent

Source: https://context7.com/junhoyeo/contrabass/llms.txt

Set up the OpenCode agent, specifying its binary path, port, and authentication credentials. The 'opencode' section holds these settings.

```yaml
agent:
  type: opencode
opencode:
  binary_path: opencode serve
  port: 4096
  password: $OPENCODE_SERVER_PASSWORD
  username: admin
```

--------------------------------

### Symphony Turn Start Response

Source: https://github.com/junhoyeo/contrabass/blob/main/docs/codex-protocol.md

The response from the Codex app-server after a turn/start request, containing the ID of the initiated turn.

```json
{"id":3,"result":{"turn":{"id":"turn-456"}}}
```

--------------------------------

### Run CI Equivalent Pass

Source: https://github.com/junhoyeo/contrabass/blob/main/CONTRIBUTING.md

Perform a full Continuous Integration check including linting, testing, and building.

```bash
make ci
```

--------------------------------

### Build and Test Commands for Contrabass

Source: https://github.com/junhoyeo/contrabass/blob/main/README.md

Provides a set of make commands for building the project's dashboard and binary, running various test suites, and performing CI checks. Use `make test-quick` for local validation and `make ci` for a fuller pre-push or CI-style pass.

```bash
make build            # build dashboard, then build ./contrabass
make build-dashboard  # build packages/dashboard/dist only
make build-landing    # build packages/landing/dist only
make test             # go test ./... -count=1
make test-dashboard   # bun test in packages/dashboard
make test-landing     # astro check in packages/landing
make test-quick       # recommended local validation path
make test-all         # Go + dashboard tests + landing checks
make ci               # lint + test-quick + binary/dashboard build + landing build
make lint             # go vet ./...
make clean            # remove built artifacts
make release-dry      # dry-run GoReleaser locally (skips publish)
```

--------------------------------

### Lint Project

Source: https://github.com/junhoyeo/contrabass/blob/main/CONTRIBUTING.md

Run `go vet` to check for suspicious constructs and potential errors in the Go code.

```bash
make lint
```

--------------------------------

### GET /api/v1/state

Source: https://context7.com/junhoyeo/contrabass/llms.txt

Retrieves a full snapshot of the orchestrator's current state, including details about running agents and their status.

```APIDOC
## `GET /api/v1/state` — Full orchestrator snapshot

### Description

This endpoint provides a comprehensive overview of the orchestrator's current operational status. It returns a list of all currently running agents, detailing their issue identifiers, attempt numbers, current phases, process IDs, session IDs, workspace paths, token counts, and start times.

### Method

GET

### Endpoint

`/api/v1/state`

### Response

#### Success Response (200)

- **running** (array): An array of objects, where each object represents a running agent.
  - **issue_id** (string): The unique identifier for the issue.
  - **identifier** (string): A general identifier for the task or issue.
  - **attempt** (integer): The current attempt number for this issue.
  - **phase** (string): The current stage of the agent's execution (e.g., "RunningAgent").
  - **pid** (integer): The process ID of the running agent.
  - **session_id** (string): The unique identifier for the agent's session.
  - **workspace** (string): The file path to the agent's workspace.
  - **tokens_in** (integer): The number of input tokens processed by the agent.
  - **tokens_out** (integer): The number of output tokens generated by the agent.
  - **started_at** (string): The timestamp when the agent started, in ISO 8601 format.

### Request Example

```bash
curl -s http://localhost:8080/api/v1/state | jq .
```

### Response Example

```json
{
  "running": [
    {
      "issue_id": "ABC-42",
      "identifier": "ABC-42",
      "attempt": 1,
      "phase": "RunningAgent",
      "pid": 12345,
      "session_id": "thread-abc-turn-xyz",
      "workspace": "/repo/workspaces/ABC-42",
      "tokens_in": 1200,
      "tokens_out": 340,
      "started_at": "2025-07-01T12:00:00Z"
    }
  ]
}
```
```

--------------------------------

### Build Contrabass Binary

Source: https://github.com/junhoyeo/contrabass/blob/main/CONTRIBUTING.md

Compile the Contrabass binary, automatically building the dashboard SPA first.

```bash
make build
```

--------------------------------

### Symphony Thread Start Response

Source: https://github.com/junhoyeo/contrabass/blob/main/docs/codex-protocol.md

The expected response from the Codex app-server after a thread/start request, containing the newly created thread's ID.

```json
{"id":2,"result":{"thread":{"id":"thread-123"}}}
```

--------------------------------

### Initialize Local Board

Source: https://github.com/junhoyeo/contrabass/blob/main/docs/local-board.md

Initialize the local board tracker with a specified issue prefix.

```bash
contrabass board init --prefix CB
```

--------------------------------

### Get Team Health Summary

Source: https://github.com/junhoyeo/contrabass/blob/main/docs/team-mode-features.md

Obtain an aggregate health summary for all workers in a team. Specify context, workspace, team name, and a timeout.

```go
summary, err := runner.GetTeamHealth(ctx, workspace, teamName, 30*time.Second)
```

--------------------------------

### Configure Internal Board Tracker

Source: https://context7.com/junhoyeo/contrabass/llms.txt

Set up the internal tracker using the local filesystem. No external credentials are required. Board directory and issue prefix can be customized.

```yaml
tracker:
  type: internal
  board_dir: .contrabass/board   # default
  issue_prefix: CB               # default
```

--------------------------------

### Running Contrabass from Source

Source: https://github.com/junhoyeo/contrabass/blob/main/README.md

Command to execute the Contrabass application directly from the source code, specifying a configuration file and a port for the web dashboard and API.

```bash
go run ./cmd/contrabass --config testdata/workflow.demo.md --port 8080
```

--------------------------------

### Initialize Request and Response

Source: https://context7.com/junhoyeo/contrabass/llms.txt

Initiates a connection with the Codex App-Server and receives initial server information.

```json
{"method":"initialize","id":1,"params":{"capabilities":{"experimentalApi":true},"clientInfo":{"name":"contrabass","title":"Contrabass","version":"0.1.0"}}}
```

```json
{"id":1,"result":{"userAgent":"codex-app-server/1.0"}}
```

--------------------------------

### Symphony Turn Start Request

Source: https://github.com/junhoyeo/contrabass/blob/main/docs/codex-protocol.md

Request sent by Symphony to initiate a turn within a thread, providing input, context, and policies. The 'sandboxPolicy' can specify network access.

```json
{
  "method": "turn/start",
  "id": 3,
  "params": {
    "threadId": "thread-123",
    "input": [{ "type": "text", "text": "<prompt>" }],
    "cwd": "/abs/workspace/path",
    "title": "MT-123: Issue title",
    "approvalPolicy": "...",
    "sandboxPolicy": { "type": "workspaceWrite", "networkAccess": false }
  }
}
```

--------------------------------

### Run Contrabass from Source

Source: https://github.com/junhoyeo/contrabass/blob/main/CONTRIBUTING.md

Execute the Contrabass application directly from source code, with options for configuration, port, and disabling the TUI.

```bash
go run ./cmd/contrabass --config testdata/workflow.demo.md
go run ./cmd/contrabass --config testdata/workflow.demo.md --port 8080
go run ./cmd/contrabass --config testdata/workflow.demo.md --no-tui
```

--------------------------------

### Create Board Issue with Dependencies

Source: https://github.com/junhoyeo/contrabass/blob/main/docs/local-board.md

Create a new issue with a title, parent issue, assignee, and dependencies.

```bash
contrabass board create --title "Ship team bridge" --parent CB-1 --assignee team-alpha --blocked-by CB-2
```

--------------------------------

### Test Commands for Contrabass Project

Source: https://context7.com/junhoyeo/contrabass/llms.txt

Execute various test suites for the project, including Go tests, dashboard tests, and landing page checks. `make test-quick` is recommended for fast local validation.

```bash
make test             # go test ./... -count=1
```

```bash
make test-dashboard   # bun test in packages/dashboard
```

```bash
make test-landing     # astro check in packages/landing
```

```bash
make test-quick       # recommended fast local validation (lint + go test + build)
```

```bash
make test-all         # Go + dashboard + landing
```

--------------------------------

### Get Worker Health Status

Source: https://github.com/junhoyeo/contrabass/blob/main/docs/team-mode-features.md

Retrieve the health status of a specific worker within a team. Requires context, workspace, team name, and worker name. A timeout can be specified.

```go
report, err := runner.GetWorkerHealth(ctx, workspace, teamName, workerName, 30*time.Second)
```

--------------------------------

### Create and Use fsnotify-backed Config Watcher

Source: https://context7.com/junhoyeo/contrabass/llms.txt

Use NewWatcher to create a file watcher that re-parses configuration on changes. On parse errors, the last known-good configuration is retained. The Watcher satisfies the ConfigProvider interface.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "github.com/junhoyeo/contrabass/internal/config"
)

func main() {
    watcher, err := config.NewWatcher("workflow.md")
    if err != nil {
        log.Fatal("creating watcher:", err)
    }
    defer watcher.Stop()

    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    // Start watching in a goroutine; Watch blocks until ctx is cancelled.
    go func() {
        if err := watcher.Watch(ctx); err != nil {
            log.Println("watcher stopped:", err)
        }
    }()

    // GetConfig always returns the latest successfully parsed config.
    cfg := watcher.GetConfig()
    fmt.Println("current tracker type:", cfg.TrackerType())

    // The watcher also satisfies ConfigProvider used by the orchestrator.
    // orchestrator.NewOrchestrator(tracker, workspace, agent, watcher, logger)
}
```

--------------------------------

### Codex Normal Flow Sequence Diagram

Source: https://github.com/junhoyeo/contrabass/blob/main/docs/codex-protocol.md

Illustrates the sequence of messages exchanged between a Symphony Client and the Codex app-server during a normal operational flow, including initialization, thread start, and turn processing.

```text
Symphony Client                           Codex app-server
    |                                           |
    | -- initialize(id=1, clientInfo, caps) --> |
    | <-- result(id=1, userAgent/...) --------- |
    | -- initialized(notification) -----------> |
    | -- thread/start(id=2, cwd, policy, ...) ->|
    | <-- result(id=2, thread.id) ------------- |
    | -- turn/start(id=3, threadId, input, ..)->|
    | <-- result(id=3, turn.id) --------------- |
    | <-- item/... notifications (stream) ----- |
    | <-- turn/completed ---------------------- |
    |                                           |
```

--------------------------------

### Stream Live Orchestrator Events with GET /api/v1/events

Source: https://context7.com/junhoyeo/contrabass/llms.txt

This endpoint provides a Server-Sent Events (SSE) stream of live events from the orchestrator. It's useful for real-time monitoring of agent and issue status updates.

```bash
curl -N http://localhost:8080/api/v1/events
# Streams:
# data: {"type":"StatusUpdate","payload":{...}}
# data: {"type":"AgentStarted","issue_id":"ABC-42","payload":{...}}
# data: {"type":"AgentFinished","issue_id":"ABC-42","payload":{"tokens_in":1200,...}}
```

```javascript
// Browser EventSource example
const es = new EventSource('http://localhost:8080/api/v1/events');
es.onmessage = (e) => {
  const event = JSON.parse(e.data);
  console.log(event.type, event.payload);
};
```

--------------------------------

### Build Commands for Contrabass Project

Source: https://context7.com/junhoyeo/contrabass/llms.txt

These make commands are used to build the project's frontend assets and the main binary. Use `make build` for a full build or specific targets like `build-dashboard`.

```bash
make build            # build dashboard JS then embed into ./contrabass binary
```

```bash
make build-dashboard  # build packages/dashboard/dist only
```

```bash
make build-landing    # build packages/landing (Astro site)
```

--------------------------------

### Run Contrabass with GitHub Tracker

Source: https://context7.com/junhoyeo/contrabass/llms.txt

Run Contrabass using a workflow configuration that utilizes the GitHub tracker. The GITHUB_TOKEN must be set.

```bash
GITHUB_TOKEN=ghp_xxxx ./contrabass --config workflow.md
```

--------------------------------

### Lookup Issue Details with GET /api/v1/{identifier}

Source: https://context7.com/junhoyeo/contrabass/llms.txt

Use this endpoint to retrieve cached details for a specific issue using its identifier. The response includes issue ID, title, description, URL, and state.

```bash
curl -s http://localhost:8080/api/v1/ABC-42 | jq .
# Response:
# {
#   "id": "abc123",
#   "identifier": "ABC-42",
#   "title": "Fix login redirect bug",
#   "description": "...",
#   "url": "https://linear.app/…",
#   "state": "Running"
# }
```

--------------------------------

### Monitor Team Worker Health and Events in Go

Source: https://context7.com/junhoyeo/contrabass/llms.txt

Use this Go code to get team health summaries, check individual worker intervention needs, read events, and wait for specific team states. Ensure the agent package is imported.

```go
import (
    "context"
    "fmt"
    "time"

    "github.com/junhoyeo/contrabass/internal/agent"
)

func monitorTeam(ctx context.Context, runner agent.TeamRunner) {
    workspace := "/repo/workspaces/CB-1"
    teamName  := "team-alpha"

    // --- Health ---
    summary, err := runner.GetTeamHealth(ctx, workspace, teamName, 30*time.Second)
    if err != nil {
        panic(err)
    }
    fmt.Printf("Team health: %d healthy, %d dead, %d quarantined\n",
        summary.HealthyWorkers, summary.DeadWorkers, summary.QuarantinedWorkers)

    for _, r := range summary.Workers {
        fmt.Printf("  worker=%s alive=%v status=%s task=%s consecutiveErrors=%d\n",
            r.WorkerName, r.Alive, r.Status, r.CurrentTask, r.ConsecutiveErrors)
    }

    // Intervention check
    reason, _ := runner.CheckWorkerNeedsIntervention(ctx, workspace, teamName, "worker-1", 30*time.Second)
    if reason != "" {
        fmt.Println("Worker needs attention:", reason)
    }

    // --- Events ---
    events, _ := runner.ReadEvents(ctx, workspace, teamName, &agent.EventFilter{
        Type: "task_completed",
    })
    for _, e := range events {
        fmt.Println("event:", e.Type, e.Worker, e.TaskID)
    }

    // Wait for the team to go fully idle
    _, _ = runner.AwaitEvent(ctx, workspace, teamName,
        &agent.EventFilter{Type: "all_workers_idle"}, 2*time.Minute)

    // --- Inter-worker messaging ---
    runner.SendMessage(ctx, workspace, teamName, "leader", "worker-1", "please review PR #42")
    runner.BroadcastMessage(ctx, workspace, teamName, "leader", "new tasks available")
    msgs, _ := runner.ListMailbox(ctx, workspace, teamName, "worker-1", false)
    for _, m := range msgs {
        fmt.Printf("  mailbox: from=%s body=%q\n", m.From, m.Body)
        runner.MarkMessageDelivered(ctx, workspace, teamName, "worker-1", m.ID)
    }

    // --- Tasks ---
    task, _ := runner.CreateTask(ctx, workspace, teamName, &agent.TaskV2{
        Subject:            "Implement feature X",
        Description:        "Add support for feature X with full tests",
        RequiresCodeChange: true,
        Role:               "executor",
    })

    result, _ := runner.ClaimTask(ctx, workspace, teamName, task.ID, "worker-1", nil)
    if result.OK {
        // work on the task …
        runner.TransitionTaskStatus(ctx, workspace, teamName,
            task.ID, "in_progress", "completed", result.ClaimToken, strPtr("done"), nil)
    }

    pending, _ := runner.GetTasksByStatus(ctx, workspace, teamName, "pending")
    fmt.Println("pending tasks:", len(pending))

    // --- Restart / recovery ---
    runner.RestartWorker(ctx, workspace, teamName, "worker-2", &agent.WorkerRestartOptions{
        GracePeriod:   5 * time.Second,
        PreserveState: true,
        ReassignTasks: true,
        MaxRetries:    3,
    })
    runner.QuarantineWorker(ctx, workspace, teamName, "worker-3", "too many consecutive errors")
}

func strPtr(s string) *string { return &s }
```

--------------------------------

### Manage Tasks with Contrabass Runner

Source: https://github.com/junhoyeo/contrabass/blob/main/docs/team-mode-features.md

Demonstrates creating, claiming, transitioning, releasing, and querying tasks using the Contrabass runner API. Ensure the runner is properly initialized and context is managed.

```go
// Create a new task
task, err := runner.CreateTask(ctx, workspace, teamName, &TaskV2{
    Subject: "Implement feature X",
    Description: "Add support for feature X with tests",
    RequiresCodeChange: true,
    Role: "executor",
})
```

```go
// Claim a task
result, err := runner.ClaimTask(ctx, workspace, teamName, taskID, "worker-1", nil)
if result.OK {
    claimToken := result.ClaimToken
    // Work on task...
}
```

```go
// Transition task status
resultMsg := "Feature implemented and tested"
transitionResult, err := runner.TransitionTaskStatus(ctx, workspace, teamName,
    taskID, "in_progress", "completed", claimToken, &resultMsg, nil)
```

```go
// Release task claim
releaseResult, err := runner.ReleaseTaskClaim(ctx, workspace, teamName,
    taskID, claimToken, "worker-1")
```

```go
// Query tasks by status
pendingTasks, err := runner.GetTasksByStatus(ctx, workspace, teamName, "pending")
```

```go
// Query tasks by worker
workerTasks, err := runner.GetTasksByWorker(ctx, workspace, teamName, "worker-1")
```

--------------------------------

### Run Contrabass with Internal Tracker

Source: https://context7.com/junhoyeo/contrabass/llms.txt

Execute Contrabass with an internal tracker configuration. This requires no external credentials as issues are stored locally.

```bash
./contrabass --config workflow.md
# No external credentials needed; issues are stored under .contrabass/board/
```

--------------------------------

### Dashboard Development Commands

Source: https://github.com/junhoyeo/contrabass/blob/main/README.md

Commands to initiate development servers for the dashboard and landing site. The repository uses a root Bun workspace for managing these packages.

```bash
make dev-dashboard
make dev-landing
```

--------------------------------

### Configure Local Board Tracker

Source: https://github.com/junhoyeo/contrabass/blob/main/docs/local-board.md

Set up the internal tracker with a specified board directory and issue prefix. Ensure team execution mode is set to 'team'.

```yaml
tracker:
  type: internal
  board_dir: .contrabass/board
  issue_prefix: CB
team:
  execution_mode: team
```

--------------------------------

### Run Individual Test Targets

Source: https://github.com/junhoyeo/contrabass/blob/main/CONTRIBUTING.md

Execute specific test suites for Go modules, the dashboard, or the landing page.

```bash
make test
make test-dashboard
make test-landing
make test-all
```

--------------------------------

### Run Contrabass with Linear Tracker

Source: https://context7.com/junhoyeo/contrabass/llms.txt

Execute the Contrabass CLI with a workflow configuration file, ensuring the LINEAR_API_KEY is provided.

```bash
LINEAR_API_KEY=lin_api_xxxx ./contrabass --config workflow.md
```

--------------------------------

### Configure Linear Tracker

Source: https://context7.com/junhoyeo/contrabass/llms.txt

Set up the Linear tracker by providing the project URL and optionally an assignee ID. Ensure the LINEAR_API_KEY environment variable is set.

```yaml
tracker:
  type: linear
  project_url: https://linear.app/acme/project/my-project-abc123
  assignee_id: $LINEAR_ASSIGNEE   # or leave empty for auto-resolution from token
```

--------------------------------

### Create New Board Issue

Source: https://github.com/junhoyeo/contrabass/blob/main/docs/local-board.md

Create a new issue on the local board with a title and labels.

```bash
contrabass board create --title "Fix retry loop" --labels bug,orchestrator
```

--------------------------------

### Run Contrabass with Demo Workflow

Source: https://github.com/junhoyeo/contrabass/blob/main/README.md

Execute Contrabass using a demo workflow file. Ensure you provide your Linear API token. This command runs Contrabass in its default TUI mode.

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

--------------------------------

### Create issues with contrabass board create

Source: https://context7.com/junhoyeo/contrabass/llms.txt

Create new issues with titles, descriptions, labels, and assignees. Supports defining parent-child hierarchies and blocked-by dependencies.

```bash
# Create issues (supports parent/child hierarchies and blocked-by dependencies)
contrabass board create --title "Implement OAuth login" \
  --description "Add OAuth2 provider support" \
  --labels feature,auth \
  --assignee team-alpha
# Output: CB-1
```

```bash
contrabass board create --title "Write OAuth tests" \
  --parent CB-1 \
  --blocked-by CB-1 \
  --labels test,auth
# Output: CB-2
```

--------------------------------

### Worker Restart and Recovery Options

Source: https://github.com/junhoyeo/contrabass/blob/main/docs/team-mode-features.md

Configure and execute worker restart and quarantine operations. Note that full implementation may require CLI integration.

```go
// Restart a specific worker
result, err := runner.RestartWorker(ctx, workspace, teamName, "worker-1", &WorkerRestartOptions{
    GracePeriod:   5 * time.Second,
    PreserveState: true,
    ReassignTasks: true,
    MaxRetries:    3,
})
```

```go
// Restart all dead workers
results, err := runner.RestartDeadWorkers(ctx, workspace, teamName, 30*time.Second)
```

```go
// Quarantine a problematic worker
err := runner.QuarantineWorker(ctx, workspace, teamName, "worker-2", 
    "Too many consecutive errors")
```

--------------------------------

### Show Board Issue Details

Source: https://github.com/junhoyeo/contrabass/blob/main/docs/local-board.md

Display detailed information about a specific board issue.

```bash
contrabass board show CB-1
```

--------------------------------

### Run Contrabass Tests

Source: https://github.com/junhoyeo/contrabass/blob/main/docs/team-mode-features.md

Execute the Contrabass test suite for the agent package. Use the `-v` flag for verbose output.

```bash
go test ./internal/agent -v -run TestTeam
```

--------------------------------

### Build Dashboard SPA

Source: https://github.com/junhoyeo/contrabass/blob/main/CONTRIBUTING.md

Build only the React dashboard Single Page Application into the `packages/dashboard/dist/` directory.

```bash
make build-dashboard
```

--------------------------------

### Contrabass CLI - Root Command

Source: https://context7.com/junhoyeo/contrabass/llms.txt

The root contrabass command is the primary entry point for running the orchestrator. It supports TUI mode, headless mode, and dry-run options. Environment variables like LINEAR_API_KEY may be required.

```bash
# TUI mode with Linear tracker + Codex agent
LINEAR_API_KEY=lin_api_xxxx \
./contrabass \
  --config workflow.md \
  --log-level debug \
  --log-file contrabass.log \
  --port 8080

# Headless (no TUI, log to stdout)
LINEAR_API_KEY=lin_api_xxxx \
./contrabass --config workflow.md --no-tui

# Dry-run: run one poll cycle then exit
LINEAR_API_KEY=lin_api_xxxx \
./contrabass --config workflow.md --dry-run

# All root 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)
```

--------------------------------

### Release Commands for Contrabass Project

Source: https://context7.com/junhoyeo/contrabass/llms.txt

Commands for tagging a new release and performing a dry run of the release process using GoReleaser. This process triggers cross-platform binary creation and GitHub release updates.

```bash
git tag v0.2.0
git push origin v0.2.0
# Triggers GoReleaser: cross-platform binaries (macOS/Linux amd64/arm64),
# GitHub Release with grouped changelogs, Homebrew tap update.
```

```bash
make release-dry      # dry-run GoReleaser locally (no publish)
```

--------------------------------

### config.NewWatcher

Source: https://context7.com/junhoyeo/contrabass/llms.txt

Creates an fsnotify-backed file watcher that re-parses configuration files on change. It retains the last known-good configuration in case of parsing errors.

```APIDOC
## `config.NewWatcher` — Live Config Reload

`NewWatcher` creates an `fsnotify`-backed file watcher. When the file changes, it re-parses it. On parse error the last known-good config is retained. The `ConfigProvider` interface is satisfied by `*Watcher`, making it compatible with `NewOrchestrator`.

### Usage

```go
watcher, err := config.NewWatcher("workflow.md")
if err != nil {
    log.Fatal("creating watcher:", err)
}
defer watcher.Stop()

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defер cancel()

// Start watching in a goroutine; Watch blocks until ctx is cancelled.
go func() {
    if err := watcher.Watch(ctx); err != nil {
        log.Println("watcher stopped:", err)
    }
}()

// GetConfig always returns the latest successfully parsed config.
cfg := watcher.GetConfig()
fmt.Println("current tracker type:", cfg.TrackerType())
```

### Parameters

- `filename` (string): The path to the configuration file to watch.
```

--------------------------------

### List Board Issues

Source: https://github.com/junhoyeo/contrabass/blob/main/docs/local-board.md

List all issues currently on the local board.

```bash
contrabass board list
```