sisyphi 1.1.16 → 1.1.18

package/README.md

@@ -48,8 +48,9 @@ The daemon handles the lifecycle: spawning panes, detecting when agents finish,
 ## Requirements
 
 - **Node.js** >= 22
-- **tmux** (you must be inside a tmux session)
+- **tmux** >= 3.2 (you must be inside a tmux session)
 - **Claude Code** CLI (`claude`) installed and authenticated
+- **Neovim** (optional — enables embedded editor in the dashboard)
 
 ## Install
 
@@ -57,9 +58,27 @@ The daemon handles the lifecycle: spawning panes, detecting when agents finish,
 npm install -g sisyphi
 ```
 
-The daemon starts automatically on first use via launchd. It auto-updates when new versions are published.
+Then run one-time setup:
 
-## Usage
+```bash
+sisyphus setup
+```
+
+This installs the background daemon (macOS launchd), tmux keybindings (`M-s` to cycle sessions, `M-S` for dashboard), and checks your environment. The daemon auto-updates when new versions are published.
+
+Verify everything is working:
+
+```bash
+sisyphus doctor
+```
+
+## Quick start
+
+```bash
+sisyphus start "your task description"    # Start a session
+sisyphus dashboard                        # Open the TUI (auto-opens on start)
+sisyphus status                           # Check session state from the CLI
+```
 
 Sisyphus is a CLI that Claude Code calls for you. You tell Claude to use it, and Claude handles the rest — calling `sisyphus start`, writing the task description, and kicking off the orchestration loop.
 
@@ -98,13 +117,161 @@ For large tasks, use the `sisyphus` CLI to orchestrate parallel agents.
 Run `sisyphus start "detailed task description"` inside tmux.
 ```
 
-### Monitoring and stopping
+### Interactive tutorial
+
+If you're new to tmux or sisyphus, run the guided walkthrough:
+
+```bash
+sisyphus getting-started
+```
+
+Six steps covering tmux basics, neovim essentials, sisyphus concepts, and a live demo session.
+
+## Dashboard
+
+The dashboard is a full-screen TUI for monitoring and controlling sessions in real time.
 
 ```bash
-sisyphus status              # Check session state
-sisyphus kill <session-id>   # Stop everything
+sisyphus dashboard    # or press M-S (Alt-Shift-S)
 ```
 
