nightshift-mcp 2.1.1 → 2.1.3

package/README.md

@@ -1,383 +1,364 @@
-# NightShift MCP
-
-**Multi-agent orchestration across AI models. The responsible kind of multi-agent chaos.**
-
-An [MCP](https://modelcontextprotocol.io/) server that coordinates Claude, Codex, Gemini, Vibe, Goose, and local Ollama models as an agentic team. Structured delegation, shared task management, autonomous workflows, and production-grade reliability features. Works with any MCP-compatible client.
-
-## Quick Start
-
-```bash
-# Install
-npm install -g nightshift-mcp
-
-# Configure for Claude Code (~/.claude.json)
-{
-  "mcpServers": {
-    "nightshift": { "command": "nightshift-mcp", "args": [] }
-  }
-}
-
-# Configure for Codex (~/.codex/config.toml)
-[mcp_servers.nightshift]
-command = "nightshift-mcp"
-args = []
-```
-
-All agents must run in the **same project directory** to share coordination state.
-
-```bash
-# Terminal 1              # Terminal 2
-cd ~/myproject            cd ~/myproject
-claude                    codex
-```
-
-## Features
-
-### Orchestration
-- **Agent spawning**: Spawn Claude, Codex, Gemini, Vibe, Goose, or Ollama as subprocesses with full lifecycle tracking
-- **Autonomous mode**: Single `orchestrate` tool runs claim-implement-complete loops until all stories pass
-- **Daemon mode**: Event-driven background orchestrator with file watchers, health checks, and auto-recovery
-- **Delegation**: Hand off stories or research tasks to specific agents with full context injection
-- **Failover handling**: Seamless handoffs when an agent hits rate limits or context windows
-
-### Reliability
-- **Health tracker**: Per-agent failure tracking. Auto-disables failing agents, re-enables after configurable cooldown. Persisted across daemon restarts.
-- **Immutable audit trail**: Append-only SQLite table records every spawn, completion, failure, and stuck-agent kill
-- **Run records**: Structured execution history per agent run — duration, exit status, files changed, scope leak detection
-- **Budget tracking**: Per-agent cost tracking with daily/monthly limits, warning thresholds, enable/disable toggle
-- **Autoresearch**: Built-in analytics queries — agent success rates, average duration, scope leak rates
-
-### New in 2.1
-- **Runtime project switching**: `set_project_path` tool + optional `projectPath` param on all tools. No more restarting the MCP server to switch projects.
-- **Token tracking**: Parses token usage from Codex, Ollama, Gemini, and Claude output. Every `spawn_agent` call logs to `.robot-chat/runs.jsonl`.
-- **Run log + stats**: Structured JSONL log per spawn. `get_run_stats` tool for aggregate tokens per agent, avg durations, rate limit counts.
-- **Rate limit detection**: Parses 429s, "quota exceeded", retry-after from agent output. Returns structured `rate_limited` status.
-- **Agent role tagging**: `role` param on `spawn_agent`, `delegate_story` — planner, coder, fixer, verifier, etc. Shows in run log and chat.
-- **Configurable pipelines**: Define multi-step agent pipelines (e.g., Gemini plans → Codex implements → Claude verifies). Tag-based routing. `get_pipeline` / `set_pipeline` tools.
-- **Tool usage tracking**: Parses which tools agents used (Read, Edit, Bash, exec, shell commands) from output.
-
-### Task Management
-- **PRD-driven workflow**: User stories in `prd.json` with priorities, dependencies (`dependsOn`), and tags for routing
-- **Bug tracking**: `bugs.json` for post-testing feedback loops
-- **Savepoints**: Git-based checkpoints (or JSON fallback) with rollback support
-- **Progress tracking**: Shared learnings via `progress.txt`
-
-### Communication
-- **Multi-agent chat**: Structured messaging via `.robot-chat/chat.txt` with agent name, timestamp, and message type
-- **Context store**: Topic-based context retrieval — agents store and query learnings instead of prompt-stuffing
-- **Execution tracing**: Parent-child trace trees for debugging multi-agent runs
-
-### Platform
-- **Cross-platform**: Windows, Linux, macOS
-- **6 agent types**: Claude, Codex, Gemini, Vibe, Goose, Ollama
-- **52 MCP tools** across 10 categories
-- **NightShift CLI**: `nightshift` command for agent coordination without MCP
-- **Zero external services**: Everything runs locally with SQLite + file storage
-
-## What's New in 2.1
-
-- **Runtime project switching**: `set_project_path` tool changes the active project without restarting. All PRD, chat, bug, and progress tools also accept an optional `projectPath` param for per-call overrides.
-- **Token tracking + run log**: Every `spawn_agent` call (foreground and background) appends to `.robot-chat/runs.jsonl` with agent, role, duration, tokens, rate limit info, and tools used. `get_run_stats` tool returns aggregate analytics.
-- **Configurable pipelines**: Define agent pipelines via `nightshift.config.json` or `set_pipeline` tool. 5 built-in pipelines (default, frontend, backend, research, quick) with tag-based routing. Pipelines execute in the daemon and orchestrator — earlier steps capture output as context for later steps.
-- **Agent role tagging**: `role` param on spawn/delegate tools. Feeds run log and chat messages.
-- **Rate limit detection**: Parses 429, quota exhausted, retry-after from agent output.
-- **Health tracker rename**: "circuit breaker" → "health tracker" in all user-facing names.
-
-### What was in 2.0
-- SQLite foundation (`.robot-chat/nightshift.db`) with ACID transactions and WAL mode
-- Health tracker (per-agent failure tracking with auto-disable/re-enable)
-- Immutable audit trail, run records, budget tracking, autoresearch queries
-- MCP SDK 1.28.0, zero production vulnerabilities
-
-## Architecture
-
-```
-┌───────────────────────────────────────────────────────────┐
-│                    NightShift MCP                          │
-├───────────────────────────────────────────────────────────┤
-│                                                           │
-│  ┌────────┐ ┌────────┐ ┌────────┐ ┌──────┐ ┌──────────┐ │
-│  │ Claude │ │ Codex  │ │ Gemini │ │ Vibe │ │Goose/Olla│ │
-│  └───┬────┘ └───┬────┘ └───┬────┘ └──┬───┘ └────┬─────┘ │
-│      └──────────┴─────┬─────┴─────────┴──────────┘       │
-│                       ▼                                   │
-│            ┌─────────────────────┐                        │
-│            │   .robot-chat/      │                        │
-│            │                     │                        │
-│            │  chat.txt     (msg) │                        │
-│            │  nightshift.db (v2) │                        │
-│            │  workflow.json      │                        │
-│            │  trace.json         │                        │
-│            │  context/           │                        │
-│            └─────────────────────┘                        │
-│                       │                                   │
-│      ┌────────────────┼────────────────┐                  │
-│      ▼                ▼                ▼                  │
-│  ┌────────┐    ┌────────────┐    ┌──────────┐            │
-│  │prd.json│    │ nightshift │    │progress  │            │
-│  │(stories│    │    .db     │    │  .txt    │            │
-│  │ + bugs)│    │ (audit,    │    │(learnings│            │
-│  │        │    │  budget,   │    │ patterns)│            │
-│  │        │    │  runs,     │    │          │            │
-│  │        │    │  circuits) │    │          │            │
-│  └────────┘    └────────────┘    └──────────┘            │
-│                                                           │
-└───────────────────────────────────────────────────────────┘
-```
-
-## Usage Patterns
-
-### Fully autonomous
-```
-orchestrate(agent: "Claude", mode: "all")
-```
-
-### Parallel delegation
-```
-delegate_story(agent: "codex", storyId: "US-001", background: true)
-delegate_story(agent: "gemini", storyId: "US-002", background: true)
-```
-
-### Research then implement
-```
-delegate_research(task: "Analyze auth patterns and recommend approach")
-delegate_story(agent: "codex", storyId: "US-001")
-```
-
-### Pipeline (multi-step)
-```
-set_pipeline(name: "default", steps: [
-  { agent: "gemini", role: "planner" },
-  { agent: "codex", role: "implementer" },
-  { agent: "claude", role: "verifier" }
-])
-orchestrate()
-```
-
-### Daemon (hands-off)
-```bash
-nightshift-daemon --verbose --max-agents 4
-```
-
-## PRD Setup
-
-Create `prd.json` in your project root:
-
-```json
-{
-  "project": "MyApp",
-  "userStories": [
-    {
-      "id": "US-001",
-      "title": "Set up project structure",
-      "acceptanceCriteria": ["Add routes", "Create base components"],
-      "priority": 1,
-      "passes": false
-    },
-    {
-      "id": "US-002",
-      "title": "Add database schema",
-      "priority": 2,
-      "passes": false,
-      "dependsOn": ["US-001"],
-      "tags": ["code", "infrastructure"]
-    }
-  ]
-}
-```
-
-### Story fields
-
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `id` | string | yes | — | Unique ID (e.g., "US-001") |
-| `title` | string | yes | — | Short title |
-| `description` | string | no | "" | Detailed description |
-| `acceptanceCriteria` | string[] | no | [] | Completion criteria |
-| `priority` | number | no | 999 | Lower = higher priority |
-| `passes` | boolean | no | false | Whether complete |
-| `dependsOn` | string[] | no | — | Story IDs that must complete first |
-| `tags` | string[] | no | — | Routing hints (e.g., `["code"]`, `["research"]`) |
-
-Tags influence agent routing: `research`/`planning` prefers Gemini/Claude, `code`/`implementation` prefers Codex/Claude.
-
-## Bug Tracking
-
-Add `bugs.json` when testing reveals issues:
-
-```json
-{
-  "project": "MyApp",
-  "bugs": [
-    {
-      "id": "BUG-001",
-      "title": "Login fails on mobile",
-      "description": "Login button unresponsive on iOS Safari",
-      "priority": 1,
-      "fixed": false
-    }
-  ]
-}
-```
-
-When all stories pass and all bugs are fixed, NightShift posts `READY_TO_TEST` to the chat.
-
-## Tools Reference
-
-NightShift provides 52 tools across 10 categories. Key tools listed below — use `nightshift_setup(showExamples: true)` or `nightshift_help` for full documentation.
-
-### Communication
-| Tool | Description |
-|------|-------------|
-| `read_robot_chat` | Read recent messages (filter by agent, type, limit) |
-| `write_robot_chat` | Post a message (STATUS_UPDATE, QUESTION, ERROR, etc.) |
-| `check_failovers` | Find unclaimed failover requests |
-| `claim_failover` | Take over work from a stuck agent |
-| `list_agents` | See who's active with activity stats |
-| `watch_chat` | Cursor-based polling for new messages |
-
-### Task Management
-| Tool | Description |
-|------|-------------|
-| `read_prd` | Read PRD with completion summary |
-| `get_next_story` | Get highest priority incomplete story |
-| `claim_story` | Claim a story and notify via chat |
-| `complete_story` | Mark done, log progress, create savepoint |
-| `read_bugs` / `claim_bug` / `mark_bug_fixed` | Bug lifecycle |
-
-### Agent Spawning
-| Tool | Description |
-|------|-------------|
-| `list_available_agents` | Check which CLIs are installed and runnable |
-| `spawn_agent` | Spawn agent, wait for completion (sync) |
-| `spawn_agent_background` | Spawn agent, return immediately (async) |
-| `delegate_story` | Delegate a story with full context injection |
-| `delegate_research` | Delegate research/analysis task |
-| `get_run_stats` | Token usage, durations, rate limits from run log |
-
-### Orchestration & Pipelines
-| Tool | Description |
-|------|-------------|
-| `orchestrate` | Autonomous claim-implement-complete loop |
-| `get_agent_status` | Check background agent by PID |
-| `list_running_agents` | All spawned agents with status |
-| `set_project_path` | Switch active project at runtime |
-| `get_pipeline` | View configured pipelines and tag routing |
-| `set_pipeline` | Create/update agent pipelines at runtime |
-
-### Workflow
-| Tool | Description |
-|------|-------------|
-| `init_workflow` | Initialize with project goal and phases |
-| `advance_phase` / `set_phase` | Phase management |
-| `record_decision` | Record strategic decisions with rationale |
-
-### Context & Tracing
-| Tool | Description |
-|------|-------------|
-| `store_context` / `query_context` | Topic-based context store |
-| `get_trace` | Execution trace (flat or tree view) |
-
-### Recovery
-| Tool | Description |
-|------|-------------|
-| `create_savepoint` | Manual git checkpoint |
-| `list_savepoints` | List all savepoints |
-| `rollback_savepoint` | Reset to a previous savepoint |
-
-### Setup
-| Tool | Description |
-|------|-------------|
-| `nightshift_setup` | Configuration check and templates |
-| `nightshift_debug` | Diagnostic report with suggested fixes |
-
-## Daemon
-
-The daemon provides hands-off, event-driven orchestration:
-
-```bash
-nightshift-daemon [options]
-```
-
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--verbose, -v` | false | Debug logging |
-| `--dry-run` | false | Preview without spawning |
-| `--health-check <N>` | 2m | Health check interval |
-| `--max-agents <N>` | 3 | Max concurrent agents |
-
-**What it does:**
-- Watches `prd.json` and `chat.txt` for changes
-- Auto-spawns agents for unassigned stories
-- Health tracker disables failing agents, re-enables after cooldown
-- Detects and kills stuck agents
-- Claims failover requests
-- Quarantines stories that fail repeatedly
-- Logs everything to the SQLite audit trail
-
-## Local Models
-
-### Goose + Ollama (recommended)
-
-```bash
-export NIGHTSHIFT_GOOSE_PROVIDER=ollama
-export NIGHTSHIFT_GOOSE_MODEL=qwen3.5:4b
-```
-
-```
-spawn_agent(agent: "goose", prompt: "Fix the pagination bug")
-```
-
-### Direct Ollama (text only)
-
-```bash
-export NIGHTSHIFT_OLLAMA_MODEL=qwen3.5:4b
-```
-
-```
-spawn_agent(agent: "ollama", prompt: "Review this PR")
-```
-
-| GPU VRAM | Model | Size |
-|----------|-------|------|
-| 4GB+ | `qwen3.5:4b` | 3.4 GB |
-| 6GB+ | `qwen3.5:4b-q8_0` | 5.3 GB |
-| 8GB+ | `qwen3.5:9b` | 6.6 GB |
-
-## Data Storage
-
-NightShift uses a hybrid storage approach:
-
-| Data | Storage | Format |
-|------|---------|--------|
-| Agent chat | `.robot-chat/chat.txt` | Human-readable text |
-| PRD / stories | `prd.json` | JSON |
-| Bugs | `bugs.json` | JSON |
-| Progress | `progress.txt` | Append-only text |
-| Workflow | `.robot-chat/workflow.json` | JSON with file locking |
-| Trace | `.robot-chat/trace.json` | JSON |
-| Context | `.robot-chat/context/*.json` | Per-topic JSON files |
-| **Audit trail** | `.robot-chat/nightshift.db` | SQLite (immutable) |
-| **Run records** | `.robot-chat/nightshift.db` | SQLite |
-| **Budget** | `.robot-chat/nightshift.db` | SQLite |
-| **Health tracker** | `.robot-chat/nightshift.db` | SQLite |
-| **Run log** | `.robot-chat/runs.jsonl` | JSONL (append-only) |
-| **Pipeline config** | `.robot-chat/pipeline-override.json` | JSON (runtime) |
-
-Add `.robot-chat/` to your `.gitignore` — coordination state is ephemeral.
-
-## Development
-
-```bash
-git clone https://gitlab.com/Pike1868/nightshift-mcp.git
-cd nightshift-mcp
-npm install
-npm run build
-npm test          # 113 tests
-npm run dev       # watch mode
-npm link          # global CLI access
-```
-
-## License
-
-MIT
+# NightShift MCP
+
+**Multi-agent orchestration across AI models. The responsible kind of multi-agent chaos.**
+
+An [MCP](https://modelcontextprotocol.io/) server that coordinates Claude, Codex, Gemini, Vibe, Goose, and local Ollama models as an agentic team. Structured delegation, shared task management, autonomous workflows, and production-grade reliability features. Works with any MCP-compatible client.
+
+## Quick Start
+
+```bash
+# Install
+npm install -g nightshift-mcp
+
+# Configure for Claude Code (~/.claude.json)
+{
+  "mcpServers": {
+    "nightshift": { "command": "nightshift-mcp", "args": [] }
+  }
+}
+
+# Configure for Codex (~/.codex/config.toml)
+[mcp_servers.nightshift]
+command = "nightshift-mcp"
+args = []
+```
+
+All agents must run in the **same project directory** to share coordination state.
+
+```bash
+# Terminal 1              # Terminal 2
+cd ~/myproject            cd ~/myproject
+claude                    codex
+```
+
+## Features
+
+### Orchestration
+- **Agent spawning**: Spawn Claude, Codex, Gemini, Vibe, Goose, or Ollama as subprocesses with full lifecycle tracking
+- **Autonomous mode**: Single `orchestrate` tool runs claim-implement-complete loops until all stories pass
+- **Daemon mode**: Event-driven background orchestrator with file watchers, health checks, and auto-recovery
+- **Delegation**: Hand off stories or research tasks to specific agents with full context injection
+- **Failover handling**: Seamless handoffs when an agent hits rate limits or context windows
+- **Runtime project switching**: Switch active project without restarting the MCP server
+
+### Reliability
+- **Health tracker**: Per-agent failure tracking. Auto-disables failing agents, re-enables after configurable cooldown. Persisted across daemon restarts.
+- **Immutable audit trail**: Append-only SQLite table records every spawn, completion, failure, and stuck-agent kill
+- **Run records**: Structured execution history per agent run — duration, exit status, files changed, scope leak detection
+- **Budget tracking**: Per-agent cost tracking with daily/monthly limits, warning thresholds, enable/disable toggle
+- **Autoresearch**: Built-in analytics queries — agent success rates, average duration, scope leak rates
+
+### Observability
+- **Token tracking**: Parses token usage from agent output. Every `spawn_agent` call logs to `.robot-chat/runs.jsonl`.
+- **Run log + stats**: Structured JSONL log per spawn. `get_run_stats` for aggregate tokens per agent, avg durations, rate limit counts.
+- **Rate limit detection**: Parses 429s, "quota exceeded", retry-after from agent output. Returns structured `rate_limited` status.
+- **Agent role tagging**: `role` param on `spawn_agent`, `delegate_story` — planner, coder, fixer, verifier, etc.
+- **Configurable pipelines**: Define multi-step agent pipelines with tag-based routing. `get_pipeline` / `set_pipeline` tools.
+- **Tool usage tracking**: Parses which tools agents used from output.
+
+### Task Management
+- **PRD-driven workflow**: User stories in `prd.json` with priorities, dependencies (`dependsOn`), and tags for routing
+- **Bug tracking**: `bugs.json` for post-testing feedback loops
+- **Savepoints**: Git-based checkpoints (or JSON fallback) with rollback support
+- **Progress tracking**: Shared learnings via `progress.txt`
+
+### Communication
+- **Multi-agent chat**: Structured messaging via `.robot-chat/chat.txt` with agent name, timestamp, and message type
+- **Context store**: Topic-based context retrieval — agents store and query learnings instead of prompt-stuffing
+- **Execution tracing**: Parent-child trace trees for debugging multi-agent runs
+
+### Platform
+- **Cross-platform**: Windows, Linux, macOS
+- **6 agent types**: Claude, Codex, Gemini, Vibe, Goose, Ollama
+- **52 MCP tools** across 10 categories
+- **NightShift CLI**: `nightshift` command for agent coordination without MCP
+- **Zero external services**: Everything runs locally with SQLite + file storage
+
+## Architecture
+
+```
+┌───────────────────────────────────────────────────────────┐
+│                    NightShift MCP                          │
+├───────────────────────────────────────────────────────────┤
+│                                                           │
+│  ┌────────┐ ┌────────┐ ┌────────┐ ┌──────┐ ┌──────────┐ │
+│  │ Claude │ │ Codex  │ │ Gemini │ │ Vibe │ │Goose/Olla│ │
+│  └───┬────┘ └───┬────┘ └───┬────┘ └──┬───┘ └────┬─────┘ │
+│      └──────────┴─────┬─────┴─────────┴──────────┘       │
+│                       ▼                                   │
+│            ┌─────────────────────┐                        │
+│            │   .robot-chat/      │                        │
+│            │                     │                        │
+│            │  chat.txt     (msg) │                        │
+│            │  nightshift.db (v2) │                        │
+│            │  workflow.json      │                        │
+│            │  trace.json         │                        │
+│            │  context/           │                        │
+│            └─────────────────────┘                        │
+│                       │                                   │
+│      ┌────────────────┼────────────────┐                  │
+│      ▼                ▼                ▼                  │
+│  ┌────────┐    ┌────────────┐    ┌──────────┐            │
+│  │prd.json│    │ nightshift │    │progress  │            │
+│  │(stories│    │    .db     │    │  .txt    │            │
+│  │ + bugs)│    │ (audit,    │    │(learnings│            │
+│  │        │    │  budget,   │    │ patterns)│            │
+│  │        │    │  runs,     │    │          │            │
+│  │        │    │  circuits) │    │          │            │
+│  └────────┘    └────────────┘    └──────────┘            │
+│                                                           │
+└───────────────────────────────────────────────────────────┘
+```
+
+## Usage Patterns
+
+### Fully autonomous
+```
+orchestrate()
+```
+
+### Parallel delegation
+```
+delegate_story(agent: "codex", storyId: "US-001", background: true)
+delegate_story(agent: "gemini", storyId: "US-002", background: true)
+```
+
+### Research then implement
+```
+delegate_research(task: "Analyze auth patterns and recommend approach")
+delegate_story(agent: "codex", storyId: "US-001")
+```
+
+### Pipeline (multi-step)
+```
+set_pipeline(name: "default", steps: [
+  { agent: "gemini", role: "planner" },
+  { agent: "codex", role: "implementer" },
+  { agent: "claude", role: "verifier" }
+])
+orchestrate()
+```
+
+### Daemon (hands-off)
+```bash
+nightshift-daemon --verbose --max-agents 4
+```
+
+## PRD Setup
+
+Create `prd.json` in your project root:
+
+```json
+{
+  "project": "MyApp",
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "Set up project structure",
+      "acceptanceCriteria": ["Add routes", "Create base components"],
+      "priority": 1,
+      "passes": false
+    },
+    {
+      "id": "US-002",
+      "title": "Add database schema",
+      "priority": 2,
+      "passes": false,
+      "dependsOn": ["US-001"],
+      "tags": ["code", "infrastructure"]
+    }
+  ]
+}
+```
+
+### Story fields
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `id` | string | yes | — | Unique ID (e.g., "US-001") |
+| `title` | string | yes | — | Short title |
+| `description` | string | no | "" | Detailed description |
+| `acceptanceCriteria` | string[] | no | [] | Completion criteria |
+| `priority` | number | no | 999 | Lower = higher priority |
+| `passes` | boolean | no | false | Whether complete |
+| `dependsOn` | string[] | no | — | Story IDs that must complete first |
+| `tags` | string[] | no | — | Routing hints (e.g., `["code"]`, `["research"]`) |
+
+Tags influence agent routing: `research`/`planning` prefers Gemini/Claude, `code`/`implementation` prefers Codex/Claude.
+
+## Bug Tracking
+
+Add `bugs.json` when testing reveals issues:
+
+```json
+{
+  "project": "MyApp",
+  "bugs": [
+    {
+      "id": "BUG-001",
+      "title": "Login fails on mobile",
+      "description": "Login button unresponsive on iOS Safari",
+      "priority": 1,
+      "fixed": false
+    }
+  ]
+}
+```
+
+When all stories pass and all bugs are fixed, NightShift posts `READY_TO_TEST` to the chat.
+
+## Tools Reference
+
+NightShift provides 52 tools across 10 categories. Key tools listed below — use `nightshift_setup(showExamples: true)` or `nightshift_help` for full documentation.
+
+### Communication
+| Tool | Description |
+|------|-------------|
+| `read_robot_chat` | Read recent messages (filter by agent, type, limit) |
+| `write_robot_chat` | Post a message (STATUS_UPDATE, QUESTION, ERROR, etc.) |
+| `check_failovers` | Find unclaimed failover requests |
+| `claim_failover` | Take over work from a stuck agent |
+| `list_agents` | See who's active with activity stats |
+| `watch_chat` | Cursor-based polling for new messages |
+
+### Task Management
+| Tool | Description |
+|------|-------------|
+| `read_prd` | Read PRD with completion summary |
+| `get_next_story` | Get highest priority incomplete story |
+| `claim_story` | Claim a story and notify via chat |
+| `complete_story` | Mark done, log progress, create savepoint |
+| `read_bugs` / `claim_bug` / `mark_bug_fixed` | Bug lifecycle |
+
+### Agent Spawning
+| Tool | Description |
+|------|-------------|
+| `list_available_agents` | Check which CLIs are installed and runnable |
+| `spawn_agent` | Spawn agent, wait for completion (sync) |
+| `spawn_agent_background` | Spawn agent, return immediately (async) |
+| `delegate_story` | Delegate a story with full context injection |
+| `delegate_research` | Delegate research/analysis task |
+| `get_run_stats` | Token usage, durations, rate limits from run log |
+
+### Orchestration & Pipelines
+| Tool | Description |
+|------|-------------|
+| `orchestrate` | Autonomous claim-implement-complete loop |
+| `get_agent_status` | Check background agent by PID |
+| `list_running_agents` | All spawned agents with status |
+| `set_project_path` | Switch active project at runtime |
+| `get_pipeline` | View configured pipelines and tag routing |
+| `set_pipeline` | Create/update agent pipelines at runtime |
+
+### Workflow
+| Tool | Description |
+|------|-------------|
+| `init_workflow` | Initialize with project goal and phases |
+| `advance_phase` / `set_phase` | Phase management |
+| `record_decision` | Record strategic decisions with rationale |
+
+### Context & Tracing
+| Tool | Description |
+|------|-------------|
+| `store_context` / `query_context` | Topic-based context store |
+| `get_trace` | Execution trace (flat or tree view) |
+
+### Recovery
+| Tool | Description |
+|------|-------------|
+| `create_savepoint` | Manual git checkpoint |
+| `list_savepoints` | List all savepoints |
+| `rollback_savepoint` | Reset to a previous savepoint |
+
+### Setup
+| Tool | Description |
+|------|-------------|
+| `nightshift_setup` | Configuration check and templates |
+| `nightshift_debug` | Diagnostic report with suggested fixes |
+
+## Daemon
+
+The daemon provides hands-off, event-driven orchestration:
+
+```bash
+nightshift-daemon [options]
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--verbose, -v` | false | Debug logging |
+| `--dry-run` | false | Preview without spawning |
+| `--health-check <N>` | 2m | Health check interval |
+| `--max-agents <N>` | 3 | Max concurrent agents |
+
+**What it does:**
+- Watches `prd.json` and `chat.txt` for changes
+- Auto-spawns agents for unassigned stories
+- Health tracker disables failing agents, re-enables after cooldown
+- Detects and kills stuck agents
+- Claims failover requests
+- Quarantines stories that fail repeatedly
+- Logs everything to the SQLite audit trail
+
+## Local Models
+
+NightShift supports local models via [Goose](https://github.com/block/goose) + Ollama or direct Ollama integration.
+
+### Goose + Ollama
+
+```bash
+export NIGHTSHIFT_GOOSE_PROVIDER=ollama
+export NIGHTSHIFT_GOOSE_MODEL=<your-model>
+```
+
+```
+spawn_agent(agent: "goose", prompt: "Fix the pagination bug")
+```
+
+### Direct Ollama
+
+```bash
+export NIGHTSHIFT_OLLAMA_MODEL=<your-model>
+```
+
+```
+spawn_agent(agent: "ollama", prompt: "Review this PR")
+```
+
+Any Ollama-compatible model works. Choose a model that fits your available resources.
+
+## Data Storage
+
+NightShift uses a hybrid storage approach:
+
+| Data | Storage | Format |
+|------|---------|--------|
+| Agent chat | `.robot-chat/chat.txt` | Human-readable text |
+| PRD / stories | `prd.json` | JSON |
+| Bugs | `bugs.json` | JSON |
+| Progress | `progress.txt` | Append-only text |
+| Workflow | `.robot-chat/workflow.json` | JSON with file locking |
+| Trace | `.robot-chat/trace.json` | JSON |
+| Context | `.robot-chat/context/*.json` | Per-topic JSON files |
+| **Audit trail** | `.robot-chat/nightshift.db` | SQLite (immutable) |
+| **Run records** | `.robot-chat/nightshift.db` | SQLite |
+| **Budget** | `.robot-chat/nightshift.db` | SQLite |
+| **Health tracker** | `.robot-chat/nightshift.db` | SQLite |
+| **Run log** | `.robot-chat/runs.jsonl` | JSONL (append-only) |
+| **Pipeline config** | `.robot-chat/pipeline-override.json` | JSON (runtime) |
+
+Add `.robot-chat/` to your `.gitignore` — coordination state is ephemeral.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test          # run test suite
+npm run dev       # watch mode
+npm link          # global CLI access
+```
+
+## License
+
+MIT