NightShift MCP

Multi-agent orchestration across AI models. The responsible kind of multi-agent chaos.

An MCP server that coordinates Claude, Codex, Gemini, Vibe, Goose, and local Ollama models as an agentic team. Structured delegation, shared task management, autonomous workflows, and production-grade reliability features. Works with any MCP-compatible client.

Quick Start

# Install
npm install -g nightshift-mcp

# Configure for Claude Code (~/.claude.json)
{
  "mcpServers": {
    "nightshift": { "command": "nightshift-mcp", "args": [] }
  }
}

# Configure for Codex (~/.codex/config.toml)
[mcp_servers.nightshift]
command = "nightshift-mcp"
args = []

All agents must run in the same project directory to share coordination state.

# Terminal 1              # Terminal 2
cd ~/myproject            cd ~/myproject
claude                    codex

Features

Orchestration

• Agent spawning: Spawn Claude, Codex, Gemini, Vibe, Goose, or Ollama as subprocesses with full lifecycle tracking
• Autonomous mode: Single orchestrate tool runs claim-implement-complete loops until all stories pass
• Daemon mode: Event-driven background orchestrator with file watchers, health checks, and auto-recovery
• Delegation: Hand off stories or research tasks to specific agents with full context injection
• Failover handling: Seamless handoffs when an agent hits rate limits or context windows
• Runtime project switching: Switch active project without restarting the MCP server

Reliability

• Health tracker: Per-agent failure tracking. Auto-disables failing agents, re-enables after configurable cooldown. Persisted across daemon restarts.
• Immutable audit trail: Append-only SQLite table records every spawn, completion, failure, and stuck-agent kill
• Run records: Structured execution history per agent run — duration, exit status, files changed, scope leak detection
• Budget tracking: Per-agent cost tracking with daily/monthly limits, warning thresholds, enable/disable toggle
• Autoresearch: Built-in analytics queries — agent success rates, average duration, scope leak rates

Observability

• Token tracking: Parses token usage from agent output. Every spawn_agent call logs to .robot-chat/runs.jsonl.
• Run log + stats: Structured JSONL log per spawn. get_run_stats for aggregate tokens per agent, avg durations, rate limit counts.
• Rate limit detection: Parses 429s, "quota exceeded", retry-after from agent output. Returns structured rate_limited status.
• Agent role tagging: role param on spawn_agent, delegate_story — planner, coder, fixer, verifier, etc.
• Configurable pipelines: Define multi-step agent pipelines with tag-based routing. get_pipeline / set_pipeline tools.
• Tool usage tracking: Parses which tools agents used from output.

Task Management

• PRD-driven workflow: User stories in prd.json with priorities, dependencies (dependsOn), and tags for routing
• Bug tracking: bugs.json for post-testing feedback loops
• Savepoints: Git-based checkpoints (or JSON fallback) with rollback support
• Progress tracking: Shared learnings via progress.txt

Communication

• Multi-agent chat: Structured messaging via .robot-chat/chat.txt with agent name, timestamp, and message type
• Context store: Topic-based context retrieval — agents store and query learnings instead of prompt-stuffing
• Execution tracing: Parent-child trace trees for debugging multi-agent runs

Platform

• Cross-platform: Windows, Linux, macOS
• 6 agent types: Claude, Codex, Gemini, Vibe, Goose, Ollama
• 52 MCP tools across 10 categories
• NightShift CLI: nightshift command for agent coordination without MCP
• Zero external services: Everything runs locally with SQLite + file storage

Architecture

