nightshift-mcp 1.0.0

package/README.md

@@ -0,0 +1,670 @@
+# 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
+- **Progress tracking**: Shared learnings via progress.txt
+- **Agent tracking**: See which agents are active and what they're working on
+- **Watch/polling**: Monitor for new messages with cursor-based polling
+- **Auto-archiving**: Archive old messages to keep the chat file manageable
+- **Universal compatibility**: Works with any MCP-supporting tool
+- **Simple file-based storage**: No external services required
+
+## Installation
+
+**Via npm (recommended):**
+```bash
+npm install -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": "node",
+      "args": ["/path/to/nightshift-mcp/dist/index.js"],
+      "env": {
+        "ROBOT_CHAT_PROJECT_PATH": "${PWD}"
+      }
+    }
+  }
+}
+```
+
+### Codex (`~/.codex/config.toml`)
+
+```toml
+[mcp_servers.nightshift]
+command = "node"
+args = ["/path/to/nightshift-mcp/dist/index.js"]
+env = { ROBOT_CHAT_PROJECT_PATH = "${PWD}" }
+```
+
+## 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",
+  "branchName": "feature/my-feature",
+  "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": ""
+    }
+  ]
+}
+```
+
+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
+```
+
+## 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 (Autonomous Orchestration)
+
+One agent can spawn others as subprocesses, enabling fully autonomous multi-agent workflows with minimal user intervention.
+
+### Tools
+
+#### `list_available_agents`
+Check which agent CLIs (claude, codex, gemini, vibe) are installed.
+
+#### `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).
+
+**Parameters:**
+- `agent` (required): "claude", "codex", "gemini", or "vibe"
+- `prompt` (required): Task/prompt to send
+
+Returns immediately with PID and output file path.
+
+#### `delegate_story`
+Delegate a PRD user story to another agent with full context.
+
+**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
+
+### Orchestration Patterns
+
+**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
+```
+
+**Ad-hoc task delegation:**
+```
+spawn_agent(agent: "claude", prompt: "Review the auth module and suggest improvements")
+```
+
+## 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. **Health Checks**: Periodic reconciliation as a fallback (default: every 2 min)
+5. **Poison Pill Protection**: Quarantines stories that fail repeatedly
+6. **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. **Add `.robot-chat/` to your project's `.gitignore`**: Chat logs are ephemeral and shouldn't be committed
+
+## License
+
+MIT