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):

npm install -g nightshift-mcp

Updating:

npm update -g nightshift-mcp

Or build from source:

git clone <repo-url>
cd nightshift-mcp
npm install
npm run build
npm link  # makes 'nightshift-mcp' available globally

Configuration

Claude Code (~/.claude.json)

{
  "mcpServers": {
    "nightshift": {
      "command": "nightshift-mcp",
      "args": []
    }
  }
}

Codex (~/.codex/config.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:

# 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

npx @modelcontextprotocol/inspector node /path/to/nightshift-mcp/dist/index.js /tmp/test-project

Manual Testing

# Set project path and run
ROBOT_CHAT_PROJECT_PATH=/tmp/test-project node dist/index.js

Development

# 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:

{
  "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 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:

{
  "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

# 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:

# 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