+It auto-opens when you `sisyphus start` a session.
+
+**Layout:**
+
+- **Left panel** — Session tree with collapsible hierarchy: sessions → cycles → agents → reports. Status indicators show active/completed/paused state at a glance.
+- **Right panel** — Context-sensitive detail view for the selected node: session roadmap, agent instructions, report content, or live pane output. Opens files in an embedded neovim instance when available.
+- **Bottom bar** — Current mode, keybinding hints, and transient notifications.
+
+**Key bindings:**
+
+| Key | Action |
+|-----|--------|
+| `j/k` or `↑/↓` | Navigate tree / scroll detail |
+| `h/l` or `←/→` | Collapse/expand nodes |
+| `n` | New session (compose mode) |
+| `R` | Resume a paused/completed session |
+| `w` | Jump to session's tmux window |
+| `g` | Edit goal | 
+| `p` | Open roadmap |
+| `m` | Message orchestrator |
+| `r` | Re-run agent |
+| `x` | Restart agent |
+| `Space` | Leader menu (copy, delete, spawn agent, shell, etc.) |
+| `Tab` | Cycle panel focus |
+| `/` | Search sessions |
+| `?` | Help overlay |
+
+Compose mode opens a temp file in the embedded neovim for multi-line input (new sessions, messages, resume instructions). Falls back to tmux popups if neovim isn't available.
+
+## Agent types
+
+Agents can be spawned with role templates that define their model, behavior, and capabilities. The orchestrator discovers available types automatically and uses them to match the right agent to each subtask.
+
+### Built-in types
+
+Sisyphus ships these agent types:
+
+| Type | Description |
+|------|-------------|
+| `sisyphus:worker` | Generic agent (default) |
+| `sisyphus:plan` | Plan lead — breaks work into phases |
+| `sisyphus:design` | Technical design and architecture |
+| `sisyphus:requirements` | EARS-based requirements analysis |
+| `sisyphus:problem` | Problem exploration and assumption challenging |
+| `sisyphus:review` | Code review |
+| `sisyphus:review-plan` | Plan review with parallel sub-reviewers |
+| `sisyphus:debug` | Systematic debugging investigation |
+| `sisyphus:explore` | Lightweight code exploration |
+| `sisyphus:operator` | QA/testing with browser automation |
+| `sisyphus:test-spec` | Test specification writing |
+
+### Custom agent types
+
+Define your own by creating a markdown file with YAML frontmatter:
+
+```markdown
+---
+name: security-reviewer
+description: Reviews code for security vulnerabilities
+model: opus
+color: red
+effort: high
+skills: [capture]
+permissionMode: bypassPermissions
+interactive: false
+---
+
+You are a security-focused code reviewer. Analyze the code for OWASP top 10
+vulnerabilities, injection risks, auth bypasses, and data exposure...
+```
+
+**Resolution order** (first match wins):
+1. `.claude/agents/{name}.md` (project-local)
+2. `~/.claude/agents/{name}.md` (user-global)
+3. Bundled `sisyphus:{name}`
+4. Installed Claude Code plugins
+
+### Frontmatter options
+
+| Field | Description |
+|-------|-------------|
+| `model` | LLM model (`opus`, `sonnet`, `gpt-4`, `codex-mini`, etc.) |
+| `color` | Tmux pane border color |
+| `effort` | `low` / `medium` / `high` / `max` |
+| `interactive` | `true` = agent can pause for user input |
+| `skills` | Claude Code skills to enable |
+| `permissionMode` | Permission handling mode |
+
+Models prefixed with `gpt-` or `codex-` automatically route to the OpenAI provider (Codex CLI).
+
+## Tmux integration
+
+### Status bar
+
+The daemon renders a live status indicator into your tmux status bar showing all sessions scoped to the current working directory:
+
+- **Yellow dot** — orchestrator processing
+- **Yellow diamond** — agents running
+- **Green dot** — session completed
+- **Red dot** — waiting for input
+- **Gray** — idle / between cycles
+
+Session phases update every 5 seconds. The currently focused session is highlighted.
+
+### Keybindings
+
+Installed by `sisyphus setup` into `~/.sisyphus/tmux.conf`:
+
+| Key | Action |
+|-----|--------|
+| `M-s` | Cycle through sisyphus sessions in current project |
+| `M-S` | Jump to dashboard window |
+| `prefix-x` | Smart kill — kills pane or session depending on context |
+
+### Native notifications (macOS)
+
+On macOS, sisyphus builds a native notification helper (`SisyphusNotify.app`) during install. Notifications fire on session completion, agent crashes, and other lifecycle events. Clicking a notification switches your terminal to the relevant session.
+
+Falls back to `terminal-notifier` or `osascript` if the native app isn't available.
+
+## Companion
+
+The companion is a persistent character that tracks your work across sessions. It earns XP, levels up (30 levels from *Boulder Intern* to *The Absurd Hero*), unlocks achievements, and shifts mood based on your usage patterns — time of day, session length, crash frequency, efficiency.
+
+It manifests as:
+- A mood-colored face in the tmux status bar (updates in real time)
+- Commentary on lifecycle events (session start, level-up, late-night coding) generated by Haiku
+- An achievement gallery with 66 unlockable badges across milestone, session, time, and behavioral categories
+
+```bash
+sisyphus companion              # View profile, stats, and achievements
+sisyphus companion --badges     # Full achievement gallery
+sisyphus companion --name Bub   # Rename your companion
+```
+
+In the dashboard, press `Space` → `c` to open the companion overlay.
+
 ## Configuration
 
 Project (`.sisyphus/config.json`) overrides global (`~/.sisyphus/config.json`):
@@ -112,10 +279,45 @@ Project (`.sisyphus/config.json`) overrides global (`~/.sisyphus/config.json`):
 ```json
 {
   "model": "sonnet",
-  "autoUpdate": true
+  "orchestratorEffort": "high",
+  "agentEffort": "medium",
+  "pollIntervalMs": 5000,
+  "autoUpdate": true,
+  "notifications": {
+    "enabled": true,
+    "sound": "/System/Library/Sounds/Hero.aiff"
+  }
 }
 ```
 
