[![CI](https://github.com/ShreyPaharia/octomux/actions/workflows/ci.yml/badge.svg)](https://github.com/ShreyPaharia/octomux/actions/workflows/ci.yml) [![npm version](https://img.shields.io/npm/v/octomux)](https://www.npmjs.com/package/octomux) [![license](https://img.shields.io/github/license/ShreyPaharia/octomux)](LICENSE) [![npm downloads](https://img.shields.io/npm/dw/octomux)](https://www.npmjs.com/package/octomux) [![GitHub stars](https://img.shields.io/github/stars/ShreyPaharia/octomux)](https://github.com/ShreyPaharia/octomux) # octomux > **Coding got faster. Managing agents didn't.** octomux is a **local dashboard for running many Claude Code and Cursor agents in parallel.** Each agent works in its own git worktree; you get **one inbox** for every "allow this tool?" prompt, a **live grid** of the whole fleet, and **in-app diff review**. Runs on your machine — no cloud, no telemetry, MIT. ```bash npm install -g octomux && octomux init && cd your-repo && octomux start ``` Open **[localhost:7777](http://localhost:7777)**, describe a task, pick **Claude Code** or **Cursor**, and watch it work. ![octomux demo](assets/demo.gif) --- ## What you get Four acts, one window — from prompt to merged PR: - **① Dispatch** — Type a task (or paste a Jira/Linear/GitHub link, or a whole list). Each one gets its own worktree, branch, and agent. Pick the model and the harness per task. - **② Run unattended** — Attach a verify command and the agent **loops in fresh context until that command exits 0**. Put it on a **cron** and it does that at 3am. Hand a goal to the **orchestrator** and it plans, splits, and dispatches child tasks for you to approve. - **③ Watch, or don't** — Every agent's live terminal on one **Monitor grid**, the diff as it grows, and every "allow this tool?" prompt collected in a single **inbox** instead of scattered across panes. - **④ Review & ship** — An agent drafts a walkthrough and inline comments grounded on the real diff. You read it in-app, mark files reviewed, send comments back for a fix, and publish as one batched GitHub review when _you_ accept it. octomux spots the PR by branch and closes the task when it merges. Crash, reboot, close the lid — `octomux start` restores every task, branch, and session. ### The 60-second version ```bash npm install -g octomux && octomux init cd your-repo && octomux start # → localhost:7777 # or skip the UI and loop a task until the tests actually pass: octomux create-task -t "Fix the flaky checkout test" -d "..." -p "..." -r . octomux loop-start --task --verify "npm test" --max-iterations 8 ``` ## Screenshots Every screenshot is full width — a dashboard shrunk into a table cell is texture, not information. **Review workstation** — the agent opens with a verdict, a risk read, and a ranked list of things worth looking at, each linked to a line. Start there, then drop into the diff. ![Review walkthrough](assets/screenshots/review-walkthrough.png) **Monitor grid** — every running agent's terminal on one wall. Spot the stuck one instantly. ![Monitor grid](assets/screenshots/monitor-grid.png) **Command center** — kanban across the real workflow, backlog → done. ![Command center](assets/screenshots/command-center.png)
More screens — inbox, schedules, orchestrator, diff review, phone **Home inbox + composer** — every "allow this?" in one queue, recent activity, and the dispatch bar. ![Home inbox](assets/screenshots/home-inbox.png) **Schedules** — cron, timezone, model, verify command and prompt, all editable from the UI. ![Schedules](assets/screenshots/schedules.png) **Orchestrator** — an agent planning and dispatching child tasks, each awaiting your approval. ![Orchestrator](assets/screenshots/orchestrator.png) **Diff review** — file tree, reviewed state, inline comments. ![Diff review](assets/screenshots/diff-review.png) **On your phone** — same fleet over a Tailscale tailnet. ![Mobile](assets/screenshots/mobile-remote.png)
## Features Each screen is a lens over one managed agent backend: - **Sessions inbox** — every permission prompt across every agent in one place; reply once, agents keep going. Tab title shows `(N) octomux` when something needs you. - **Command center** — kanban across the real workflow (backlog → planned → in progress → review → PR → done), with filter-to-attention and a restore grace period on delete. - **Monitor grid** — every running agent's terminal tiled into one live wall; spot the stuck one instantly. - **Orchestrator view** — watch an agent that dispatches agents: the parent planning, its children coding, who's blocked — the whole tree at once. - **Review workstation** — an agent drafts a walkthrough + inline comments (grounded against the real diff, no invented line numbers); nothing hits GitHub until you accept it, then it posts as one batched review. Reject a comment with a reason and it remembers for next time. - **Chats, Workspaces, persistent agents** — detach a quick spike as its own session, manage the reusable worktrees behind your tasks, and keep long-lived agents (own system prompt, optional Telegram/Slack channel) on **Agents**. - **Loops** — hand a task a prompt plus a verify command and it re-runs itself in fresh context until verify passes; `/loops` shows the iteration ledger, what each pass changed, and the stop controls. Fan out N competing candidates from one prompt when you want options. - **Schedules** — run a task on a cron from `/schedules` (nightly triage, a weekly digest) instead of remembering to kick it off. - **Worktrees keep agents off each other** — five agents can edit `auth.ts` at once without conflicts on your main tree. - **Run it anywhere** — npm CLI, a **macOS desktop app** ([`.dmg`](https://github.com/ShreyPaharia/octomux/releases)), or hosted on a box and reached from your **phone over Tailscale** (the UI is mobile-ready). - **Local-only** — no telemetry, no cloud sync. Your `.env` stays on the host. ## Patterns Three workflows octomux makes one-click: - **Verifier — two agents, two opinions.** Claude wrote it; drop Cursor on the same branch for a second pass. A different model reads the diff without inheriting the first's assumptions, catching the bugs that pass type-checking but break in prod. - **Sweep — five PRs by lunch.** Paste a Jira filter or GitHub issue list; each ticket gets its own worktree and agent. Come back from standup to a kanban of ready-to-review PRs. - **Operator — one prompt becomes an epic.** Give an agent the orchestrator skills; it plans a spec, breaks it into subtasks, and dispatches each into its own worktree. You supervise from the Orchestrator view. ## How it compares | | **octomux** | vibe-kanban | Conductor | Emdash | | -------------------------------------- | ----------------- | ----------------- | ------------- | --------------- | | License | MIT, open source | MIT (community\*) | Closed | Open source | | Fully local, no cloud | Yes | Now local\* | Cloud account | Yes | | One permission inbox | **Yes** | No | No | No | | Monitor grid (all agents at once) | **Yes** | No | No | No | | Automated review + human-gated publish | **Yes** | Partial | Partial | No | | Recursive orchestration | **Yes** | No | No | No | | Reach it from your phone | **Yes** (tailnet) | No | No | Partial (SSH) | | Claude Code + Cursor | Yes | Yes (10+) | Yes | Yes (20+) | | Platform | macOS + Linux | macOS/Linux/Win | macOS only | macOS/Linux/Win | \* Bloop, the company behind vibe-kanban, wound down in early 2026; it continues as a community project. Verified 2 Aug 2026 against each project's own docs. Something out of date or unfair? [Open an issue](https://github.com/ShreyPaharia/octomux/issues/new) — corrections to this table are welcome and get merged. ## Why octomux The editor was built around a human typing one file at a time. That's not the job anymore. The job is directing a fleet — and the hard part moved from _writing_ code to _reviewing_ it, _unblocking_ it, and _knowing what's happening_ across ten sessions. octomux is a bet on what that surface should look like: not a chat box bolted onto a file tree, but a control deck. It handles the ugly backend of running agents and puts the human's job — the inbox, the fleet grid, the review workstation, the orchestrator — front and center. It's early and opinionated, and the roadmap is shaped in the open. ## Requirements - macOS (arm64/x64) or Linux for the CLI; macOS for the desktop app - Node.js 20+ · `git` (`tmux` ships bundled) - At least one harness: **Claude Code** (`claude`) and/or **Cursor CLI** (`cursor-agent`)
Full CLI reference | Command | Description | | ------------------------------------ | -------------------------------------------------------------------- | | `octomux start` | Dashboard at `:7777` (add `--bind 0.0.0.0` for remote) | | `octomux init` | Defaults wizard (Jira URL/project, base branch) + workflow scripts | | `octomux create-task` | New task (`--harness`, `--model`, `--mode`, `--fork-from`) | | `octomux list-tasks` / `get-task` | Inspect tasks | | `octomux close-task` / `delete-task` | Stop or fully remove | | `octomux resume-task` | Resume a closed task | | `octomux add-agent` | Another agent window (`--model`, `--notify-agent`) | | `octomux send-message` | Message a running agent — course-correct without restart | | `octomux loop-start` | Loop a task until `--verify` passes (`--prompt`, `--max-iterations`) | | `octomux loop-start-group` | Fan out `--n` competing loop candidates from one prompt | | `octomux learn` / `recall` | Record and retrieve durable notes for future runs on a repo | | `octomux plugins list` | List plugins in `octomux.yml` (`disable ` / `enable `) | | `octomux doctor` | Report plugin boot health from the last load report | Full setup, Jira/Linear, and orchestrator skills: **[ONBOARDING.md](./ONBOARDING.md)**.
Remote access from your phone (Tailscale) octomux binds to `127.0.0.1` by default. To reach it from another device, put them on a [Tailscale](https://tailscale.com) tailnet and start in remote mode: ```bash octomux start --bind 0.0.0.0 # or: OCTOMUX_BIND=0.0.0.0 octomux start ``` A random access token is generated on first start (path logged to `~/.octomux/data/remote-token`; override with `OCTOMUX_REMOTE_TOKEN`). Open `http://:7777` from a tailnet device and sign in once. Only tailnet devices can reach the port; the token is a second factor. For HTTPS, front it with `tailscale serve`.
Built to extend octomux keeps a clean line between the **agent backend** (done for you) and the **views** (where the value is). Building blocks available today: - **REST API** (~130 endpoints) over tasks, agents, diffs, reviews, chats, workspaces, skills. - **Three live WebSocket channels** — `/ws/events` for task/chat/review events, `/ws/terminal/*` for bidirectional xterm ↔ tmux, and `/ws/orchestrator/:convId` for the conductor's conversation stream. - **A queryable SQLite schema** — tasks, agents, permission prompts, review runs, comments, learnings. - **User hook scripts** — drop executables in `~/.octomux/hooks/.d/` (or `/.octomux/hooks/.d/`) to fire on task-lifecycle events. There still isn't a drop-in API for custom **UI views** — adding one means building against these blocks in the codebase. For workflows, integration providers, and harnesses, though, see below: that line moved.
## Plugins octomux is a **metaharness** — a third-party npm package can register a **workflow**, an **integration provider**, or a **harness** without forking octomux. List it in `~/.octomux/octomux.yml`, export one `apply(ctx)` function, and octomux calls it at boot. | Registrar | Adds | Example | | ----------------------------- | ---------------------------------------------------------------- | --------------------------------- | | `ctx.workflows.register()` | a workflow kind — cron-triggered or run-based, own config schema | a nightly "translate strings" job | | `ctx.integrations.register()` | a handler for task lifecycle events (issue tracker, chat, CI) | GitHub Issues instead of Jira | | `ctx.harnesses.register()` | a new coding-agent backend | Aider, Codex CLI, OpenHands | The smallest possible plugin — a workflow that logs on every run: ```js // index.js export function apply(ctx) { ctx.workflows.register({ kind: 'hello', displayName: 'Hello World', surfaces: ['session'], run: async (runCtx) => { ctx.logger.info({ repo: runCtx.repoPath }, 'hello from a plugin'); }, }); } ``` Installing one today is manual — there's no `octomux plugins add` yet: ```bash npm install --prefix ~/.octomux octomux-plugin-hello ``` ```yaml # ~/.octomux/octomux.yml plugins: - id: hello name: octomux-plugin-hello # or an absolute path, while developing one locally version: 1.0.0 ``` Restart octomux. `octomux plugins list` shows what's in the manifest; `octomux doctor` reports whether each row actually loaded, and how long its `apply()` took. Full authoring guide and the pinned `@octomux/plugin-api` types: **[docs/plugins/README.md](./docs/plugins/README.md)** · **[API reference](./docs/plugins/api-reference.md)**. **Security, plainly:** a plugin runs in-process with the DB handle, every stored credential, and full `process.env` — there is no sandbox and none is planned. Only install a plugin you'd trust with `npm install`'s postinstall scripts. `octomux start --safe-mode` skips every plugin row at boot if one goes bad. ## FAQ **Is this just tmux + git worktrees?** Underneath, largely yes — one tmux session per task, one window per agent, one worktree per branch. `tmux attach -t octomux-agent-` still works and your own scripts still work; nothing is hidden from you. What octomux adds is the layer above: one permission inbox, the whole fleet on one grid, loops with a verify command, cron schedules, and a review workstation. If you have already built that on top of tmux, you do not need this. **What does it cost to run?** Nothing beyond what you already pay. MIT licensed, and it adds no inference cost of its own — it drives the Claude Code or Cursor subscription you already have. Loops multiply token spend by the iteration count, so set `--max-iterations` and a budget. **Will an overnight loop burn through my plan limits?** Loops are capped. You set a max iteration count and an optional token/time budget, and a loop stops early when it stops making progress. Every pass and its cost lands in the `/loops` ledger, and you can stop a run from the UI or your phone. **What if two agents touch the same file?** During the work they can't — each task is its own git worktree on its own branch, so your main working tree never moves. At merge time you still get normal git conflicts; what octomux gives you is all N diffs in one review queue so you pick the merge order deliberately. **Can I use it from my phone?** Yes — host it on a tailnet box and open the mobile-ready dashboard from any device on the tailnet. **What if my laptop reboots?** Run `octomux start`; tasks, branches, terminals, and review state come back. ## Contributing Issues and PRs are welcome — the roadmap is shaped in the open. ```bash git clone https://github.com/ShreyPaharia/octomux && cd octomux bun install bun run dev # Express :7777 + Vite bun run test # bun test ``` Then open a PR **against `next`** with a short description of the change. See **[CONTRIBUTING.md](./CONTRIBUTING.md)** for architecture and testing patterns, and [good first issues](https://github.com/ShreyPaharia/octomux/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) to get started. We try to respond to PRs within a couple of days. ## Star it If octomux saves you an afternoon of babysitting agents, a ⭐ helps other people find it — and tells me which parts to build next. Thanks for trying it. ## Links [GitHub](https://github.com/ShreyPaharia/octomux) · [npm](https://www.npmjs.com/package/octomux) · [octomux.com](https://octomux.com) · [Releases](https://github.com/ShreyPaharia/octomux/releases)