Getting started

Core concepts

Five words the rest of these docs assume. Worth two minutes.

Task

The unit of work. A task owns a prompt, a git branch, a worktree, one or more agents, and a position on the board. Everything else in octomux attaches to a task.

Worktree

Each task gets its own git worktree on its own branch. Five agents can edit auth.ts at the same time and your working tree never moves. This is also why a task can be handed to a different agent later without conflict.

Harness

The coding agent that actually writes the code — Claude Code or Cursor today. octomux has no agent loop of its own; it launches, resumes and supervises an agent CLI as a subprocess. Choose per task:

octomux create-task --harness cursor -t "Review the diff on agents/in-482" -r .

Because the harness is per task, you can put one agent on a branch another agent wrote — a second opinion from a different model that has not inherited the first one’s assumptions.

Workflow

A kind of scheduled or looped job — its own config form, cron trigger and run history. Schedules, loops, doc-drift and log triage are all workflows. Each one is a registration, not special-cased core code, which is why you can add your own.

Integration

An outbound connection to something external. Jira and Linear move a ticket as the task moves; Slack and Telegram let you drive the fleet from a chat thread. Integrations fire on the task, not the agent — so the ticket moves the same way regardless of which harness did the work.

The board

Tasks move through six columns: backlog, planned, in_progress, human_review, pr, done. Agents move their own cards, and integrations mirror those moves onto your tracker.