┌───────────────────────────────────────────────────────────┐
│                    NightShift MCP                          │
├───────────────────────────────────────────────────────────┤
│                                                           │
│  ┌────────┐ ┌────────┐ ┌────────┐ ┌──────┐ ┌──────────┐ │
│  │ Claude │ │ Codex  │ │ Gemini │ │ Vibe │ │Goose/Olla│ │
│  └───┬────┘ └───┬────┘ └───┬────┘ └──┬───┘ └────┬─────┘ │
│      └──────────┴─────┬─────┴─────────┴──────────┘       │
│                       ▼                                   │
│            ┌─────────────────────┐                        │
│            │   .robot-chat/      │                        │
│            │                     │                        │
│            │  chat.txt     (msg) │                        │
│            │  nightshift.db (v2) │                        │
│            │  workflow.json      │                        │
│            │  trace.json         │                        │
│            │  context/           │                        │
│            └─────────────────────┘                        │
│                       │                                   │
│      ┌────────────────┼────────────────┐                  │
│      ▼                ▼                ▼                  │
│  ┌────────┐    ┌────────────┐    ┌──────────┐            │
│  │prd.json│    │ nightshift │    │progress  │            │
│  │(stories│    │    .db     │    │  .txt    │            │
│  │ + bugs)│    │ (audit,    │    │(learnings│            │
│  │        │    │  budget,   │    │ patterns)│            │
│  │        │    │  runs,     │    │          │            │
│  │        │    │  circuits) │    │          │            │
│  └────────┘    └────────────┘    └──────────┘            │
│                                                           │
└───────────────────────────────────────────────────────────┘

Usage Patterns

Fully autonomous

orchestrate()

Parallel delegation

delegate_story(agent: "codex", storyId: "US-001", background: true)
delegate_story(agent: "gemini", storyId: "US-002", background: true)

Research then implement

delegate_research(task: "Analyze auth patterns and recommend approach")
delegate_story(agent: "codex", storyId: "US-001")

Pipeline (multi-step)

set_pipeline(name: "default", steps: [
  { agent: "gemini", role: "planner" },
  { agent: "codex", role: "implementer" },
  { agent: "claude", role: "verifier" }
])
orchestrate()

Daemon (hands-off)

nightshift-daemon --verbose --max-agents 4

PRD Setup

Create prd.json in your project root:

{
  "project": "MyApp",
  "userStories": [
    {
      "id": "US-001",
      "title": "Set up project structure",
      "acceptanceCriteria": ["Add routes", "Create base components"],
      "priority": 1,
      "passes": false
    },
    {
      "id": "US-002",
      "title": "Add database schema",
      "priority": 2,
      "passes": false,
      "dependsOn": ["US-001"],
      "tags": ["code", "infrastructure"]
    }
  ]
}

Story fields

| Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | id | string | yes | — | Unique ID (e.g., "US-001") | | title | string | yes | — | Short title | | description | string | no | "" | Detailed description | | acceptanceCriteria | string[] | no | [] | Completion criteria | | priority | number | no | 999 | Lower = higher priority | | passes | boolean | no | false | Whether complete | | dependsOn | string[] | no | — | Story IDs that must complete first | | tags | string[] | no | — | Routing hints (e.g., ["code"], ["research"]) |

Tags influence agent routing: research/planning prefers Gemini/Claude, code/implementation prefers Codex/Claude.

Bug Tracking

Add bugs.json when testing reveals issues:

{
  "project": "MyApp",
  "bugs": [
    {
      "id": "BUG-001",
      "title": "Login fails on mobile",
      "description": "Login button unresponsive on iOS Safari",
      "priority": 1,
      "fixed": false
    }
  ]
}

When all stories pass and all bugs are fixed, NightShift posts READY_TO_TEST to the chat.

Tools Reference

NightShift provides 52 tools across 10 categories. Key tools listed below — use nightshift_setup(showExamples: true) or nightshift_help for full documentation.

Communication

| Tool | Description | |------|-------------| | read_robot_chat | Read recent messages (filter by agent, type, limit) | | write_robot_chat | Post a message (STATUS_UPDATE, QUESTION, ERROR, etc.) | | check_failovers | Find unclaimed failover requests | | claim_failover | Take over work from a stuck agent | | list_agents | See who's active with activity stats | | watch_chat | Cursor-based polling for new messages |

Task Management

