sisyphi 0.1.17 → 0.1.21

package/README.md

@@ -29,39 +29,21 @@
 
 A tmux-integrated orchestration daemon for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) multi-agent workflows.
 
-A background daemon manages sessions where an **orchestrator** Claude instance breaks tasks into subtasks, spawns **agent** Claude instances in tmux panes, and coordinates their lifecycle through cycles. Agents work in parallel, submit reports, and the orchestrator respawns each cycle with fresh context to review progress and plan next steps.
+## What this is
 
-## How It Works
+Sisyphus is a thin orchestration layer on top of Claude Code. It doesn't replace Claude Code or wrap it in some abstraction — it just runs multiple Claude Code instances in tmux panes and coordinates them. Every agent is a real `claude` process with full access to your codebase, your tools, your CLAUDE.md, your hooks. You keep all the steerability of Claude Code; sisyphus just handles the "run N of them in parallel and loop until done" part.
 
-```
-You ──► sisyphus start "build auth system"
-              │
-              ▼
-        ┌─────────────┐
-        │ Orchestrator │  ◄── Reads state, plans work, spawns agents
-        └──────┬──────┘
-               │ sisyphus spawn (×N)
-               ▼
-     ┌─────┐ ┌─────┐ ┌─────┐
-     │ A-1 │ │ A-2 │ │ A-3 │  ◄── Parallel Claude agents in tmux panes
-     └──┬──┘ └──┬──┘ └──┬──┘
-        │       │       │
-        ▼       ▼       ▼
-   sisyphus submit (each agent reports back)
-              │
-              ▼
-        ┌─────────────┐
-        │ Orchestrator │  ◄── Respawned with updated state (next cycle)
-        └─────────────┘
-```
+If you're familiar with the [Ralph Wiggum loop](https://ghuntley.com/ralph/) — `while true; do claude --prompt task.md; done` — sisyphus is that idea taken further. Instead of one agent in a loop, you get an orchestrator that decomposes work into parallel agents, each looping independently, with structured state that persists across cycles. The orchestrator itself is in a Ralph loop: it plans, spawns agents, gets killed, and respawns fresh with all the results. Same principle, more leverage.
+
+## How it works
 
-1. **You** run `sisyphus start` with a high-level task
-2. **Orchestrator** decomposes it, spawns agents, yields
-3. **Agents** work in parallel tmux panes, send progress reports, submit when done
-4. **Daemon** detects completion, respawns orchestrator with updated state
-5. **Orchestrator** reviews reports, spawns more agents or completes the session
+Most hard tasks aren't hard because any single piece is difficult — they're hard because there are many pieces and context gets lost between them. A developer working a 12-file refactor holds it all in their head until they don't, then makes a mistake three files from the end because they forgot a constraint from the beginning.
 
-The orchestrator is stateless — it's killed after yielding and respawned fresh each cycle with the full session state. This means it never runs out of context, no matter how many cycles a session takes.
+Sisyphus solves this structurally. An **orchestrator** Claude instance reads the full task, breaks it into subtasks, and spawns parallel **agent** Claude instances — each in its own tmux pane with a focused instruction. Agents work simultaneously, submit reports when they're done, and the orchestrator respawns to review progress and plan the next round.
+
+The key mechanism: **the orchestrator is stateless**. After it spawns agents and yields, it gets killed. When all agents finish, the daemon respawns a fresh orchestrator with the complete session state — every agent report, every cycle's history, the running plan. This means the orchestrator never degrades. Cycle 1 and cycle 15 get the same quality of reasoning, because each cycle starts with a full context window and a clean slate. The boulder rolls back down; Sisyphus walks back down after it, picks it up, and pushes again — but this time he remembers everything from every previous push.
+
+The daemon handles the lifecycle: spawning panes, detecting when agents finish, persisting state to disk, respawning the orchestrator. You just describe what you want built and watch it work.
 
 ## Requirements
 
