nightshift-mcp 1.0.6 → 1.0.8

package/README.md

@@ -1,799 +1,800 @@
-# NightShift MCP
-
-**The responsible kind of multi-agent chaos.**
-
-Explicit delegation, review, and handoffs between AI models.
-
----
-
-An MCP (Model Context Protocol) server that enables multi-agent communication and task coordination via shared files. Designed for AI agents (Claude, Codex, Gemini, etc.) to collaborate autonomously with minimal human intervention.
-
-## Features
-
-- **Multi-agent chat**: Structured messages with agent name, timestamp, type, and content
-- **Failover handling**: Seamless handoffs when an agent hits limits
-- **Ralph-style PRD management**: Work through user stories in prd.json with Zod-validated schemas and helpful error messages
-- **Progress tracking**: Shared learnings via progress.txt
-- **Agent spawning & orchestration**: Spawn Claude, Codex, Gemini, or Vibe as subprocesses with full lifecycle tracking
-- **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)
-- **Universal compatibility**: Works with any MCP-supporting tool (42 tools across 8 categories)
-- **Simple file-based storage**: No external services required
-
-## 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": "Add database field",
-      "description": "As a developer, I need to store the new field",
-      "acceptanceCriteria": [
-        "Add column to table",
-        "Run migration",
-        "Typecheck passes"
-      ],
-      "priority": 1,
-      "passes": false,
-      "notes": ""
-    }
-  ]
-}
-```
-
-### 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 |
-
-### 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")
-
-### Autonomous Workflow
-
-With multiple agents working together:
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    NightShift Workflow                       │
-├─────────────────────────────────────────────────────────────┤
-│                                                              │
-│   ┌────────┐  ┌────────┐  ┌────────┐  ┌────────┐          │
-│   │ Claude │  │ Codex  │  │ Gemini │  │  Vibe  │          │
-│   └───┬────┘  └───┬────┘  └───┬────┘  └───┬────┘          │
-│       │           │           │           │                │
-│       └───────────┴─────┬─────┴───────────┘                │
-│                        │                                    │
-│                        ▼                                    │
-│              ┌─────────────────┐                           │
-│              │  .robot-chat/   │  ◄── Agent coordination   │
-│              │    chat.txt     │                           │
-│              └─────────────────┘                           │
-│                        │                                    │
-│        ┌───────────────┼───────────────┐                   │
-│        │               │               │                    │
-│        ▼               ▼               ▼                    │
-│   ┌─────────┐    ┌──────────┐   ┌────────────┐            │
-│   │ prd.json│    │progress. │   │   Code     │            │
-│   │ (tasks) │    │   txt    │   │  Changes   │            │
-│   └─────────┘    └──────────┘   └────────────┘            │
-│                                                              │
-└─────────────────────────────────────────────────────────────┘
-```
-
-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) are installed and ready to run.
-
-#### `spawn_agent`
-Spawn another agent as a subprocess and wait for completion.
-
-**Parameters:**
-- `agent` (required): "claude", "codex", "gemini", or "vibe"
-- `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", or "vibe"
-- `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", or "vibe"
-- `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
-- Recent content from progress.txt
-- Recent chat messages for context
-- Instructions to use nightshift tools for coordination
-
-#### `delegate_research`
-Delegate a research or planning task to Gemini. Ideal for read-only tasks like codebase analysis, architecture planning, code review, and documentation.
-
-**Parameters:**
-- `task` (required): The research/planning task description
-- `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: "gemini", 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                             │     │
-│   └──────────────────────────────────────────────────┘     │
-│                                                             │
-└─────────────────────────────────────────────────────────────┘
-```
-
-## 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. **Document learnings**: Progress.txt helps future iterations
-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. **Add `.robot-chat/` to your project's `.gitignore`**: Chat logs are ephemeral and shouldn't be committed
-
-## License
-
-MIT
+# 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, and Vibe 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 Zod-validated schemas and helpful error messages
+- **Progress tracking**: Shared learnings via progress.txt
+- **Agent spawning & orchestration**: Spawn Claude, Codex, Gemini, or Vibe as subprocesses with full lifecycle tracking
+- **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 (42 tools across 8 categories)
+- **Simple file-based storage**: No external services required
+
+## 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": "Add database field",
+      "description": "As a developer, I need to store the new field",
+      "acceptanceCriteria": [
+        "Add column to table",
+        "Run migration",
+        "Typecheck passes"
+      ],
+      "priority": 1,
+      "passes": false,
+      "notes": ""
+    }
+  ]
+}
+```
+
+### 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 |
+
+### 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")
+
+### Autonomous Workflow
+
+With multiple agents working together:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    NightShift Workflow                       │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│   ┌────────┐  ┌────────┐  ┌────────┐  ┌────────┐          │
+│   │ Claude │  │ Codex  │  │ Gemini │  │  Vibe  │          │
+│   └───┬────┘  └───┬────┘  └───┬────┘  └───┬────┘          │
+│       │           │           │           │                │
+│       └───────────┴─────┬─────┴───────────┘                │
+│                        │                                    │
+│                        ▼                                    │
+│              ┌─────────────────┐                           │
+│              │  .robot-chat/   │  ◄── Agent coordination   │
+│              │    chat.txt     │                           │
+│              └─────────────────┘                           │
+│                        │                                    │
+│        ┌───────────────┼───────────────┐                   │
+│        │               │               │                    │
+│        ▼               ▼               ▼                    │
+│   ┌─────────┐    ┌──────────┐   ┌────────────┐            │
+│   │ prd.json│    │progress. │   │   Code     │            │
+│   │ (tasks) │    │   txt    │   │  Changes   │            │
+│   └─────────┘    └──────────┘   └────────────┘            │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+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) are installed and ready to run.
+
+#### `spawn_agent`
+Spawn another agent as a subprocess and wait for completion.
+
+**Parameters:**
+- `agent` (required): "claude", "codex", "gemini", or "vibe"
+- `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", or "vibe"
+- `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", or "vibe"
+- `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
+- Recent content from progress.txt
+- Recent chat messages for context
+- Instructions to use nightshift tools for coordination
+
+#### `delegate_research`
+Delegate a research or planning task to Gemini. Ideal for read-only tasks like codebase analysis, architecture planning, code review, and documentation.
+
+**Parameters:**
+- `task` (required): The research/planning task description
+- `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: "gemini", 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                             │     │
+│   └──────────────────────────────────────────────────┘     │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 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. **Document learnings**: Progress.txt helps future iterations
+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. **Add `.robot-chat/` to your project's `.gitignore`**: Chat logs are ephemeral and shouldn't be committed
+
+## License
+
+MIT