claude-multi-session 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,545 @@
+# claude-multi-session
+
+**Multi-session orchestrator for Claude Code CLI** — spawn, control, pause, resume, and send multiple inputs to Claude Code sessions programmatically.
+
+Built on Claude CLI's `stream-json` protocol for efficient multi-turn conversations using a single long-lived process per session.
+
+## Why?
+
+Claude Code's `-p` (print) mode is one-shot: one prompt, one response. For larger projects you need:
+
+- **Multi-turn conversations** — send follow-ups without restarting
+- **Parallel sessions** — work on multiple tasks simultaneously
+- **Pause & Resume** — stop a session and come back later
+- **Session forking** — branch off to try different approaches
+- **Cost tracking** — know what each session costs
+- **Programmatic control** — use from scripts or other tools
+
+This package solves all of the above with zero dependencies.
+
+## Install
+
+```bash
+npm install -g claude-multi-session
+```
+
+### Quick Setup (MCP Integration)
+
+After installing, run the setup wizard to register the MCP server with Claude Code:
+
+```bash
+cms setup
+```
+
+This adds 17 native tools to Claude Code (spawn_session, delegate_task, etc.) so Claude can manage sessions directly — no Bash commands needed.
+
+**Non-interactive options:**
+```bash
+cms setup --global          # Register for all projects
+cms setup --local           # Register for current project only
+cms setup --global --guide  # Also add strategy guide to CLAUDE.md
+cms setup --uninstall       # Remove MCP integration
+```
+
+### CLI Usage
+
+Use `cms` (or `claude-multi-session`) from anywhere:
+
+```bash
+cms spawn --name my-task --prompt "Fix the auth bug"
+cms send --name my-task --message "Also add tests"
+```
+
+**Or use without installing:**
+```bash
+npx claude-multi-session spawn --name my-task --prompt "Fix the auth bug"
+```
+
+**Prerequisites:** [Claude Code CLI](https://claude.ai/code) must be installed and authenticated.
+
+## Quick Start
+
+```bash
+# Start a session with a prompt
+cms spawn --name fix-auth --prompt "Fix the authentication bug in auth.service.ts" --model sonnet
+
+# Send follow-up messages (same session, full context retained)
+cms send --name fix-auth --message "Also add input validation"
+cms send --name fix-auth --message "Now write tests for it"
+
+# Stop when done (can resume later)
+cms stop --name fix-auth
+
+# Resume days later
+cms resume --name fix-auth --message "Actually, handle the edge case too"
+
+# Check what happened
+cms output --name fix-auth --full
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `spawn` | Start a new session |
+| `send` | Send follow-up message (auto-resumes if stopped) |
+| `resume` | Restore a stopped/paused session |
+| `pause` | Pause session (process stays alive) |
+| `fork` | Branch off into new session (keeps parent context) |
+| `stop` | Gracefully stop (saves state, can resume later) |
+| `kill` | Force kill a session |
+| `status` | Show detailed session info |
+| `output` | Get last response text |
+| `list` | List all sessions |
+| `history` | Show full interaction history |
+| `delete` | Permanently remove a session |
+| `batch` | Spawn multiple sessions from JSON file |
+| `cleanup` | Remove old sessions |
+| `delegate` | Smart task delegation with safety limits + control loop |
+| `continue` | Send follow-up to a delegated session |
+
+## How It Works
+
+### Streaming Mode (Default)
+
+Uses Claude CLI's `--input-format stream-json` to keep **one process alive** per session:
+
+```
+spawn  → starts ONE claude process (stays alive)
+send   → pipes message into stdin → reads response from stdout
+send   → pipes again → reads again (same process, no reload)
+```
+
+**Benefits over the resume approach:**
+- No process restart overhead (~2-3s saved per message)
+- No conversation history reload (lower token cost)
+- Instant follow-up responses
+
+### Session Persistence
+
+Sessions are saved to `~/.claude-multi-session/sessions.json`. When a session is stopped, its Claude session ID is saved. When you resume it later, the system uses `--resume <session-id>` to restore the full conversation context.
+
+## Parallel Tasks
+
+### Batch Mode
+```bash
+# Create a tasks.json file
+echo '[
+  { "name": "task-1", "prompt": "Build login page", "model": "sonnet" },
+  { "name": "task-2", "prompt": "Build signup page", "model": "sonnet" },
+  { "name": "task-3", "prompt": "Build dashboard", "model": "sonnet" }
+]' > tasks.json
+
+# Spawn all in parallel
+cms batch --file tasks.json
+```
+
+### Programmatic API
+```javascript
+const { SessionManager } = require('claude-multi-session');
+const mgr = new SessionManager();
+
+// Spawn multiple sessions in parallel
+const results = await mgr.batch([
+  { name: 'task-1', prompt: 'Build login page', model: 'sonnet' },
+  { name: 'task-2', prompt: 'Build signup page', model: 'sonnet' },
+]);
+
+// Send follow-ups
+const r1 = await mgr.send('task-1', 'Add form validation');
+const r2 = await mgr.send('task-2', 'Add password strength meter');
+
+console.log(r1.text); // The response
+console.log(r1.cost); // Cost in USD
+
+mgr.stopAll();
+```
+
+## Forking Sessions
+
+Fork creates a new session that starts with all the parent's conversation context:
+
+```bash
+# Original session
+cms spawn --name approach-a --prompt "Implement auth with sessions"
+cms send --name approach-a --message "Add login endpoint"
+
+# Fork to try a different approach (keeps all context from approach-a)
+cms fork --name approach-a --new-name approach-b --message "Actually, use JWT instead"
+
+# Now both sessions exist independently
+cms send --name approach-a --message "Add session storage"
+cms send --name approach-b --message "Add token refresh"
+```
+
+## Delegate (Control Loop + Safety Net)
+
+The `delegate` system gives the parent Claude (or any automation) human-like control over child sessions:
+
+1. **Spawns** a session with the right permissions
+2. **Sends** the task
+3. **Monitors** for issues (permission denials, cost overruns, turn limits)
+4. **Auto-handles** permission retries
+5. **Returns** structured output for the parent to evaluate
+6. **Accepts** follow-up corrections via `continue`
+
+### CLI Usage
+
+```bash
+# Delegate a task with a $1 budget limit
+cms delegate --name fix-bug --task "Fix the auth bug in auth.service.ts" --max-cost 1.00
+
+# Delegate with read-only mode (no file edits allowed)
+cms delegate --name review --task "Review code quality of src/" --preset read-only
+
+# Get structured JSON output (for programmatic use)
+cms delegate --name task-1 --task "Count all TypeScript files" --model haiku --json
+
+# Send follow-up corrections
+cms continue --name fix-bug --message "Also add input validation"
+
+# Full control with context and custom limits
+cms delegate --name big-refactor --task "Refactor the auth module" \
+  --model opus --preset full --max-cost 5.00 --max-turns 100 \
+  --context "Use JWT tokens, not sessions"
+
+# Disable safety net entirely (no cost/turn/path limits)
+cms delegate --name trusted-task --task "Build the feature" --no-safety
+```
+
+### Permission Presets
+
+| Preset | Permission Mode | Description |
+|--------|----------------|-------------|
+| `read-only` | default | Can search and read files only |
+| `review` | default | Same as read-only (code review) |
+| `edit` | acceptEdits | Can read and edit files (default) |
+| `full` | bypassPermissions | Full access (use with caution) |
+| `plan` | plan | Explore only, no execution |
+
+### Safety Net
+
+Every delegated session has automatic safety limits:
+
+- **Cost limit** — Auto-kills if cumulative cost exceeds threshold (default: $2.00)
+- **Turn limit** — Auto-kills if agent turns exceed threshold (default: 50)
+- **Time limit** — Timeout per interaction (default: 5 minutes)
+- **Protected paths** — Warns on modifications to `.env`, `.git/`, `node_modules/`, etc.
+
+### Structured Output (--json)
+
+When using `--json`, delegate returns machine-readable output:
+
+```json
+{
+  "status": "completed",
+  "response": "Fixed the auth bug by...",
+  "cost": 0.0342,
+  "turns": 5,
+  "duration": 12340,
+  "sessionId": "abc123",
+  "name": "fix-bug",
+  "canContinue": true,
+  "toolsUsed": ["Read", "Edit", "Grep"],
+  "safety": {
+    "totalViolations": 0,
+    "violations": [],
+    "limits": { "maxCostUsd": 1.00, "maxTurns": 50 }
+  },
+  "error": null
+}
+```
+
+**Status values:** `completed`, `needs_input`, `failed`, `cost_exceeded`, `turns_exceeded`
+
+### Programmatic Delegate API
+
+```javascript
+const { SessionManager, Delegate } = require('claude-multi-session');
+
+const mgr = new SessionManager();
+const delegate = new Delegate(mgr);
+
+// One-shot delegation
+const result = await delegate.run('fix-bug', {
+  task: 'Fix the authentication bug in auth.service.ts',
+  model: 'sonnet',
+  preset: 'edit',
+  maxCost: 1.00,
+  maxTurns: 30,
+});
+
+console.log(result.status);   // 'completed'
+console.log(result.response);  // What the session did
+console.log(result.cost);      // $0.0342
+
+// Disable safety net entirely
+const noSafety = await delegate.run('trusted', {
+  task: 'Build the whole feature',
+  safety: false,  // No cost/turn/path limits
+});
+
+// Multi-step with evaluation
+const r1 = await delegate.run('feature', { task: 'Build login page' });
+// Parent evaluates r1.response...
+const r2 = await delegate.continue('feature', 'Good, now add form validation');
+// Parent evaluates r2.response...
+const r3 = await delegate.continue('feature', 'Perfect. Now write tests.');
+delegate.finish('feature');
+```
+
+### SafetyNet Standalone
+
+```javascript
+const { SafetyNet, StreamSession } = require('claude-multi-session');
+
+const safety = new SafetyNet({
+  maxCostUsd: 0.50,
+  maxTurns: 20,
+  protectedPaths: ['.env', 'credentials/', '.git/'],
+});
+
+const session = new StreamSession({ name: 'task', model: 'haiku' });
+session.start();
+safety.attach(session);
+
+// Safety net monitors all interactions
+safety.on('violation', (v) => console.log('VIOLATION:', v.message));
+safety.on('kill', (v) => console.log('SESSION KILLED:', v.message));
+
+await session.send('Do something');
+```
+
+## Options
+
+### spawn
+```
+--name <name>              Session name (required)
+--prompt <text>            Initial prompt (required)
+--model <model>            Model: sonnet, opus, haiku (default: sonnet)
+--stop                     Stop after first response (one-shot mode)
+--work-dir <path>          Working directory for claude
+--permission-mode <mode>   Permission mode: default, acceptEdits, bypassPermissions
+--allowed-tools <t1,t2>    Restrict available tools
+--system-prompt <text>     Append to system prompt
+--max-budget <usd>         Max budget in USD
+--agent <name>             Use a specific agent
+```
+
+### send
+```
+--name <name>              Session name (required)
+--message <text>           Message to send (required)
+--stop                     Stop session after response
+```
+
+### delegate
+```
+--name <name>              Session name (required)
+--task <text>              Task description (required)
+--model <model>            Model: sonnet, opus, haiku (default: sonnet)
+--preset <preset>          Permission preset (default: edit)
+--max-cost <usd>           Max cost in USD (default: 2.00)
+--max-turns <n>            Max agent turns (default: 50)
+--no-safety                Disable safety net entirely (no cost/turn/path limits)
+--context <text>           Extra context to prepend to the task
+--work-dir <path>          Working directory
+--system-prompt <text>     Append to system prompt
+--agent <name>             Use a specific agent
+--json                     Output structured JSON
+```
+
+### continue
+```
+--name <name>              Session name (required)
+--message <text>           Follow-up message (required)
+--json                     Output structured JSON
+```
+
+## Programmatic API
+
+```javascript
+const { SessionManager, StreamSession } = require('claude-multi-session');
+
+// High-level API (recommended)
+const mgr = new SessionManager({
+  defaultModel: 'sonnet',
+  defaultPermissionMode: 'default',
+});
+
+const { session, response } = await mgr.spawn('my-task', {
+  prompt: 'Fix the auth bug',
+  model: 'sonnet',
+  workDir: '/path/to/project',
+});
+
+const r2 = await mgr.send('my-task', 'Add tests');
+mgr.stop('my-task');
+
+// Low-level API (single session)
+const session = new StreamSession({
+  name: 'direct',
+  model: 'haiku',
+});
+session.start();
+const r1 = await session.send('Hello');
+const r2 = await session.send('Follow up');
+session.stop();
+```
+
+### Events
+
+```javascript
+session.on('text', (text) => { /* partial text chunks */ });
+session.on('tool-use', ({ name, input }) => { /* tool calls */ });
+session.on('result', (response) => { /* complete response */ });
+session.on('init', (data) => { /* session initialized */ });
+session.on('error', (err) => { /* error occurred */ });
+session.on('close', (code) => { /* process exited */ });
+```
+
+## Cost Tracking
+
+Every interaction tracks cost:
+
+```bash
+cms status --name my-task
+# Shows: total cost, turns, interactions
+
+cms history --name my-task
+# Shows: cost per interaction
+```
+
+## Data Storage
+
+Session data is stored in `~/.claude-multi-session/`:
+- `sessions.json` — Session metadata, history, and config
+
+Clean up old sessions:
+```bash
+cms cleanup --days 7
+```
+
+## MCP Server (Claude Code Native Integration)
+
+The MCP server exposes all multi-session tools as **native Claude Code tools**. Instead of running CLI commands via Bash, Claude calls tools directly — just like Read, Edit, or Grep.
+
+### Setup
+
+**Automatic (recommended):**
+```bash
+cms setup
+```
+This interactive wizard registers the MCP server for you. See [Quick Setup](#quick-setup-mcp-integration) above.
+
+**Manual — Option 1: Global install**
+```bash
+npm install -g claude-multi-session
+```
+
+Add to your Claude Code MCP config (`~/.claude/settings.json` or project `.claude/settings.json`):
+```json
+{
+  "mcpServers": {
+    "multi-session": {
+      "command": "cms-mcp"
+    }
+  }
+}
+```
+
+**Manual — Option 2: Local (no install)**
+```json
+{
+  "mcpServers": {
+    "multi-session": {
+      "command": "node",
+      "args": ["/absolute/path/to/claude-multi-session/bin/mcp.js"]
+    }
+  }
+}
+```
+
+### Available MCP Tools
+
+Once configured, Claude sees these tools:
+
+**Session Management:**
+| Tool | Description |
+|------|-------------|
+| `spawn_session` | Start a new session |
+| `send_message` | Send message (auto-resumes if stopped) |
+| `resume_session` | Resume a stopped session |
+| `pause_session` | Pause a session |
+| `fork_session` | Fork into a new session |
+| `stop_session` | Gracefully stop |
+| `kill_session` | Force kill |
+
+**Information:**
+| Tool | Description |
+|------|-------------|
+| `get_session_status` | Detailed session info |
+| `get_last_output` | Last response text |
+| `list_sessions` | List all sessions |
+| `get_history` | Full interaction history |
+| `delete_session` | Permanently delete |
+
+**Delegate (Control Loop + Safety):**
+| Tool | Description |
+|------|-------------|
+| `delegate_task` | Smart delegation with safety limits |
+| `continue_task` | Send corrections to a delegated task |
+| `finish_task` | Finish a task cleanly |
+| `abort_task` | Emergency abort |
+
+**Batch:**
+| Tool | Description |
+|------|-------------|
+| `batch_spawn` | Spawn multiple sessions in parallel |
+
+### How Claude Uses It
+
+With MCP configured, Claude can autonomously:
+
+```
+User: "Build auth with login, signup, and password reset"
+
+Claude thinks: "This has 3 independent parts. I'll delegate in parallel."
+
+Claude calls:
+  → delegate_task(name="auth-login", task="Build login with JWT", model="sonnet")
+  → delegate_task(name="auth-signup", task="Build signup with validation", model="sonnet")
+  → delegate_task(name="auth-reset", task="Build password reset with email", model="sonnet")
+
+Claude reads results, notices signup is missing email validation...
+
+Claude calls:
+  → continue_task(name="auth-signup", message="Add email format validation")
+
+All good now. Claude calls:
+  → finish_task(name="auth-login")
+  → finish_task(name="auth-signup")
+  → finish_task(name="auth-reset")
+
+Claude: "Done! All 3 auth features implemented."
+```
+
+### Strategy Guide
+
+See `STRATEGY.md` for the complete guide on:
+- When to delegate vs do it yourself
+- How to decompose tasks
+- Model selection (haiku/sonnet/opus)
+- Budget allocation
+- The correction loop pattern
+- Parallel coordination
+
+## Requirements
+
+- **Node.js** >= 18
+- **Claude Code CLI** installed and authenticated
+- Zero npm dependencies
+
+## License
+
+MIT