@@ -75,190 +57,65 @@ The orchestrator is stateless — it's killed after yielding and respawned fresh
 npm install -g sisyphi
 ```
 
-This gives you two commands:
-- `sisyphus` — the CLI for interacting with sessions
-- `sisyphusd` — the background daemon
-
-### Claude Code Plugin (optional)
-
-The companion plugin on the [crouton-kit](https://github.com/CaptainCrouton89/crouton-kit) marketplace adds specialized agent types and an orchestration skill with task breakdown patterns for common workflows (bug fixes, feature builds, refactors, reviews, etc.).
-
-```bash
-claude plugins install CaptainCrouton89/crouton-kit sisyphus
-```
-
-This makes `sisyphus:debug`, `sisyphus:implement`, `sisyphus:plan`, and other agent types available for `sisyphus spawn --agent-type`.
-
-## Quick Start
+The daemon starts automatically on first use via launchd. It auto-updates when new versions are published.
 
-### 1. Start the daemon
+## Usage
 
-```bash
-sisyphusd
-```
+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.
 
-The daemon also supports `sisyphusd stop` and `sisyphusd restart` subcommands.
-
-To run it persistently on macOS, use launchd — create `~/Library/LaunchAgents/com.sisyphus.daemon.plist`:
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-  <key>Label</key>
-  <string>com.sisyphus.daemon</string>
-  <key>ProgramArguments</key>
-  <array>
-    <string>sisyphusd</string>
-  </array>
-  <key>KeepAlive</key>
-  <true/>
-  <key>RunAtLoad</key>
-  <true/>
-  <key>StandardOutPath</key>
-  <string>~/.sisyphus/daemon.log</string>
-  <key>StandardErrorPath</key>
-  <string>~/.sisyphus/daemon.log</string>
-</dict>
-</plist>
-```
+In Claude Code, just say something like:
 
-Then load it:
+> Use sisyphus to migrate our REST API from Express to Hono. The API lives in src/api/ with 14 route files...
 
-```bash
-launchctl load ~/Library/LaunchAgents/com.sisyphus.daemon.plist
-```
+Claude will call `sisyphus start` with a detailed task description, and tmux panes will start appearing with parallel agents working on your codebase.
 
-To unload and clean up:
+### Setting up a slash command (recommended)
 
-```bash
-sisyphus uninstall          # Unload from launchd
-sisyphus uninstall --purge  # Also remove ~/.sisyphus data
-```
+Create a file at `.claude/commands/sisyphus-begin.md` in your project:
 
-### 2. Start a session (inside tmux)
+~~~markdown
+Run `sisyphus start` with a detailed task description:
 
 ```bash
-sisyphus start "Refactor the authentication module to use JWT tokens"
+sisyphus start "your task description"
 ```
 