+| Option | Default | Description |
+|--------|---------|-------------|
+| `model` | *(Claude Code default)* | LLM model for orchestrator and agents |
+| `orchestratorEffort` | `high` | Effort level for orchestrator (`low`/`medium`/`high`/`max`) |
+| `agentEffort` | `medium` | Effort level for agents |
+| `orchestratorPrompt` | *(built-in)* | Path to custom orchestrator system prompt |
+| `pollIntervalMs` | `5000` | Daemon poll interval in milliseconds |
+| `autoUpdate` | — | Auto-update via npm on new releases |
+| `notifications.enabled` | `true` | Desktop notifications on lifecycle events |
+| `notifications.sound` | macOS Hero | Notification sound file path |
+| `requiredPlugins` | `[devcore]` | Claude Code plugins to auto-install for agents |
+
+## CLI reference
+
+**Session lifecycle:**
+`start`, `kill`, `resume`, `continue`, `rollback`, `complete`
+
+**Agent & orchestrator interaction:**
+`spawn`, `submit`, `report`, `yield`, `message`, `restart-agent`, `update-task`
+
+**Monitoring:**
+`status` (`--verbose`), `list` (`--all`), `dashboard`
+
+**Setup & utilities:**
+`setup`, `init`, `doctor`, `getting-started`, `companion`, `uninstall`
+
+Run `sisyphus --help` or `sisyphus <command> --help` for full usage.
+
 ## License
 
 MIT

package/dist/{chunk-6TIO23U3.js → chunk-22ZGZTGY.js}

