nightshift-mcp 1.1.2 → 2.0.1

package/README.md

@@ -1,971 +1,352 @@
-# NightShift MCP
-
-**The responsible kind of multi-agent chaos.**
-
-Explicit delegation, review, and handoffs between AI models.
-
----
-
-An MCP (Model Context Protocol) server for agent teams and multi-agent orchestration across different AI models. Coordinate Claude, Codex, Gemini, Goose, and local Ollama models as an agentic team — with structured delegation, shared task management, and autonomous workflows. Works with any MCP-compatible client.
-
-## Features
-
-- **Multi-agent chat**: Structured inter-agent messaging with agent name, timestamp, type, and content
-- **Failover handling**: Seamless handoffs when an agent hits limits or context windows fill up
-- **PRD-driven task management**: Work through user stories in prd.json with dependencies (`dependsOn`) and tags for smart routing
-- **Progress tracking**: Shared learnings via progress.txt
-- **Selective context retrieval**: Topic-based context store lets agents query relevant context instead of prompt-stuffing
-- **Execution tracing**: Structured trace of agent spawns, completions, and failures with parent-child tree visualization
-- **Agent spawning & orchestration**: Spawn Claude, Codex, Gemini, Goose, or local Ollama models as subprocesses with full lifecycle tracking
-- **Agent availability checks**: Pre-flight validation before spawning — never fails silently on missing agents
-- **Local model support**: Use Goose + Ollama for free, private, offline agent work with local models
-- **Autonomous orchestration**: Single `orchestrate` tool runs a claim→implement→complete loop until all stories pass
-- **Agent status tracking**: Monitor spawned agents by PID, check exit codes, and tail output in real-time
-- **Smart retry**: Automatically suggests or uses a different agent when one fails
-- **Workflow management**: Phases, strategic decisions, and agent assignments
-- **Watch/polling**: Monitor for new messages with cursor-based polling
-- **Auto-archiving**: Archive old messages to keep the chat file manageable
-- **Cross-platform**: Works on Windows, Linux, and macOS (uses cross-spawn and platform-safe process management)
-- **Heterogeneous agent teams**: Mix different AI models — use each for what it's best at
-- **Universal compatibility**: Works with any MCP-supporting tool (49 tools across 10 categories)
-- **Flexible savepoints**: Git-based checkpoints when available, JSON state snapshots when not
-- **Simple file-based storage**: No external services required
-
-## What's New in 1.1.0
-
-- **Local model support**: New `ollama` agent type + Goose/Ollama integration for local model tool use
-- **Agent availability checks**: All spawn/delegate tools validate agents before attempting — clear errors with available alternatives
-- **PRD dependencies**: `dependsOn` field prevents stories from running before their prerequisites complete
-- **PRD tags**: `tags` field enables smart agent routing (e.g., `["code"]` routes to codex, `["research"]` routes to gemini)
-- **Optional savepoints**: Works without git — falls back to JSON state snapshots
-- **Persistent agent tracking**: Agent registry survives restarts (`.robot-chat/agent-registry.json`)
-- **Flexible workflow phases**: Custom phase names beyond the built-in set
-- **Benchmark suite**: Test local model tool-use reliability (`benchmarks/run-experiment.mjs`)
-
-## Installation
-
-**Via npm (recommended):**
-```bash
-npm install -g nightshift-mcp
-```
-
-**Updating:**
-```bash
-npm update -g nightshift-mcp
-```
-
-**Or build from source:**
-```bash
-git clone <repo-url>
-cd nightshift-mcp
-npm install
-npm run build
-npm link  # makes 'nightshift-mcp' available globally
-```
-
-## Configuration
-
-### Claude Code (`~/.claude.json`)
-
-```json
-{
-  "mcpServers": {
-    "nightshift": {
-      "command": "nightshift-mcp",
-      "args": []
-    }
-  }
-}
-```
-
-### Codex (`~/.codex/config.toml`)
-
-```toml
-[mcp_servers.nightshift]
-command = "nightshift-mcp"
-args = []
-```
-
-The server automatically uses the current working directory for the `.robot-chat/` folder. You can override this with the `ROBOT_CHAT_PROJECT_PATH` environment variable if needed.
-
-## Usage
-
-For agents to communicate, they must be running in the **same project directory**. The chat file is created at `<project>/.robot-chat/chat.txt` based on where each CLI is started.
-
-**Example - two agents working on the same project:**
-
-```bash
-# Terminal 1
-cd ~/myproject
-claude
-
-# Terminal 2
-cd ~/myproject
-codex
-```
-
-Both agents now share the same chat file and can coordinate via the nightshift tools.
-
-**Note:** If agents are started in different directories, they will have separate chat files and won't be able to communicate.
-
-## Tools
-
-### `read_robot_chat`
-
-Read recent messages from the chat file.
-
-**Parameters:**
-- `limit` (optional): Maximum messages to return (default: 20)
-- `agent` (optional): Filter by agent name
-- `type` (optional): Filter by message type
-
-**Example:**
-```
-Read the last 10 messages from Claude
-```
-
-### `write_robot_chat`
-
-Write a message to the chat file.
-
-**Parameters:**
-- `agent` (required): Your agent name (e.g., "Claude", "Codex")
-- `type` (required): Message type
-- `content` (required): Message content
-
-**Message Types:**
-- `FAILOVER_NEEDED` - Request another agent to take over
-- `FAILOVER_CLAIMED` - Acknowledge taking over a task
-- `TASK_COMPLETE` - Mark a task as finished
-- `STATUS_UPDATE` - Share progress update
-- `HANDOFF` - Pass work to a specific agent
-- `INFO` - General information
-- `ERROR` - Error report
-- `QUESTION` - Ask other agents a question
-- `ANSWER` - Answer a question
-
-**Example:**
-```
-Post a STATUS_UPDATE from Claude about completing the login form
-```
-
-### `check_failovers`
-
-Find unclaimed FAILOVER_NEEDED messages.
-
-**Example:**
-```
-Check if any agent needs help with their task
-```
-
-### `claim_failover`
-
-Claim a failover request from another agent.
-
-**Parameters:**
-- `agent` (required): Your agent name
-- `originalAgent` (required): Agent who requested failover
-- `task` (optional): Task description
-
-**Example:**
-```
-Claim the failover from Codex and continue working on the authentication feature
-```
-
-### `get_chat_path`
-
-Get the full path to the chat file.
-
-### `list_agents`
-
-List all agents who have posted to the chat, with their activity stats.
-
-**Returns:**
-- Agent name
-- Last seen timestamp
-- Last message type
-- Total message count
-
-**Example:**
-```
-Show me which agents have been active in the chat
-```
-
-### `watch_chat`
-
-Poll for new messages since a cursor position. Useful for monitoring the chat for updates.
-
-**Parameters:**
-- `cursor` (optional): Line number from previous watch call. Omit to get current cursor.
-
-**Returns:**
-- `cursor`: Updated cursor for next call
-- `messageCount`: Number of new messages
-- `messages`: Array of new messages
-
-**Example workflow:**
-```
-1. Call watch_chat without cursor to get initial position
-2. Store the returned cursor value
-3. Call watch_chat with that cursor to get new messages
-4. Update your cursor with the returned value
-5. Repeat step 3-4 to poll for updates
-```
-
-### `archive_chat`
-
-Archive old messages to a date-stamped file, keeping recent messages in main chat.
-
-**Parameters:**
-- `keepRecent` (optional): Number of messages to keep (default: 50)
-
-**Example:**
-```
-Archive old messages, keeping the last 20
-```
-
-## Chat File Format
-
-Messages are stored in a human-readable format:
-
-```
-# Robot Chat - Multi-Agent Communication
-# Format: [AgentName @ HH:MM] MESSAGE_TYPE
-# ========================================
-
-[Claude @ 14:32] STATUS_UPDATE
-Working on implementing the login form.
-Files modified: src/components/LoginForm.tsx
-
-[Codex @ 14:45] FAILOVER_NEEDED
-Status: Hit rate limit
-Current Task: Implementing user authentication
-Progress: 60% - login form done, need logout and session handling
-Files Modified: src/auth/login.tsx, src/api/auth.ts
-
-Requesting another agent continue this work.
-
-[Claude @ 14:47] FAILOVER_CLAIMED
-Claiming failover from Codex.
-Continuing task: Implementing user authentication
-```
-
-## Testing
-
-### With MCP Inspector
-
-```bash
-npx @modelcontextprotocol/inspector node /path/to/nightshift-mcp/dist/index.js /tmp/test-project
-```
-
-### Manual Testing
-
-```bash
-# Set project path and run
-ROBOT_CHAT_PROJECT_PATH=/tmp/test-project node dist/index.js
-```
-
-## Development
-
-```bash
-# Watch mode for development
-npm run dev
-
-# Build
-npm run build
-```
-
-## Ralph-Style Task Management
-
-NightShift includes Ralph-compatible PRD and progress management, enabling structured autonomous development.
-
-### Setup
-
-1. Create a `prd.json` in your project root:
-
-```json
-{
-  "project": "MyApp",
-  "description": "Feature description",
-  "userStories": [
-    {
-      "id": "US-001",
-      "title": "Set up project structure",
-      "description": "Initialize the project with routing and base components",
-      "acceptanceCriteria": ["Add routes", "Create base components", "Typecheck passes"],
-      "priority": 1,
-      "passes": false,
-      "notes": "",
-      "tags": ["infrastructure"]
-    },
-    {
-      "id": "US-002",
-      "title": "Add database field",
-      "description": "As a developer, I need to store the new field",
-      "acceptanceCriteria": ["Add column to table", "Run migration", "Typecheck passes"],
-      "priority": 2,
-      "passes": false,
-      "notes": "",
-      "dependsOn": ["US-001"],
-      "tags": ["code", "infrastructure"]
-    }
-  ]
-}
-```
-
-### PRD Schema
-
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `project` | string | no | — | Project name |
-| `description` | string | no | "" | Project description |
-| **`userStories`** | array | **yes** | — | Array of user story objects |
-
-**User 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 | [] | Criteria for completion |
-| `priority` | number | no | 999 | Lower = higher priority |
-| `passes` | boolean | no | false | Whether the story is complete |
-| `notes` | string | no | "" | Implementation notes |
-| `dependsOn` | string[] | no | — | Story IDs that must complete first |
-| `tags` | string[] | no | — | Labels for routing (e.g., `["code", "security"]`) |
-
-**Tags and routing:** When the orchestrator uses `adaptive` strategy, tags influence which agent gets assigned:
-- `research`, `planning`, `documentation` → prefers gemini/claude
-- `code`, `implementation`, `feature` → prefers codex/claude
-- `security`, `architecture`, `infrastructure` → prefers claude
-
-### PRD Validation
-
-NightShift validates your `prd.json` with Zod schemas and provides helpful error messages when common mistakes are detected:
-
-- Using `stories` instead of `userStories` → suggests the correct field name
-- Using `acceptance_criteria` instead of `acceptanceCriteria` → suggests the correct field name
-- Missing required fields (`id`, `title`) → identifies which story has the issue
-- Optional fields default gracefully (`passes` → false, `notes` → "", `acceptanceCriteria` → [])
-
-Use `nightshift_setup(showExamples: true)` for the full schema reference and examples.
-
-2. Agents use these tools to work through stories:
-
-### PRD Tools
-
-#### `read_prd`
-Read the full PRD with completion summary.
-
-#### `get_next_story`
-Get the highest priority incomplete story.
-
-#### `get_incomplete_stories`
-List all remaining work.
-
-#### `claim_story`
-Claim a story and notify other agents via chat.
-
-**Parameters:**
-- `agent` (required): Your agent name
-- `storyId` (optional): Specific story to claim
-
-#### `complete_story`
-Mark story complete, log progress, and notify via chat.
-
-**Parameters:**
-- `agent` (required): Your agent name
-- `storyId` (required): Story ID
-- `summary` (required): What was implemented
-- `filesModified` (optional): List of changed files
-- `learnings` (optional): Gotchas/patterns for future iterations
-
-#### `mark_story_complete`
-Just mark a story as complete without chat notification.
-
-**Parameters:**
-- `storyId` (required): Story ID
-- `notes` (optional): Implementation notes
-
-### Progress Tools
-
-#### `read_progress`
-Read progress.txt containing learnings from all iterations.
-
-#### `append_progress`
-Add a timestamped progress entry.
-
-**Parameters:**
-- `content` (required): What was done, files changed, learnings
-
-#### `add_codebase_pattern`
-Add a reusable pattern to the Codebase Patterns section.
-
-**Parameters:**
-- `pattern` (required): The pattern (e.g., "Use sql<number> for aggregations")
-
-### Context Store
-
-NightShift includes a selective context retrieval system that replaces prompt-stuffing with topic-based queries. Instead of truncating progress.txt to fit the context window, agents can store and retrieve relevant context on demand.
-
-Context entries are stored as individual JSON files in `.robot-chat/context/` for concurrent-safe multi-agent access.
-
-#### `store_context`
-Store a context entry for other agents to query later.
-
-**Parameters:**
-- `topic` (required): Topic/category (e.g., "authentication", "database-schema")
-- `content` (required): The context to store (learnings, decisions, findings)
-- `agent` (required): Your agent name
-- `tags` (optional): Tags for better searchability (e.g., ["auth", "jwt"])
-
-**Example:**
-```
-store_context(topic: "authentication", content: "Using JWT with RS256. Refresh tokens stored in httpOnly cookies.", agent: "Claude", tags: ["jwt", "cookies"])
-```
-
-#### `query_context`
-Search stored context entries by topic.
-
-**Parameters:**
-- `topic` (required): Search term (case-insensitive match on topic and tags)
-- `limit` (optional): Max entries to return (default: 10)
-
-**Example:**
-```
-query_context(topic: "auth")
-# Returns all entries matching "auth" in topic or tags, sorted by recency
-```
-
-#### `list_context`
-List all topics in the context store with entry counts.
-
-**How delegation uses context:**
-
-When `delegate_story` or `delegate_research` spawns an agent, it queries the context store for entries relevant to the task and includes them in the prompt — instead of blindly truncating progress.txt. Agents are also instructed to use `store_context` to save their learnings, creating a self-enriching context loop.
-
-### Execution Tracing
-
-NightShift automatically traces all agent spawns, completions, and failures into a structured execution log at `.robot-chat/trace.json`. Each trace event has parent-child relationships that can be reconstructed as a tree for debugging multi-agent runs.
-
-#### `get_trace`
-View the execution trace as a flat list or tree.
-
-**Parameters:**
-- `tree` (optional): Return as tree with parent-child relationships (default: false)
-- `taskId` (optional): Filter by story/task ID
-
-**Example:**
-```
-get_trace(tree: true)
-# Returns tree showing: orchestrator → spawned claude (US-001) → completed
-#                        orchestrator → spawned codex (US-002) → failed → retried with gemini → completed
-```
-
-#### `clear_trace`
-Reset the trace for a fresh orchestration run.
-
-**What gets traced automatically:**
-- `spawn_agent` and `spawn_agent_background` calls
-- `delegate_story` and `delegate_research` delegations
-- `orchestrate` decisions (inline mode)
-- Agent completions with exit codes
-- Agent failures with error details
-
-Each trace event includes metadata: agent type, story ID, prompt length, exit code, and timing.
-
-### Autonomous Workflow
-
-With multiple agents working together:
-
-```
-┌──────────────────────────────────────────────────────────────────┐
-│                      NightShift Workflow                          │
-├──────────────────────────────────────────────────────────────────┤
-│                                                                   │
-│   ┌────────┐  ┌────────┐  ┌────────┐  ┌────────┐  ┌────────┐   │
-│   │ Claude │  │ Codex  │  │ Gemini │  │  Vibe  │  │ Goose  │   │
-│   └───┬────┘  └───┬────┘  └───┬────┘  └───┬────┘  └───┬────┘   │
-│       │           │           │           │           │          │
-│       └───────────┴─────┬─────┴───────────┴───────────┘          │
-│                         │                                         │
-│                         ▼                                         │
-│              ┌──────────────────┐                                 │
-│              │   .robot-chat/   │  ◄── Agent coordination        │
-│              │     chat.txt     │                                 │
-│              └──────────────────┘                                 │
-│                         │                                         │
-│     ┌──────────┬────────┼────────┬──────────┐                    │
-│     │          │        │        │          │                     │
-│     ▼          ▼        ▼        ▼          ▼                     │
-│ ┌────────┐ ┌────────┐ ┌────┐ ┌──────────┐ ┌──────────┐         │
-│ │prd.json│ │progress│ │Code│ │ context/ │ │trace.json│         │
-│ │(tasks) │ │  .txt  │ │    │ │(per-topic│ │(execution│         │
-│ │        │ │        │ │    │ │ queries) │ │  tree)   │         │
-│ └────────┘ └────────┘ └────┘ └──────────┘ └──────────┘         │
-│                                                                   │
-└──────────────────────────────────────────────────────────────────┘
-```
-
-Each agent:
-1. Checks for failovers (helps stuck agents first)
-2. Reads progress.txt for codebase patterns
-3. Claims the next story via chat
-4. Implements the story
-5. Runs quality checks
-6. Commits changes
-7. Marks complete and logs learnings
-8. Repeats until all stories pass
-
-When an agent hits limits, it posts `FAILOVER_NEEDED` and another agent claims the work.
-
-### Completion Signal
-
-When all stories in prd.json have `passes: true` AND all bugs in bugs.json have `fixed: true`, the tools:
-
-1. Post a `READY_TO_TEST` message to the chat
-2. Return `<promise>COMPLETE</promise>`
-
-This signals to humans that work is ready for review.
-
-## Bug Tracking
-
-When testing reveals issues, add a `bugs.json` file:
-
-```json
-{
-  "project": "MyApp",
-  "bugs": [
-    {
-      "id": "BUG-001",
-      "title": "Login fails on mobile",
-      "description": "Login button unresponsive on iOS Safari",
-      "stepsToReproduce": [
-        "Open app on iOS Safari",
-        "Enter credentials",
-        "Tap login button",
-        "Nothing happens"
-      ],
-      "priority": 1,
-      "fixed": false
-    }
-  ]
-}
-```
-
-### Bug Tools
-
-#### `read_bugs`
-Read bugs.json with completion summary.
-
-#### `get_next_bug`
-Get highest priority unfixed bug.
-
-#### `claim_bug`
-Claim a bug and notify via chat.
-
-**Parameters:**
-- `agent` (required): Your agent name
-- `bugId` (optional): Specific bug to claim
-
-#### `mark_bug_fixed`
-Mark bug fixed, create savepoint, and notify.
-
-**Parameters:**
-- `agent` (required): Your agent name
-- `bugId` (required): Bug ID
-- `summary` (required): What was fixed
-- `filesModified` (optional): Files changed
-
-## Savepoints (Recovery)
-
-Every completed story and fixed bug automatically creates a savepoint (git commit + tag). Use these for easy rollback if needed.
-
-### Savepoint Tools
-
-#### `create_savepoint`
-Create a manual checkpoint.
-
-**Parameters:**
-- `label` (required): Savepoint name (e.g., "pre-refactor", "auth-working")
-- `message` (optional): Commit message
-
-#### `list_savepoints`
-List all savepoints (git tags with `savepoint/` prefix).
-
-#### `rollback_savepoint`
-Reset to a previous savepoint. **Warning:** Discards all changes after that point.
-
-**Parameters:**
-- `label` (required): Savepoint to rollback to
-
-### Example Recovery
-
-```bash
-# Something went wrong after US-003
-# List available savepoints
-list_savepoints
-# → savepoint/US-001, savepoint/US-002, savepoint/US-003
-
-# Rollback to after US-002
-rollback_savepoint("US-002")
-# → All changes after US-002 discarded
-```
-
-## Workflow Management
-
-NightShift includes workflow tools for tracking project phases, recording strategic decisions, and managing agent assignments.
-
-### Workflow Tools
-
-#### `init_workflow`
-Initialize a new workflow with a project goal and optional custom phases.
-
-**Parameters:**
-- `projectGoal` (required): High-level goal of the project
-- `phases` (optional): Custom phases (default: research, decisions, planning, build, test, report)
-
-#### `get_workflow_state`
-Get the current workflow state including phase, assignments, and decisions.
-
-#### `advance_phase`
-Advance to the next workflow phase when the current phase's exit criteria are met.
-
-#### `set_phase`
-Manually set the workflow to a specific phase.
-
-**Parameters:**
-- `phase` (required): Target phase (research, decisions, planning, build, test, report, complete)
-
-#### `record_decision`
-Record a strategic decision with rationale for future reference.
-
-**Parameters:**
-- `topic` (required): What the decision is about
-- `options` (required): Options that were considered
-- `chosen` (required): The chosen option
-- `rationale` (required): Why this option was chosen
-- `decidedBy` (required): Agent or person who decided
-
-#### `get_decisions`
-Get all recorded decisions, optionally filtered by topic.
-
-#### `get_active_assignments`
-Get all stories currently being worked on by agents.
-
-#### `clear_assignment`
-Clear a story assignment (for abandonment/failover scenarios).
-
-## Setup & Debugging
-
-NightShift includes self-service tools for setup and troubleshooting.
-
-### `nightshift_setup`
-
-Get configuration instructions and verify project setup.
-
-**Parameters:**
-- `showExamples` (optional): Include prd.json and bugs.json templates
-
-**Returns:**
-- Project status checks (prd.json, bugs.json, git, .gitignore)
-- Agent configuration examples for Claude and Codex
-- Setup suggestions for any issues found
-- Example templates (if requested)
-
-**Example:**
-```
-nightshift_setup(showExamples: true)
-```
-
-### `nightshift_debug`
-
-Diagnose issues and get troubleshooting guidance.
-
-**Checks:**
-- File system permissions
-- JSON file validation (prd.json, bugs.json)
-- Daemon lock status
-- Recent chat errors and unclaimed failovers
-- Agent availability
-- Git repository status
-
-**Example:**
-```
-nightshift_debug
-# Returns detailed diagnostic report with suggested fixes
-```
-
-## Agent Spawning & Orchestration
-
-One agent can spawn others as subprocesses, enabling fully autonomous multi-agent workflows with minimal user intervention.
-
-### Spawning Tools
-
-#### `list_available_agents`
-Check which agent CLIs (claude, codex, gemini, vibe, goose) are installed and ready to run.
-
-#### `spawn_agent`
-Spawn another agent as a subprocess and wait for completion.
-
-**Parameters:**
-- `agent` (required): "claude", "codex", "gemini", "vibe", or "goose"
-- `prompt` (required): Task/prompt to send
-- `timeout` (optional): Seconds before timeout (default: 300)
-
-**Example:**
-```
-spawn_agent(agent: "codex", prompt: "Fix the type errors in src/utils.ts")
-```
-
-#### `spawn_agent_background`
-Spawn an agent in the background (non-blocking). Returns immediately with PID and output file path.
-
-**Parameters:**
-- `agent` (required): "claude", "codex", "gemini", "vibe", or "goose"
-- `prompt` (required): Task/prompt to send
-
-#### `delegate_story`
-Delegate a PRD user story to another agent with full context. On failure, returns a `retryHint` suggesting alternative available agents.
-
-**Parameters:**
-- `agent` (required): "claude", "codex", "gemini", "vibe", or "goose"
-- `storyId` (optional): Story ID to delegate (defaults to next available)
-- `background` (optional): Run in background (default: false)
-
-**Example:**
-```
-delegate_story(agent: "gemini", storyId: "US-003", background: true)
-```
-
-The spawned agent receives:
-- Full story description and acceptance criteria
-- Relevant context from the context store (or progress.txt as fallback)
-- Recent chat messages for context
-- Instructions to use nightshift tools for coordination (including `store_context` and `query_context`)
-
-#### `delegate_research`
-Delegate a research or planning task to an agent (default: Gemini). Ideal for read-only tasks like codebase analysis, architecture planning, code review, and documentation. Queries the context store for relevant prior findings.
-
-**Parameters:**
-- `task` (required): The research/planning task description
-- `agent` (optional): Which agent to use (default: gemini)
-- `context` (optional): Additional context to provide
-- `background` (optional): Run in background (default: false)
-
-### Monitoring Tools
-
-#### `get_agent_status`
-Check the status of a spawned background agent by PID.
-
-**Parameters:**
-- `pid` (required): Process ID of the spawned agent
-
-**Returns:**
-- Whether the agent is still running or has exited
-- Exit code (if finished)
-- Last 30 lines of output
-- Story assignment (if delegated via `delegate_story`)
-
-#### `list_running_agents`
-List all agents spawned in the current session with their status.
-
-**Returns:** Array of agents with PID, agent type, running/exited status, elapsed time, and story assignment.
-
-### Orchestration
-
-#### `orchestrate`
-Run an autonomous orchestration loop that claims stories, implements them, and marks them complete until all work is done. This is the highest-level automation tool.
-
-**Parameters:**
-- `agent` (optional): Your agent name (default: "NightShift")
-- `maxIterations` (optional): Maximum stories to process (default: 50)
-- `mode` (optional): "stories", "bugs", or "all" (default: "all")
-
-### Orchestration Patterns
-
-**Fully autonomous (recommended):**
-```
-orchestrate(agent: "Claude", mode: "all")
-# Runs until all stories and bugs are complete
-```
-
-**Sequential delegation:**
-```
-delegate_story(agent: "codex")        # Wait for completion
-delegate_story(agent: "gemini")       # Then delegate next
-```
-
-**Parallel execution:**
-```
-delegate_story(agent: "codex", storyId: "US-001", background: true)
-delegate_story(agent: "goose", storyId: "US-002", background: true)
-# Work on US-003 yourself while they run in parallel
-# Monitor with get_agent_status or list_running_agents
-```
-
-**Research then implement:**
-```
-delegate_research(task: "Analyze auth patterns and recommend approach")
-# Use findings to inform implementation
-delegate_story(agent: "codex", storyId: "US-001")
-```
-
-## NightShift Daemon (Continuous Orchestration)
-
-For fully automated, event-driven orchestration, run the NightShift daemon:
-
-```bash
-# Start the daemon
-nightshift-daemon
-
-# With options
-nightshift-daemon --verbose --max-agents 4 --health-check 1m
-
-# Preview mode (see what would happen)
-nightshift-daemon --dry-run --verbose
-```
-
-### How It Works
-
-The daemon provides hands-off multi-agent orchestration:
-
-1. **Event-Driven**: Watches `prd.json` and `chat.txt` for changes
-2. **Auto-Spawning**: Spawns agents for orphaned stories (up to concurrency limit)
-3. **Failover Handling**: Automatically claims and reassigns failover requests
-4. **Smart Retry**: Tracks failed agents per story and tries a different agent on retry
-5. **Health Checks**: Periodic reconciliation as a fallback (default: every 2 min)
-6. **Poison Pill Protection**: Quarantines stories that fail repeatedly
-7. **Stuck Detection**: Kills agents that haven't reported activity
-
-### Options
-
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--verbose, -v` | Enable debug logging | false |
-| `--dry-run` | Show actions without spawning | false |
-| `--health-check <N>` | Health check interval (e.g., "2m", "30s") | 2m |
-| `--max-agents <N>` | Max concurrent agents | 3 |
-
-### Environment
-
-- `ROBOT_CHAT_PROJECT_PATH` - Project directory (default: current directory)
-
-### Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                   NightShift Daemon                         │
-├─────────────────────────────────────────────────────────────┤
-│                                                             │
-│   ┌──────────────────────────────────────────────────┐     │
-│   │              File Watchers (Primary)              │     │
-│   │   • prd.json changes → reconcile                 │     │
-│   │   • chat.txt changes → check failovers           │     │
-│   └──────────────────────────────────────────────────┘     │
-│                          │                                  │
-│                          ▼                                  │
-│   ┌──────────────────────────────────────────────────┐     │
-│   │            Reconciliation Engine                  │     │
-│   │   • Find orphaned stories                        │     │
-│   │   • Spawn agents (up to max concurrency)         │     │
-│   │   • Handle failovers                             │     │
-│   │   • Quarantine poison pills                      │     │
-│   └──────────────────────────────────────────────────┘     │
-│                          │                                  │
-│                          ▼                                  │
-│   ┌──────────────────────────────────────────────────┐     │
-│   │           Health Check (Fallback)                 │     │
-│   │   • Runs every 2 minutes                         │     │
-│   │   • Detects stuck agents                         │     │
-│   │   • Restarts watchers if needed                  │     │
-│   │   • Reconciles state                             │     │
-│   └──────────────────────────────────────────────────┘     │
-│                                                             │
-└─────────────────────────────────────────────────────────────┘
-```
-
-## Local Models via Ollama
-
-NightShift supports local Ollama models through two harnesses:
-
-### Goose + Ollama (Recommended for tool use)
-
-[Goose](https://github.com/block/goose) has its own tool-calling implementation that works reliably with local models. This is the recommended path for local agent work.
-
-```bash
-# Install Goose CLI
-curl -fsSL https://github.com/block/goose/releases/latest/download/install.sh | bash
-
-# Install Ollama and pull a model
-ollama pull qwen3.5:4b
-
-# Configure nightshift to use Goose with Ollama
-export NIGHTSHIFT_GOOSE_PROVIDER=ollama
-export NIGHTSHIFT_GOOSE_MODEL=qwen3.5:4b
-```
-
-Then use `goose` as your agent in nightshift:
-```
-spawn_agent(agent: "goose", prompt: "Fix the pagination bug in src/api.ts")
-delegate_research(agent: "goose", task: "Analyze error handling patterns")
-```
-
-**Recommended models** (by hardware):
-
-| GPU VRAM | Model | Size | Notes |
-|----------|-------|------|-------|
-| 4GB+ | `qwen3.5:4b` | 3.4 GB | Fast, good tool use |
-| 6GB+ | `qwen3.5:4b-q8_0` | 5.3 GB | Better accuracy, same speed |
-| 8GB+ | `qwen3.5:9b` | 6.6 GB | Best quality, slower on consumer GPUs |
-
-### Claude Code + Ollama (Text generation only)
-
-For tasks that don't require tool use (summarization, code review, planning):
-
-```bash
-export NIGHTSHIFT_OLLAMA_MODEL=qwen3.5:4b   # or any Ollama model
-```
-
-Then use `ollama` as your agent:
-```
-spawn_agent(agent: "ollama", prompt: "Review this PR for security issues")
-delegate_research(agent: "ollama", task: "Summarize the authentication patterns")
-```
-
-This uses Claude Code's harness with Ollama's Anthropic-compatible API. Text generation works well, but local models don't reliably trigger Claude Code's structured tool calls.
-
-### Benchmarking Local Models
-
-A benchmark suite is included to test which models work on your hardware:
-
-```bash
-# Test all tasks with goose + a specific model
-node benchmarks/run-experiment.mjs --agent goose --model qwen3.5:4b
-
-# Test only text-level tasks (fast sanity check)
-node benchmarks/run-experiment.mjs --agent goose --model qwen3.5:4b --level text
-
-# Compare models
-node benchmarks/run-experiment.mjs --agent goose --model qwen3.5:9b
-```
-
-Results are saved to `benchmarks/results/` for comparison across runs.
-
-## Multi-Agent Tips
-
-1. **Same directory**: All agents must run in the same project directory to share chat
-2. **Claim before working**: Always claim stories to prevent duplicate work
-3. **Post status updates**: Keep other agents informed of progress
-4. **Store context, not just progress**: Use `store_context` to share learnings by topic — other agents can query for exactly what they need instead of reading a giant progress file
-5. **Handle failovers**: Check for and claim failovers at the start of each session
-6. **Use delegation**: One orchestrating agent can spawn others for parallel work
-7. **Monitor background agents**: Use `get_agent_status` and `list_running_agents` to track spawned agents
-8. **Use `orchestrate` for full autonomy**: The `orchestrate` tool handles the entire claim→implement→complete loop
-9. **Review traces after runs**: Use `get_trace(tree: true)` to understand what happened during orchestration
-10. **Add `.robot-chat/` to your project's `.gitignore`**: Chat logs, context, and traces are ephemeral and shouldn't be committed
-
-## 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
+
+### Reliability (New in 2.0)
+- **Circuit breaker**: Per-agent CLOSED/OPEN/HALF_OPEN state machine. 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, circuit break, 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
+
+### 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
+- **49 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.0
+
+- **SQLite foundation**: New data layer (`.robot-chat/nightshift.db`) with ACID transactions and WAL mode. Powers audit trail, run records, budget tracking, and circuit breaker persistence. Legacy managers (chat, PRD, workflow) still use their original files for backwards compatibility — migration planned for 2.1.
+- **Circuit breaker**: Tracks consecutive failures per agent type. Auto-disables after threshold (default: 3), auto-recovers after cooldown (default: 60s). Single-probe enforcement in half-open state.
+- **Immutable audit trail**: Every daemon event logged to `audit_log` table. Queryable by event type, agent, story, or timestamp.
+- **Run records + autoresearch**: Structured execution data feeds analytics queries for agent performance optimization.
+- **Budget tracking**: Enable/disable per agent with configurable daily and monthly cost limits. Ready for OpenRouter integration.
+- **Security**: MCP SDK upgraded to 1.28.0. Zero production dependency 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")
+```
+
+### 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 49 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 |
+
+### Orchestration
+| Tool | Description |
+|------|-------------|
+| `orchestrate` | Autonomous claim-implement-complete loop |
+| `get_agent_status` | Check background agent by PID |
+| `list_running_agents` | All spawned agents with status |
+
+### 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
+- Circuit breaker 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 |
+| **Circuit breaker** | `.robot-chat/nightshift.db` | SQLite |
+
+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