-The orchestrator spawns in a yellow tmux pane and begins planning.
-
-### 3. Watch it work
+**Write a thorough task description.** Include what needs to be built or fixed, where relevant code lives, what done looks like, constraints or preferences, and adjacent concerns (don't break X, keep Y working). More context produces better results — the orchestrator figures out how to break it down.
 
+**Example:**
 ```bash
-sisyphus status              # Check session state and agents
-sisyphus list                # List sessions in current project
-sisyphus list --all          # List sessions across all projects
+sisyphus start "Rip out our hand-rolled RBAC system and replace it with a proper policy engine. Current implementation is scattered across 20+ middleware files in src/middleware/auth/ that each do their own role checks with hardcoded string comparisons. Replace with a centralized policy engine in src/auth/policies/ using a declarative permission model — define resources, actions, and role mappings in a single config, then write one middleware that evaluates policies. Migrate every route that currently calls requireRole() or checkPermission() to the new system. The admin panel (src/routes/admin/) has the most complex rules including org-scoped permissions and delegated access — those need to work exactly as before. Add integration tests that cover the full matrix: superadmin, org-admin, member, and guest across every protected endpoint. Don't break the public API routes in src/routes/v1/public/. The existing test suite (npm test) must pass when you're done."
 ```
+~~~
 
-Agent panes appear as the orchestrator spawns them, color-coded by role. Agent types from the crouton-kit plugin define their own colors via frontmatter; otherwise agents rotate through blue, green, magenta, cyan, red, and white.
+Then in Claude Code, type `/sisyphus-begin` followed by your task and Claude will use sisyphus to orchestrate it.
 
-### 4. Resume or complete
+Alternatively, add a note to your `CLAUDE.md`:
 
-```bash
-sisyphus resume <session-id>                    # Resume a paused session
-sisyphus resume <session-id> "focus on tests"   # Resume with new instructions
-sisyphus kill <session-id>                      # Kill a session and all agents
+```markdown
+## Sisyphus
+For large tasks, use the `sisyphus` CLI to orchestrate parallel agents.
+Run `sisyphus start "detailed task description"` inside tmux.
 ```
 
-## CLI Reference
+### Monitoring and stopping
 
 ```bash
-# Session lifecycle
-sisyphus start "task description"           # Create session, launch orchestrator
-sisyphus status [session-id]                # Session state (defaults to active session)
-sisyphus list [-a, --all]                   # List sessions (--all for cross-project)
-sisyphus resume <id> [message]              # Resume paused session
-sisyphus kill <id>                          # Kill session and all agents
-sisyphus uninstall [--purge] [-y]           # Unload daemon from launchd
-
-# Daemon management
-sisyphusd                                   # Start the daemon
-sisyphusd stop                              # Stop the daemon
-sisyphusd restart                           # Restart the daemon
-
-# Used by the orchestrator/agents (not typically run manually):
-sisyphus spawn --agent-type <t> --name <n> --instruction "..."
-sisyphus spawn --agent-type <t> --name <n> --instruction "..." --worktree
-sisyphus yield [--prompt "next cycle context"]
-sisyphus complete --report "summary"        # Mark session done
-sisyphus submit --report "findings"         # Agent submits final report
-sisyphus report --message "progress"        # Agent sends progress update
+sisyphus status              # Check session state
+sisyphus kill <session-id>   # Stop everything
 ```
 
-Both `yield`, `submit`, and `report` support stdin piping for long content:
-
-```bash
-echo "detailed report" | sisyphus submit
-echo "progress update" | sisyphus report
-```
-
-## Git Worktree Isolation
-
-Agents can work in isolated git worktrees to avoid conflicts when multiple agents edit files in parallel:
-
-```bash
-sisyphus spawn --agent-type sisyphus:implement --name "auth" \
-  --instruction "implement auth module" --worktree
-```
-
-With `--worktree`, the daemon:
-1. Creates a new branch (`sisyphus/{session}/{agent-id}`) and worktree
-2. Symlinks `.sisyphus` and `.claude` directories into the worktree
-3. Runs bootstrap commands from `.sisyphus/worktree.json` (copy files, install deps, etc.)
-4. Automatically merges the agent's branch back when the agent submits
-
-Configure worktree bootstrap in `.sisyphus/worktree.json`:
-
-```json
-{
-  "symlink": [".env", "node_modules"],
-  "copy": ["package.json"],
-  "init": "npm install"
-}
-```
-
-## Architecture
-
-Three layers communicating over a Unix socket (`~/.sisyphus/daemon.sock`):
-
-- **CLI** (`sisyphus`) — Commander.js program that sends JSON requests to the daemon
-- **Daemon** (`sisyphusd`) — Manages sessions, spawns/monitors tmux panes, tracks state
-- **Shared** — Types, protocol definitions, config resolution
-
-### State & Persistence
-
-State is persisted as JSON at `.sisyphus/sessions/{id}/state.json` (project-relative), written atomically via temp file + rename.
-
-Each session directory contains:
-```
-.sisyphus/sessions/{id}/
-├── state.json        # Session state (atomic writes)
-├── plan.md           # Orchestrator memory — outstanding work
-├── logs.md           # Orchestrator memory — session log
-├── prompts/          # Rendered system + user prompt files
-├── reports/          # Agent report files
-└── context/          # Persistent artifacts (specs, plans, explorations)
-```
-
-The orchestrator maintains `plan.md` and `logs.md` across cycles as persistent memory — these survive orchestrator respawns and give each new cycle continuity with previous work.
-
 ## Configuration
 
-Config is layered: project (`.sisyphus/config.json`) overrides global (`~/.sisyphus/config.json`).
+Project (`.sisyphus/config.json`) overrides global (`~/.sisyphus/config.json`):
 
 ```json
 {
   "model": "sonnet",
-  "pollIntervalMs": 1000,
-  "tmuxSession": "my-session"
+  "autoUpdate": true
 }
 ```
 
-You can also override the orchestrator prompt per-project by placing a file at `.sisyphus/orchestrator.md`.
-
 ## License
 
 MIT

package/dist/cli.js

@@ -229,17 +229,23 @@ function getTmuxWindow() {
 
 // src/cli/commands/start.ts
 function registerStart(program2) {
-  program2.command("start").description("Start a new sisyphus session").argument("<task>", "Task description for the orchestrator").action(async (task) => {
+  program2.command("start").description("Start a new sisyphus session").argument("<task>", "Task description for the orchestrator").option("-c, --context <context>", "Background context for the orchestrator").action(async (task, opts) => {
     const tmuxSession = getTmuxSession();
     const tmuxWindow = getTmuxWindow();
-    const request = { type: "start", task, cwd: process.cwd(), tmuxSession, tmuxWindow };
+    const request = { type: "start", task, context: opts.context, cwd: process.cwd(), tmuxSession, tmuxWindow };
     const response = await sendRequest(request);
     if (response.ok) {
       const sessionId = response.data?.sessionId;
-      console.log(`Session started: ${sessionId}`);
-      if (response.data?.tmuxWindow) {
-        console.log(`Orchestrator spawned in tmux window: ${response.data.tmuxWindow}`);
-      }
+      console.log(`Task handed off to sisyphus orchestrator (session ${sessionId})`);
+      console.log(`The orchestrator and its agents will handle this task autonomously \u2014 no further action needed from you.`);
+      console.log(`
+Monitor:`);
+      console.log(`  sisyphus status ${sessionId}    # agents, cycles, reports`);
+      console.log(`  tail -f ~/.sisyphus/daemon.log   # daemon activity`);
+      console.log(`
+Control:`);
+      console.log(`  sisyphus resume ${sessionId} "new instructions"  # respawn with follow-up`);
+      console.log(`  sisyphus kill ${sessionId}        # stop all agents and orchestrator`);
     } else {
       console.error(`Error: ${response.error}`);
       process.exit(1);
@@ -247,21 +253,40 @@ function registerStart(program2) {
   });
 }
 
