octomux 1.0.26 → 1.0.29

package/README.md

@@ -4,185 +4,183 @@
 
 # octomux
 
-**Your local command center for autonomous Claude Code agents.**
+> **Coding got faster. Managing agents didn't.**
 
-Pull tasks from Jira, GitHub, or any source your agent can read. Agents work in isolated worktrees. Get notified when they need you. PRs auto-link and tasks auto-close on merge. Review diffs with built-in lazygit. Survives restarts.
+A local web app to **dispatch, watch, and review** parallel **Claude Code** and **Cursor** agents from one place. Kanban for fleet status. One inbox for every "allow this tool?" prompt. In-app diff review with **Ship**. No cloud. MIT.
 
-![octomux dashboard](assets/screenshots/dashboard-hero.png)
-
-## The Loop
-
-```
-1. INTAKE      Pull Jira tickets or GitHub issues — auto-creates tasks with prompts
-2. EXECUTE     Each task gets its own worktree, branch, and Claude Code agents
-3. SUPERVISE   Live terminals + notifications when agents finish or need attention
-4. REVIEW      Built-in lazygit & lazyvim — check diffs without leaving octomux
-5. MERGE       PRs auto-detected and linked — tasks auto-close when PRs merge
-6. RESUME      Close your laptop. Reboot. Everything picks back up automatically.
+```bash
+npm install -g octomux && octomux init && cd your-repo && octomux start
 ```
 
-> The orchestrator agent can drive this entire loop autonomously — or you can control each step from the CLI and dashboard.
-
-## Features
-
-### Orchestrator: agents managing agents
+Open [http://localhost:7777](http://localhost:7777) — describe a task in the composer, pick **Claude Code** or **Cursor**, and watch agents work in place.
 
-A dedicated Claude Code instance that orchestrates your entire workflow. Create tasks, monitor status, add agents, create PRs — all via slash commands (`/create-task`, `/list-tasks`, `/status`, `/create-pr`).
+## From prompt to merged PR
 
-Wire it to Jira MCP, GitHub CLI, or any source — the orchestrator pulls context and creates properly named tasks with initial prompts. Ships with Claude Code skills (`create-task`, `create-pr`, `create-commit`) that any agent can use directly.
+Three phases, one window:
 
-![orchestrator](assets/screenshots/orchestrator.png)
+- **01 — Dispatch.** Type a task. Pick Claude Code or Cursor. Hit go. The composer takes plain English, Jira links, or GitHub issue URLs. Drop a second agent on the same branch with one click.
+- **02 — Watch.** See every agent work, live. Each task streams its own view — files the agent is editing, the diff as it grows, terminal output as it runs. When an agent needs permission, the prompt lands in your inbox so you don't have to babysit every pane.
+- **03 — Review & Ship.** Diff review in the same window. File tree, per-file reviewed state, inline comments. Hit **Ship** and the PR auto-links to the task — closes itself when the PR merges.
 
-### Intake from anywhere
+Code never leaves your laptop. No telemetry, no cloud sync. Crash, reboot, close the lid — `octomux start` restores every task, branch, and session.
 
-- Any Claude Code agent can create tasks via `octomux create-task`
-- Works with Jira MCP, GitHub CLI, or anything your agent can read
-- Auto-generates task names and initial prompts from ticket context
-- Draft tasks: create in draft mode, edit title/prompt/branch before starting
+## Screenshots
 
-### Auto-review from reviewer requests
+|                                                                               |                                                          |
+| ----------------------------------------------------------------------------- | -------------------------------------------------------- |
+| **Home inbox + composer** — permission prompts, recent activity, dispatch bar | ![Home](assets/screenshots/dashboard-hero.png)           |
+| **Command center** — kanban from backlog → done                               | ![Command center](assets/screenshots/command-center.png) |
+| **Settings** — default harness, Cursor model & `--force`                      | ![Settings](assets/screenshots/settings-harnesses.png)   |
+| **Task cockpit** — agent tabs, live Claude session, Ship, Done                | ![Task detail](assets/screenshots/task-detail.png)       |
+| **Diff review** — file tree, reviewed state, inline comments                  | ![Diff](assets/screenshots/diff-review.png)              |
 
-- When you're added as a reviewer on a PR in any tracked repo (any repo that
-  appears in `octomux recent-repos`), octomux stages a **draft** review task
-  prefilled with `/review-pr <url>` and PR context
-- Tasks stay in draft until you approve — no agents start automatically
-- If you haven't approved and the request is withdrawn (review submitted / PR
-  closed / reviewer removed), the draft is cleaned up on the next poll
-- If the review is already running when new commits arrive, the existing agent
-  is nudged via a tmux message — no duplicate task is created
-- Owner identity is resolved once via `gh api user` and cached; override with
-  `OCTOMUX_GITHUB_LOGIN` if you want octomux to watch a different account
-
-### Isolated execution
+## Features
 
-- Each task gets its own git worktree, branch, and tmux session
-- Multiple agents per task, working in parallel
-- Custom base branches supported (work from `develop`, not just `main`)
-- Your main working tree stays untouched
+- **Sessions inbox** — every permission prompt and question lands in one place; reply once, agents keep going. Tab title shows `(N) octomux` when something needs you.
+- **Command center** — kanban for backlog → done; drag status, archive, workflow from draft → ship.
+- **In-app diff review** — compare to `main`, mark files reviewed, queue inline comments, open lazygit in-editor.
+- **Dual harnesses** — run **Claude Code** (`claude`) or **Cursor** (`cursor-agent`) per task; mix agents on one task via **Add agent**.
+- **Worktrees keep agents off each other** — each task gets its own git worktree and `agents/<task-id>` branch; five agents can edit `auth.ts` at the same time without conflicts on your main tree.
+- **Live task view** — see every agent work in real time: files edited, diff growing, terminal output streaming via xterm.js. Attach the same session from the CLI if you prefer.
+- **Agents that dispatch agents** — `/create-task`, `/list-tasks`, `/send-agent-message` skills work inside any Claude Code window; recursive dispatch from inside an agent.
+- **Integrations** — Jira wiring plus orchestrator skills for GitHub / auto-review intake.
+- **CLI ↔ dashboard parity** — `octomux create-task`, `send-message`, `resume-task` — same tasks the UI shows.
+- **Reboot-proof** — WAL SQLite + preserved worktrees across restarts.
+- **Local-only** — no telemetry, no cloud sync, no analytics. Your `.env` stays on the host.
 
-### Smart supervision
+## Patterns
 
-- Live terminals in the dashboard via xterm.js
-- Color-coded agent activity: green (active), gray (idle), amber (waiting for input)
-- Notifications when agents finish, stop unexpectedly, or hit permission prompts
-- Browser tab shows `(N) octomux` + red favicon dot when tasks need attention
-- Toast notifications with "View" button — one click to the relevant agent
-- Send messages to running agents via `octomux send-message`
-- Smart status: tasks needing attention surface before idle tasks
+Three workflows octomux makes one-click:
 
-![task detail](assets/screenshots/task-detail.png)
+### Verifier — two agents, two opinions
 
-### Built-in review
+Claude wrote it. Drop Cursor on the same branch for a second pass. Same-model self-review is just self-confirmation — a different model reads the diff without inheriting the first agent's assumptions. Catches missing nonce checks, off-by-one TTLs, and the kind of mistakes that pass type-checking but break in prod.
 
-- Lazygit and lazyvim integrated — review diffs inside octomux
-- Open ad-hoc shell terminals in any task's worktree from the dashboard
-- No context switching to a separate terminal or IDE
-- Clean branches ready to push and PR when you're satisfied
+> Finish a task with Claude → hit **Add agent** → pick Cursor → reviews land as inline comments → you arbitrate, Ship.
 
-![lazygit review](assets/screenshots/lazygit-review.png)
+### Sweep — five PRs by lunch
 
-### Auto PR detection + merge
+Paste a Jira filter or GitHub issue list into the composer. Each ticket gets its own worktree, branch, and agent. Mix Claude and Cursor across the batch so the model best at each kind of task ends up on it. Come back from standup to a kanban of ready-to-review PRs.
 
-- Background poller detects PRs on task branches via `gh pr list`
-- PR URLs auto-linked in task cards — visible from the dashboard
-- Tasks auto-close when their PRs are merged
-- Zero manual status updates from task creation to merged code
+### Operator — one prompt becomes an epic
 
-### Survives restarts
+Give an agent the orchestrator skills. It plans the work, breaks down the spec, and dispatches subtasks — each one gets its own worktree, mergeable independently. Inside a Claude Code window, the agent itself becomes the user of octomux. You supervise from the dashboard.
 
-- Full state persistence in SQLite across reboots
-- On next `octomux start`, running tasks are recovered and agent sessions resume
-- Close your laptop, come back tomorrow, run `octomux start`, keep going
+> `/create-task`, `/list-tasks`, `/send-agent-message` skills inside any Claude Code window. Recursive dispatch.
 
-### Safety: graduated trust
+## Quick start
 
-Each task worktree gets a permission config (`.claude/settings.local.json`) with three tiers:
+```bash
+brew install tmux git
+npm install -g @anthropic-ai/claude-code    # and/or Cursor CLI
+npm install -g octomux
+octomux init
+cd your-project
+octomux start
+```
 
-- **Denied**: `git push --force`, `rm -rf`, `git reset --hard` — always blocked
-- **Allowed**: read-only ops, safe writes, non-force `git push` — auto-approved
-- **Prompted**: everything else requires explicit user permission
+```bash
+octomux create-task -t "Add OAuth login" -r .
+octomux create-task -t "Spike with Cursor" -r . --harness cursor
+```
 
-Permission prompts surface in the dashboard with tool name and input details. Agents can't destroy things without asking first.
+Step-by-step setup, Jira, and orchestrator skills: [ONBOARDING.md](./ONBOARDING.md)
 
-## Quick Start
+## How it works
 
-```bash
-npm install -g octomux
-cd your-project
-octomux start                                    # opens dashboard at localhost:7777
-octomux create-task -t "Add auth flow" -r .      # create a task from the CLI
+```
+DISPATCH → BRANCH → CODE → INBOX → REVIEW → MERGE
 ```
 