| Tool | Description | |------|-------------| | read_prd | Read PRD with completion summary | | get_next_story | Get highest priority incomplete story | | claim_story | Claim a story and notify via chat | | complete_story | Mark done, log progress, create savepoint | | read_bugs / claim_bug / mark_bug_fixed | Bug lifecycle |

Agent Spawning

| Tool | Description | |------|-------------| | list_available_agents | Check which CLIs are installed and runnable | | spawn_agent | Spawn agent, wait for completion (sync) | | spawn_agent_background | Spawn agent, return immediately (async) | | delegate_story | Delegate a story with full context injection | | delegate_research | Delegate research/analysis task | | get_run_stats | Token usage, durations, rate limits from run log |

Orchestration & Pipelines

| Tool | Description | |------|-------------| | orchestrate | Autonomous claim-implement-complete loop | | get_agent_status | Check background agent by PID | | list_running_agents | All spawned agents with status | | set_project_path | Switch active project at runtime | | get_pipeline | View configured pipelines and tag routing | | set_pipeline | Create/update agent pipelines at runtime |

Workflow

| Tool | Description | |------|-------------| | init_workflow | Initialize with project goal and phases | | advance_phase / set_phase | Phase management | | record_decision | Record strategic decisions with rationale |

Context & Tracing

| Tool | Description | |------|-------------| | store_context / query_context | Topic-based context store | | get_trace | Execution trace (flat or tree view) |

Recovery

| Tool | Description | |------|-------------| | create_savepoint | Manual git checkpoint | | list_savepoints | List all savepoints | | rollback_savepoint | Reset to a previous savepoint |

Setup

| Tool | Description | |------|-------------| | nightshift_setup | Configuration check and templates | | nightshift_debug | Diagnostic report with suggested fixes |

Daemon

The daemon provides hands-off, event-driven orchestration:

nightshift-daemon [options]

| Flag | Default | Description | |------|---------|-------------| | --verbose, -v | false | Debug logging | | --dry-run | false | Preview without spawning | | --health-check <N> | 2m | Health check interval | | --max-agents <N> | 3 | Max concurrent agents |

What it does:

• Watches prd.json and chat.txt for changes
• Auto-spawns agents for unassigned stories
• Health tracker disables failing agents, re-enables after cooldown
• Detects and kills stuck agents
• Claims failover requests
• Quarantines stories that fail repeatedly
• Logs everything to the SQLite audit trail

Local Models

NightShift supports local models via Goose + Ollama or direct Ollama integration.

Goose + Ollama

export NIGHTSHIFT_GOOSE_PROVIDER=ollama
export NIGHTSHIFT_GOOSE_MODEL=<your-model>

spawn_agent(agent: "goose", prompt: "Fix the pagination bug")

Direct Ollama

export NIGHTSHIFT_OLLAMA_MODEL=<your-model>

spawn_agent(agent: "ollama", prompt: "Review this PR")

Any Ollama-compatible model works. Choose a model that fits your available resources.

Data Storage

NightShift uses a hybrid storage approach:

| Data | Storage | Format | |------|---------|--------| | Agent chat | .robot-chat/chat.txt | Human-readable text | | PRD / stories | prd.json | JSON | | Bugs | bugs.json | JSON | | Progress | progress.txt | Append-only text | | Workflow | .robot-chat/workflow.json | JSON with file locking | | Trace | .robot-chat/trace.json | JSON | | Context | .robot-chat/context/*.json | Per-topic JSON files | | Audit trail | .robot-chat/nightshift.db | SQLite (immutable) | | Run records | .robot-chat/nightshift.db | SQLite | | Budget | .robot-chat/nightshift.db | SQLite | | Health tracker | .robot-chat/nightshift.db | SQLite | | Run log | .robot-chat/runs.jsonl | JSONL (append-only) | | Pipeline config | .robot-chat/pipeline-override.json | JSON (runtime) |

Add .robot-chat/ to your .gitignore — coordination state is ephemeral.

Development

npm install
npm run build
npm test          # run test suite
npm run dev       # watch mode
npm link          # global CLI access

License

MIT