+// src/cli/stdin.ts
+function readStdin() {
+  if (process.stdin.isTTY) return Promise.resolve(null);
+  return new Promise((resolve2, reject) => {
+    const chunks = [];
+    process.stdin.on("data", (chunk) => chunks.push(chunk));
+    process.stdin.on("end", () => {
+      const text = Buffer.concat(chunks).toString("utf-8").trim();
+      resolve2(text || null);
+    });
+    process.stdin.on("error", reject);
+  });
+}
+
 // src/cli/commands/spawn.ts
 function registerSpawn(program2) {
-  program2.command("spawn").description("Spawn a new agent (orchestrator only)").option("--agent-type <type>", "Agent role label (default: worker)", "worker").requiredOption("--name <name>", "Agent name").requiredOption("--instruction <instruction>", "Task instruction for the agent").option("--worktree", "Spawn agent in an isolated git worktree").action(async (opts) => {
+  program2.command("spawn").description("Spawn a new agent (orchestrator only)").argument("[instruction]", "Task instruction for the agent").option("--agent-type <type>", "Agent role label (default: worker)", "worker").requiredOption("--name <name>", "Agent name").option("--instruction <instruction>", "Task instruction for the agent (or pipe via stdin)").option("--worktree", "Spawn agent in an isolated git worktree").action(async (positionalInstruction, opts) => {
     assertTmux();
     const sessionId = process.env.SISYPHUS_SESSION_ID;
     if (!sessionId) {
       console.error("Error: SISYPHUS_SESSION_ID environment variable not set");
       process.exit(1);
     }
+    const instruction = opts.instruction ?? positionalInstruction ?? await readStdin();
+    if (!instruction) {
+      console.error("Error: --instruction is required (or pipe via stdin)");
+      process.exit(1);
+    }
     const request = {
       type: "spawn",
       sessionId,
       agentType: opts.agentType,
       name: opts.name,
-      instruction: opts.instruction,
+      instruction,
       ...opts.worktree ? { worktree: true } : {}
     };
     const response = await sendRequest(request);
@@ -279,22 +304,6 @@ function registerSpawn(program2) {
 
 // src/cli/commands/submit.ts
 import { execSync as execSync3 } from "child_process";
-
-// src/cli/stdin.ts
-function readStdin() {
-  if (process.stdin.isTTY) return Promise.resolve(null);
-  return new Promise((resolve2, reject) => {
-    const chunks = [];
-    process.stdin.on("data", (chunk) => chunks.push(chunk));
-    process.stdin.on("end", () => {
-      const text = Buffer.concat(chunks).toString("utf-8").trim();
-      resolve2(text || null);
-    });
-    process.stdin.on("error", reject);
-  });
-}
-
-// src/cli/commands/submit.ts
 function isInWorktree() {
   try {
     const gitDir = execSync3("git rev-parse --git-dir", { encoding: "utf-8" }).trim();
@@ -350,7 +359,6 @@ function registerSubmit(program2) {
 }
 
 // src/cli/commands/yield.ts
-import { writeFileSync as writeFileSync2 } from "fs";
 function registerYield(program2) {
   program2.command("yield").description("Yield control back to daemon (orchestrator only)").option("--prompt <text>", "Instructions for the next orchestrator cycle (or pipe via stdin)").action(async (opts) => {
     assertTmux();
@@ -363,7 +371,6 @@ function registerYield(program2) {
     const request = { type: "yield", sessionId, agentId: "orchestrator", nextPrompt };
     const response = await sendRequest(request);
     if (response.ok) {
-      writeFileSync2(`/tmp/sisyphus-exit-${sessionId}`, "");
       console.log("Yielded. Waiting for agents to complete.");
     } else {
       console.error(`Error: ${response.error}`);
@@ -373,7 +380,6 @@ function registerYield(program2) {
 }
 
 // src/cli/commands/complete.ts
-import { writeFileSync as writeFileSync3 } from "fs";
 function registerComplete(program2) {
   program2.command("complete").description("Mark session as completed (orchestrator only)").requiredOption("--report <report>", "Final completion report").action(async (opts) => {
     assertTmux();
@@ -385,8 +391,10 @@ function registerComplete(program2) {
     const request = { type: "complete", sessionId, report: opts.report };
     const response = await sendRequest(request);
     if (response.ok) {
-      writeFileSync3(`/tmp/sisyphus-exit-${sessionId}`, "");
       console.log("Session completed.");
+      console.log(`
+Follow up:`);
+      console.log(`  sisyphus resume ${sessionId} "new instructions"  # respawn orchestrator with follow-up`);
     } else {
       console.error(`Error: ${response.error}`);
       process.exit(1);
@@ -463,6 +471,10 @@ function printSession(session) {
 ${BOLD}Session: ${session.id}${RESET}`);
   console.log(`  Status: ${status}`);
   console.log(`  Task: ${session.task}`);
+  if (session.context) {
+    const truncated = session.context.length > 120 ? session.context.slice(0, 120) + "..." : session.context;
+    console.log(`  Context: ${truncated}`);
+  }
   console.log(`  CWD: ${session.cwd}`);
   console.log(`  Created: ${session.createdAt}`);
   console.log(`  Duration: ${sessionDuration}${session.completedAt ? "" : " (ongoing)"}`);