octomux

octomux is a local dashboard for running multiple Claude Code and Cursor agents in parallel. Each agent works in its own git worktree, avoiding interference with each other; all "Allow this tool?" permission prompts are collected into a single inbox, and it provides a real-time grid of the entire agent cluster and in-app diff review. It runs entirely on the user's machine, with no cloud sync, no telemetry, and is MIT licensed.

Purpose

octomux solves the problem of "writing code has gotten faster, but managing agents has not." It consolidates the flow from prompt to merged PR into a single window, letting users command multiple coding agents at once instead of switching back and forth between multiple terminal panes.

Main capabilities

• Dispatch: Enter tasks, paste Jira/Linear/GitHub links or an entire list, and each task gets its own worktree, branch, and agent; models and harnesses can be selected per task.
• Unattended runs: After attaching a verification command, the agent loops in a fresh context until the command exits with 0; it can be scheduled with cron. After handing a goal to the orchestrator, it plans, splits, and dispatches subtasks, waiting for user approval.
• Monitoring: Real-time terminals for all agents are gathered into a Monitor grid, diffs grow in real time, and all permission prompts are collected into a single inbox.
• Review and delivery: Agents draft walkthrough notes and inline comments based on the real diff; users read in-app, mark files as reviewed, send comments back for fixes, and once accepted, publish as a single batched GitHub review. octomux identifies PRs by branch and closes the task after merge.
• Recovery: After a crash, restart, or closing the laptop, running octomux start restores all tasks, branches, and sessions.

How to use

Open localhost:7777, describe the task, and choose Claude Code or Cursor to begin. It supports an npm CLI, a macOS desktop app (.dmg), and can also be hosted on a server and accessed from a phone via Tailscale (the interface is adapted for mobile). It binds by default to 127.0.0.1; remote mode generates a random access token, the path is recorded in ~/.octomux/data/remote-token, and can be overridden with OCTOMUX_REMOTE_TOKEN .

Requirements: macOS (arm64/x64) or Linux for the CLI; macOS for the desktop app; Node.js 20+; git (tmux is bundled); and at least one harness: Claude Code (claude) and/or Cursor CLI (cursor-agent).

Workflow examples

• Verifier: two agents, two opinions. After Claude writes, have Cursor do a second review on the same branch; a different model does not inherit the former's assumptions and can catch bugs that pass type checking but fail in production.
• Batch processing: Paste a Jira filter or GitHub issue list, and each ticket gets its own worktree and agent; before lunch break you can produce five PRs ready for review.
• Operator: one prompt becomes an epic. After giving the agent orchestration skills, it plans the spec, splits subtasks, and distributes them to their own worktrees, supervising in the Orchestrator view.

Extensions and plugins

octomux is a meta harness; third-party npm packages can register workflows, integration providers, or harnesses without forking. Listed in ~/.octomux/octomux.yml , exporting a apply(ctx) function that octomux calls at startup. Currently, installing plugins must be done manually; there is no octomux plugins add command.octomux plugins list shows the manifest contents, andoctomux doctor reports whether each line actually loaded and the time taken by apply() .

Security note: plugins run in-process, with a database handle, all stored credentials, and full process.env, there is no sandbox, and none is planned. Only install plugins whose npm install postinstall scripts you trust.octomux start --safe-mode can skip all plugin lines at startup.

Use cases

For developers who need to run multiple coding agents simultaneously, centrally manage permission prompts, review diffs in batches, and orchestrate large tasks. octomux does not add inference costs; it drives existing Claude Code or Cursor subscriptions. Loops multiply token consumption by the number of iterations, so you can set --max-iterations and a budget. Each task has its own worktree, and the main worktree does not move. During merges, normal git conflicts still occur, but all diffs are centralized in a single review queue, allowing you to deliberately choose the merge order.

Limitations

• There is currently no plug-and-play API for custom UI views.
• Plugin installation must be done manually.
• There is no cloud sync or telemetry; remote access requires a network such as Tailscale.
• For complete setup, Jira/Linear integration, and orchestration techniques, see ONBOARDING.md.