@@ -46,8 +46,8 @@ function execEnv() {
 // src/shared/exec.ts
 import { execSync } from "child_process";
 var EXEC_ENV = execEnv();
-function exec(cmd, cwd) {
-  return execSync(cmd, { encoding: "utf-8", env: EXEC_ENV, cwd }).trim();
+function exec(cmd, cwd, timeoutMs = 3e4) {
+  return execSync(cmd, { encoding: "utf-8", env: EXEC_ENV, cwd, timeout: timeoutMs }).trim();
 }
 function execSafe(cmd, cwd) {
   try {
@@ -64,4 +64,4 @@ export {
   exec,
   execSafe
 };
-//# sourceMappingURL=chunk-6TIO23U3.js.map
+//# sourceMappingURL=chunk-22ZGZTGY.js.map

package/dist/{chunk-6TIO23U3.js.map → chunk-22ZGZTGY.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/shared/env.ts","../src/shared/exec.ts"],"sourcesContent":["import { resolve } from 'node:path';\n\n/**\n * Build a PATH string that includes common binary directories\n * across package managers and platforms.\n *\n * Prepends known directories that exist on the system to the current PATH.\n * This ensures tmux commands can find binaries installed by Homebrew,\n * MacPorts, nix, and other package managers.\n */\nexport function augmentedPath(): string {\n  const rawPath = process.env['PATH'];\n  const basePath = rawPath !== undefined && rawPath.length > 0 ? rawPath : '/usr/bin:/bin';\n\n  // Common binary directories across platforms/package managers.\n  // Only prepend ones that aren't already in PATH.\n  const home = process.env['HOME'];\n  const candidates = [\n    ...(home ? [`${home}/.local/bin`] : []),  // Claude CLI, pipx, user-local installs\n    resolve(process.execPath, '..'),           // Node.js bin dir (ensures node/npm available)\n    '/opt/homebrew/bin',              // Homebrew (Apple Silicon macOS)\n    '/opt/homebrew/sbin',             // Homebrew sbin\n    '/usr/local/bin',                 // Homebrew (Intel macOS), manual installs\n    '/usr/local/sbin',                // Manual installs\n    '/opt/local/bin',                 // MacPorts\n    '/opt/local/sbin',                // MacPorts\n    '/home/linuxbrew/.linuxbrew/bin', // Linuxbrew\n  ];\n\n  // Check for nix profile paths\n  const nixProfile = process.env['NIX_PROFILES'];\n  if (nixProfile) {\n    for (const p of nixProfile.split(' ').reverse()) {\n      candidates.push(`${p}/bin`);\n    }\n  }\n\n  const existing = new Set(basePath.split(':'));\n  const prepend = candidates.filter(dir => !existing.has(dir));\n\n  return prepend.length > 0 ? `${prepend.join(':')}:${basePath}` : basePath;\n}\n\n/**\n * Environment variables for child processes that need access to\n * user-installed binaries (tmux, git, claude, etc.).\n */\nexport function execEnv(): Record<string, string | undefined> {\n  return {\n    ...process.env,\n    PATH: augmentedPath(),\n  };\n}\n","import { execSync } from 'node:child_process';\nimport { execEnv } from './env.js';\n\nexport const EXEC_ENV = execEnv();\n\nexport function exec(cmd: string, cwd?: string): string {\n  return execSync(cmd, { encoding: 'utf-8', env: EXEC_ENV, cwd }).trim();\n}\n\nexport function execSafe(cmd: string, cwd?: string): string | null {\n  try {\n    return execSync(cmd, { encoding: 'utf-8', env: EXEC_ENV, cwd, stdio: ['pipe', 'pipe', 'pipe'] }).trim();\n  } catch { return null; }\n}\n"],"mappings":";;;AAAA,SAAS,eAAe;AAUjB,SAAS,gBAAwB;AACtC,QAAM,UAAU,QAAQ,IAAI,MAAM;AAClC,QAAM,WAAW,YAAY,UAAa,QAAQ,SAAS,IAAI,UAAU;AAIzE,QAAM,OAAO,QAAQ,IAAI,MAAM;AAC/B,QAAM,aAAa;AAAA,IACjB,GAAI,OAAO,CAAC,GAAG,IAAI,aAAa,IAAI,CAAC;AAAA;AAAA,IACrC,QAAQ,QAAQ,UAAU,IAAI;AAAA;AAAA,IAC9B;AAAA;AAAA,IACA;AAAA;AAAA,IACA;AAAA;AAAA,IACA;AAAA;AAAA,IACA;AAAA;AAAA,IACA;AAAA;AAAA,IACA;AAAA;AAAA,EACF;AAGA,QAAM,aAAa,QAAQ,IAAI,cAAc;AAC7C,MAAI,YAAY;AACd,eAAW,KAAK,WAAW,MAAM,GAAG,EAAE,QAAQ,GAAG;AAC/C,iBAAW,KAAK,GAAG,CAAC,MAAM;AAAA,IAC5B;AAAA,EACF;AAEA,QAAM,WAAW,IAAI,IAAI,SAAS,MAAM,GAAG,CAAC;AAC5C,QAAM,UAAU,WAAW,OAAO,SAAO,CAAC,SAAS,IAAI,GAAG,CAAC;AAE3D,SAAO,QAAQ,SAAS,IAAI,GAAG,QAAQ,KAAK,GAAG,CAAC,IAAI,QAAQ,KAAK;AACnE;AAMO,SAAS,UAA8C;AAC5D,SAAO;AAAA,IACL,GAAG,QAAQ;AAAA,IACX,MAAM,cAAc;AAAA,EACtB;AACF;;;ACpDA,SAAS,gBAAgB;AAGlB,IAAM,WAAW,QAAQ;AAEzB,SAAS,KAAK,KAAa,KAAsB;AACtD,SAAO,SAAS,KAAK,EAAE,UAAU,SAAS,KAAK,UAAU,IAAI,CAAC,EAAE,KAAK;AACvE;AAEO,SAAS,SAAS,KAAa,KAA6B;AACjE,MAAI;AACF,WAAO,SAAS,KAAK,EAAE,UAAU,SAAS,KAAK,UAAU,KAAK,OAAO,CAAC,QAAQ,QAAQ,MAAM,EAAE,CAAC,EAAE,KAAK;AAAA,EACxG,QAAQ;AAAE,WAAO;AAAA,EAAM;AACzB;","names":[]}
+{"version":3,"sources":["../src/shared/env.ts","../src/shared/exec.ts"],"sourcesContent":["import { resolve } from 'node:path';\n\n/**\n * Build a PATH string that includes common binary directories\n * across package managers and platforms.\n *\n * Prepends known directories that exist on the system to the current PATH.\n * This ensures tmux commands can find binaries installed by Homebrew,\n * MacPorts, nix, and other package managers.\n */\nexport function augmentedPath(): string {\n  const rawPath = process.env['PATH'];\n  const basePath = rawPath !== undefined && rawPath.length > 0 ? rawPath : '/usr/bin:/bin';\n\n  // Common binary directories across platforms/package managers.\n  // Only prepend ones that aren't already in PATH.\n  const home = process.env['HOME'];\n  const candidates = [\n    ...(home ? [`${home}/.local/bin`] : []),  // Claude CLI, pipx, user-local installs\n    resolve(process.execPath, '..'),           // Node.js bin dir (ensures node/npm available)\n    '/opt/homebrew/bin',              // Homebrew (Apple Silicon macOS)\n    '/opt/homebrew/sbin',             // Homebrew sbin\n    '/usr/local/bin',                 // Homebrew (Intel macOS), manual installs\n    '/usr/local/sbin',                // Manual installs\n    '/opt/local/bin',                 // MacPorts\n    '/opt/local/sbin',                // MacPorts\n    '/home/linuxbrew/.linuxbrew/bin', // Linuxbrew\n  ];\n\n  // Check for nix profile paths\n  const nixProfile = process.env['NIX_PROFILES'];\n  if (nixProfile) {\n    for (const p of nixProfile.split(' ').reverse()) {\n      candidates.push(`${p}/bin`);\n    }\n  }\n\n  const existing = new Set(basePath.split(':'));\n  const prepend = candidates.filter(dir => !existing.has(dir));\n\n  return prepend.length > 0 ? `${prepend.join(':')}:${basePath}` : basePath;\n}\n\n/**\n * Environment variables for child processes that need access to\n * user-installed binaries (tmux, git, claude, etc.).\n */\nexport function execEnv(): Record<string, string | undefined> {\n  return {\n    ...process.env,\n    PATH: augmentedPath(),\n  };\n}\n","import { execSync } from 'node:child_process';\nimport { execEnv } from './env.js';\n\nexport const EXEC_ENV = execEnv();\n\nexport function exec(cmd: string, cwd?: string, timeoutMs: number = 30_000): string {\n  return execSync(cmd, { encoding: 'utf-8', env: EXEC_ENV, cwd, timeout: timeoutMs }).trim();\n}\n\nexport function execSafe(cmd: string, cwd?: string): string | null {\n  try {\n    return execSync(cmd, { encoding: 'utf-8', env: EXEC_ENV, cwd, stdio: ['pipe', 'pipe', 'pipe'] }).trim();\n  } catch { return null; }\n}\n"],"mappings":";;;AAAA,SAAS,eAAe;AAUjB,SAAS,gBAAwB;AACtC,QAAM,UAAU,QAAQ,IAAI,MAAM;AAClC,QAAM,WAAW,YAAY,UAAa,QAAQ,SAAS,IAAI,UAAU;AAIzE,QAAM,OAAO,QAAQ,IAAI,MAAM;AAC/B,QAAM,aAAa;AAAA,IACjB,GAAI,OAAO,CAAC,GAAG,IAAI,aAAa,IAAI,CAAC;AAAA;AAAA,IACrC,QAAQ,QAAQ,UAAU,IAAI;AAAA;AAAA,IAC9B;AAAA;AAAA,IACA;AAAA;AAAA,IACA;AAAA;AAAA,IACA;AAAA;AAAA,IACA;AAAA;AAAA,IACA;AAAA;AAAA,IACA;AAAA;AAAA,EACF;AAGA,QAAM,aAAa,QAAQ,IAAI,cAAc;AAC7C,MAAI,YAAY;AACd,eAAW,KAAK,WAAW,MAAM,GAAG,EAAE,QAAQ,GAAG;AAC/C,iBAAW,KAAK,GAAG,CAAC,MAAM;AAAA,IAC5B;AAAA,EACF;AAEA,QAAM,WAAW,IAAI,IAAI,SAAS,MAAM,GAAG,CAAC;AAC5C,QAAM,UAAU,WAAW,OAAO,SAAO,CAAC,SAAS,IAAI,GAAG,CAAC;AAE3D,SAAO,QAAQ,SAAS,IAAI,GAAG,QAAQ,KAAK,GAAG,CAAC,IAAI,QAAQ,KAAK;AACnE;AAMO,SAAS,UAA8C;AAC5D,SAAO;AAAA,IACL,GAAG,QAAQ;AAAA,IACX,MAAM,cAAc;AAAA,EACtB;AACF;;;ACpDA,SAAS,gBAAgB;AAGlB,IAAM,WAAW,QAAQ;AAEzB,SAAS,KAAK,KAAa,KAAc,YAAoB,KAAgB;AAClF,SAAO,SAAS,KAAK,EAAE,UAAU,SAAS,KAAK,UAAU,KAAK,SAAS,UAAU,CAAC,EAAE,KAAK;AAC3F;AAEO,SAAS,SAAS,KAAa,KAA6B;AACjE,MAAI;AACF,WAAO,SAAS,KAAK,EAAE,UAAU,SAAS,KAAK,UAAU,KAAK,OAAO,CAAC,QAAQ,QAAQ,MAAM,EAAE,CAAC,EAAE,KAAK;AAAA,EACxG,QAAQ;AAAE,WAAO;AAAA,EAAM;AACzB;","names":[]}

package/dist/{chunk-UIVQXCWB.js → chunk-6PJVJEYQ.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   loadConfig
-} from "./chunk-IF55HPWX.js";
+} from "./chunk-V36NXMHP.js";
 
 // src/daemon/plugins.ts
 import { readFileSync } from "fs";
@@ -43,4 +43,4 @@ export {
   resolveInstalledPlugin,
   resolveRequiredPluginDirs
 };
-//# sourceMappingURL=chunk-UIVQXCWB.js.map
+//# sourceMappingURL=chunk-6PJVJEYQ.js.map