-Open [http://localhost:7777](http://localhost:7777) to watch agents work, or keep using the CLI.
-
-## CLI Commands
-
-| Command                                           | Description                                     |
-| ------------------------------------------------- | ----------------------------------------------- |
-| `octomux start`                                   | Launch the local web dashboard                  |
-| `octomux create-task`                             | Create a new task                               |
-| `octomux list-tasks`                              | List all tasks                                  |
-| `octomux get-task <id>`                           | Get task details                                |
-| `octomux close-task <id>`                         | Stop agents and preserve the worktree           |
-| `octomux delete-task <id>`                        | Fully clean up task state, branch, and worktree |
-| `octomux resume-task <id>`                        | Resume a previously closed task                 |
-| `octomux add-agent <task-id>`                     | Add an agent to an existing task                |
-| `octomux send-message <task-id> <agent-id> "msg"` | Send a message to an agent                      |
-
-## Why octomux?
-
-|                      | Without octomux          | With octomux                             |
-| -------------------- | ------------------------ | ---------------------------------------- |
-| Git isolation        | Manual worktrees         | Automatic per task                       |
-| Agent visibility     | Tab-switching            | Single dashboard with activity dots      |
-| Backlog intake       | Copy-paste prompts       | Agent-driven from Jira/GH                |
-| PR tracking          | Manual                   | Auto-detected and linked                 |
-| Task completion      | Manual status updates    | Auto-closes on PR merge                  |
-| After a reboot       | Start over               | Auto-resumes                             |
-| Reviewing changes    | Switch to terminal + git | Built-in lazygit                         |
-| Agent safety         | Hope for the best        | Graduated trust: denied/allowed/prompted |
-| Lifecycle management | None                     | draft → running → closed                 |
-
-## How It Works
+| Phase        | What happens                                                                |
+| ------------ | --------------------------------------------------------------------------- |
+| **Dispatch** | Composer, CLI, orchestrator skills, or Jira/GitHub drafts                   |
+| **Branch**   | Automatic git worktree + `agents/<task-id>` branch                          |
+| **Code**     | tmux session per task; harness launches `claude` or `cursor-agent`          |
+| **Inbox**    | Every permission prompt or question collects in one place                   |
+| **Review**   | Diff tab, lazygit terminal, mark files reviewed, **Ship** / **Done**        |
+| **Merge**    | PR poller links branches; tasks close when their PRs merge                  |
+| _Recovery_   | DB + worktrees survive reboot — `octomux start` picks up where you left off |
+
+## CLI
+
+| Command                              | Description                                              |
+| ------------------------------------ | -------------------------------------------------------- |
+| `octomux start`                      | Dashboard at `:7777`                                     |
+| `octomux init`                       | Defaults wizard (Jira, base branch, harness prefs)       |
+| `octomux create-task`                | New task (`--harness cursor` optional)                   |
+| `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                                     |
+| `octomux send-message`               | Message a running agent — course-correct without restart |
+
+## Architecture
 
 ```mermaid
-graph LR
-    O[Orchestrator Agent] -->|octomux create-task| B[Dashboard / API]
-    A[Any Claude Code Agent] -->|octomux create-task| B
-    B --> C[Git Worktree]
-    B --> D[tmux Session]
-    B --> H[(SQLite DB)]
-    D --> E[Claude Code Agent]
-    E -->|done / permission| F[Notifications]
-    C --> G[lazygit Review]
-    H -->|recovery on restart| D
-    E -->|git push| P[GitHub PR]
-    P -->|poller detects merge| B
+flowchart LR
+  subgraph intake [Intake]
+    C[Composer]
+    CLI[CLI / skills]
+  end
+  subgraph core [octomux]
+    API[API + SQLite]
+    IN[Inbox]
+    BC[Command center]
+  end
+  subgraph run [Per task]
+    WT[Worktree]
+    TM[tmux]
+    H[Claude or Cursor]
+  end
+  C --> API
+  CLI --> API
+  API --> WT
+  API --> TM
+  TM --> H
+  H -->|hooks| API
+  API --> IN
+  API --> BC
+  WT --> DIFF[Diff review]
+  H --> GH[GitHub PR]
+  GH -->|poller| API
 ```
 
 ## Requirements
 
-- **macOS** (ARM64 or x64)
-- **Node.js 20+**
-- **tmux**: `brew install tmux`
-- **git**: `brew install git`
-- **Claude Code CLI**: `npm install -g @anthropic-ai/claude-code`
-
-> Xcode Command Line Tools (`xcode-select --install`) may be needed if native dependencies (`better-sqlite3`, `node-pty`) require local compilation.
+- macOS (ARM64 or x64), Node.js 20+
+- `tmux`, `git`
+- At least one harness: **Claude Code** (`claude`) and/or **Cursor CLI** (`cursor-agent`)
+- Recommended: `lazygit`, `neovim`
 
 ## Configuration
 
-| Option          | Description                     | Default                 |
-| --------------- | ------------------------------- | ----------------------- |
-| `--port <port>` | Port for the dashboard          | `7777`                  |
-| `--no-open`     | Do not auto-open the browser    | —                       |
-| `PORT`          | Alternative to `--port`         | `7777`                  |
-| `OCTOMUX_URL`   | Server URL used by CLI commands | `http://localhost:7777` |
+| Variable / flag           | Purpose                          |
+| ------------------------- | -------------------------------- |
+| `OCTOMUX_PORT` / `--port` | Dashboard port (default `7777`)  |
+| `OCTOMUX_URL`             | CLI → API base URL               |
+| `OCTOMUX_DB_PATH`         | Override task DB path            |
+| `OCTOMUX_GITHUB_LOGIN`    | Reviewer-request polling account |
+
+## FAQ
+
+**What's the difference between octomux and just running tmux + Claude Code?**
+octomux adds the kanban, the inbox, and diff review on top. tmux is just plumbing underneath.
+
+**Does it work with Cursor?**
+Yes. Pick Claude Code or Cursor per task. Mix them on the same task with **Add agent**.
+
+**What happens if two agents touch the same file?**
+They can't — each task runs in its own git worktree on its own branch. Five agents can edit `auth.ts` at the same time without conflicts on your main tree.
+
+**What if my laptop reboots or crashes?**
+Run `octomux start`. Tasks, branches, terminals, and review state all come back.
+
+**How do I track what each agent is costing me?**
+Each agent's tmux session has its own session log; Claude Code and Cursor both emit token usage there. A first-class cost view in the dashboard is on the roadmap.
 
 ## Links
 
-- GitHub: [github.com/ShreyPaharia/octomux](https://github.com/ShreyPaharia/octomux)
-- npm: [npmjs.com/package/octomux](https://www.npmjs.com/package/octomux)
-- Landing page: [octomux.com](https://octomux.com)
+- [GitHub](https://github.com/ShreyPaharia/octomux) · [npm](https://www.npmjs.com/package/octomux) · [octomux.dev](https://octomux.dev)
 
-Contributions welcome — [open an issue](https://github.com/ShreyPaharia/octomux/issues) or submit a PR.
+Issues and PRs welcome.

package/bin/octomux-hook-bridge.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+
+/**
+ * octomux-hook-bridge.js — Cursor hook bridge script
+ *
+ * Self-contained Node.js script (no npm dependencies). Copied into each
+ * worktree's .octomux-hooks/ directory alongside a config.json that carries
+ * {baseUrl, token}. Cursor invokes this as a hook command with event JSON
+ * on stdin; the bridge forwards it to the octomux server and writes the
+ * response JSON to stdout.
+ *
+ * Fail-open principle: any error (network, parse, missing config) writes '{}'
+ * to stdout and exits 0 so Cursor is never blocked by bridge failures.
+ *
+ * The bridge NEVER exits with code 2. Deny is communicated via stdout JSON
+ * {"permission":"deny",...} with exit 0.
+ */
+
+import fs from 'node:fs';
+import http from 'node:http';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+// Hardcoded denylist — mirrors Claude's DENIED_TOOLS destructive set.
+// These regexes are checked against event.command for beforeShellExecution.
+const DENYLIST = [
+  { re: /^\s*rm\s+-rf(\s|$)/, label: 'rm -rf' },
+  { re: /^\s*git\s+push\s+--force(\s|$)/, label: 'git push --force' },
+  { re: /^\s*git\s+reset\s+--hard(\s|$)/, label: 'git reset --hard' },
+];
+
+function writeStdout(obj) {
+  process.stdout.write(JSON.stringify(obj));
+}
+
+/**
+ * POST JSON to a local http:// URL. Returns a promise that resolves with the
+ * response status code on success, or rejects on network/timeout error.
+ */
+function postJson(url, token, body) {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(url);
+    const qs = '?token=' + encodeURIComponent(token);
+
+    const options = {
+      protocol: parsed.protocol,
+      hostname: parsed.hostname,
+      port: parsed.port || 80,
+      path: parsed.pathname + qs,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+    };
+
+    const payload = JSON.stringify(body);
+
+    const req = http.request(options, (res) => {
+      // Consume response body to free socket
+      res.resume();
+      res.on('end', () => resolve(res.statusCode));
+    });
+
+    // 5-second timeout — fail-open on expiry
+    req.setTimeout(5000, () => {
+      req.destroy(new Error('Hook bridge request timed out'));
+    });
+
+    req.on('error', reject);
+    req.write(payload);
+    req.end();
+  });
+}
+
+async function main() {
+  // Step 1: read all stdin synchronously. fd 0 = stdin.
+  let stdinText = '';
+  try {
+    stdinText = fs.readFileSync(0, 'utf8');
+  } catch {
+    // No stdin available — treat as empty
+  }
+
+  // Step 2: parse stdin JSON. Malformed input → fail-open.
+  let event;
+  try {
+    event = JSON.parse(stdinText);
+  } catch {
+    writeStdout({});
+    process.exit(0);
+  }
+
+  // Step 3: resolve and read sibling config.json.
+  let baseUrl, token;
+  try {
+    const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+    const configPath = path.join(scriptDir, 'config.json');
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    baseUrl = config.baseUrl;
+    token = config.token;
+    if (!baseUrl || !token) throw new Error('config.json missing baseUrl or token');
+  } catch (err) {
+    console.error('[octomux-hook-bridge] Failed to load config.json:', err);
+    writeStdout({});
+    process.exit(0);
+  }
+
+  // Step 4: branch on hook_event_name.
+  const eventName = event.hook_event_name;
+
+  if (eventName === 'sessionStart') {
+    try {
+      await postJson(baseUrl + '/api/hooks/session-start', token, {
+        conversation_id: event.conversation_id,
+        session_id: event.session_id,
+        is_background_agent: event.is_background_agent ?? false,
+      });
+    } catch (err) {
+      // HTTP error — fail-open
+      console.error('[octomux-hook-bridge] sessionStart HTTP error:', err);
+    }
+    writeStdout({});
+  } else if (eventName === 'beforeSubmitPrompt') {
+    try {
+      await postJson(baseUrl + '/api/hooks/user-prompt-submit', token, {
+        conversation_id: event.conversation_id,
+        prompt: event.prompt,
+      });
+    } catch (err) {
+      console.error('[octomux-hook-bridge] beforeSubmitPrompt HTTP error:', err);
+    }
+    writeStdout({ continue: true });
+  } else if (eventName === 'beforeShellExecution') {
+    // Apply denylist locally — no HTTP call.
+    const command = event.command ?? '';
+    for (const rule of DENYLIST) {
+      if (rule.re.test(command)) {
+        writeStdout({
+          permission: 'deny',
+          user_message: 'Blocked by octomux denylist: ' + rule.label,
+        });
+        process.exit(0);
+      }
+    }
+    writeStdout({ permission: 'allow' });
+  } else if (eventName === 'postToolUse' || eventName === 'afterFileEdit') {
+    // Normalize both events to the {tool_name, tool_input} shape that
+    // /api/hooks/post-tool-use expects (Claude's PostToolUse shape).
+    // - postToolUse already carries tool_name + tool_input, pass through.
+    // - afterFileEdit carries file_path at top-level; synthesize a tool_use
+    //   so the server's current_summary deriver picks up the file path.
+    let body;
+    if (eventName === 'afterFileEdit') {
+      body = {
+        conversation_id: event.conversation_id,
+        tool_name: 'Edit',
+        tool_input: { file_path: event.file_path },
+      };
+    } else {
+      body = {
+        conversation_id: event.conversation_id,
+        tool_name: event.tool_name,
+        tool_input: event.tool_input,
+      };
+    }
+    try {
+      await postJson(baseUrl + '/api/hooks/post-tool-use', token, body);
+    } catch (err) {
+      console.error('[octomux-hook-bridge] postToolUse/afterFileEdit HTTP error:', err);
+    }
+    writeStdout({});
+  } else {
+    // Unknown event — fail-open
+    writeStdout({});
+  }
+}
+
+main().catch((err) => {
+  // Top-level safety net — any unhandled error must not crash Cursor
+  console.error('[octomux-hook-bridge] Unhandled error:', err);
+  writeStdout({});
+  process.exit(0);
+});