Getting started

Quickstart

Two commands to install, one to start. octomux drives a coding agent CLI you already have — it does not ship a model and adds no inference cost of its own.

Requirements

Requirement	Notes
Node.js 20+	The CLI and server both run on it.
macOS or Linux	A macOS desktop app is also available from Releases.
git	Every task runs in its own worktree.
An agent CLI	Claude Code or Cursor, already authenticated. octomux uses the subscription you have.

Install

npm install -g octomux && octomux start

Run it from inside a repo and it starts on localhost:7777. There is nothing to configure first.

If you would rather set defaults up front — harness, model, integrations — octomux init is an interactive setup that writes them to ~/.octomux/settings.json. It is optional; use --non-interactive with flags for scripted installs.

First task

Open localhost:7777, describe a task, pick your harness, and watch it work.

Or skip the UI

Everything the dashboard does is available on the CLI, which is also how an agent drives octomux.

octomux create-task -t "Fix the flaky checkout test" -r .
octomux loop-start --task <id> --verify "npm test" --max-iterations 8

A loop re-runs the agent in fresh context until the verify command exits 0, the iteration cap is hit, or it stops making progress.

Surviving a restart

Run octomux start again after a reboot. Tasks, branches, terminals and review progress all come back. If you want scheduled work to keep running when your laptop is shut, host it on a machine that stays up and reach it over a tailnet.