Claude State MCP Server

SQLite-backed MCP server for Claude Code session persistence and multi-agent coordination.

Features

• Session Persistence — Save/restore session state across Claude Code restarts
• Event Logging — Track what you worked on, when
• Decision Tracking — Record architectural decisions with rationale
• File Locking — Prevent conflicts between parallel agents
• Agent Registry — See who's working on what
• Plan Tracking — Monitor GSD plan execution progress

Installation

# Clone or copy this directory
cd claude-state-mcp

# Install dependencies
npm install

# Build
npm run build

# Test it works
node dist/index.js
# Should see: "Claude State MCP initialized: ~/.claude/state.db"
# Ctrl+C to exit

Claude Code Configuration

Add to your ~/.claude/claude_desktop_config.json (or create it):

{
  "mcpServers": {
    "claude-state": {
      "command": "node",
      "args": ["/absolute/path/to/claude-state-mcp/dist/index.js"]
    }
  }
}

Or if you prefer npx (after publishing to npm):

{
  "mcpServers": {
    "claude-state": {
      "command": "npx",
      "args": ["claude-state-mcp"]
    }
  }
}

Database Location

Default: ~/.claude/state.db

Override with environment variable:

CLAUDE_STATE_DB=/custom/path/state.db node dist/index.js

Available Tools

Session Management

Tool	Description
session_start	Start a new session (call at beginning)
session_end	End session with notes (call at end)
session_get	Get last session for a branch
session_list_active	List all active sessions
session_update_progress	Update phase/plan/task progress
session_history	"What did I work on last week?"

Event Logging

Tool	Description
event_log	Log an event (task completion, etc.)
event_list	Get recent events

Decision Tracking

Tool	Description
decision_record	Record an architectural decision
decision_list	Get all active decisions
decision_supersede	Replace a decision with a new one

File Coordination

Tool	Description
files_lock	Lock files to prevent conflicts
files_unlock	Release file locks
files_check_conflicts	Check if files are locked
files_list_locks	List all locks

Agent Registry

Tool	Description
agent_register	Register this Claude instance
agent_heartbeat	Update heartbeat
agent_list_active	List active agents
agent_deregister	Mark agent as terminated

Plan Tracking

Tool	Description
plan_start	Record start of GSD plan
plan_update_progress	Update task completion
plan_complete	Record plan completion
plan_status	Get status of plans in a phase

Utility

Tool	Description
query	Run custom SELECT query

Usage Examples

Start of Session

Claude, start a session for branch feature/calendar in /Users/me/project

Claude calls:

{
  "tool": "session_start",
  "args": {
    "branch": "feature/calendar",
    "worktree_path": "/Users/me/project"
  }
}

End of Session

Claude, save my session - we're stopping for the day

Claude calls:

{
  "tool": "session_end",
  "args": {
    "branch": "feature/calendar",
    "worktree_path": "/Users/me/project",
    "context_notes": ["Working on WeekView component", "Using react-big-calendar"],
    "next_steps": ["Finish time slot click handlers", "Add drag-and-drop"],
    "blockers": [],
    "uncommitted_files": ["src/components/WeekView.tsx"]
  }
}

Check What's Running

What other Claude sessions are active?

Claude calls:

{
  "tool": "session_list_active"
}

Query History

What did I work on last week?

Claude calls:

{
  "tool": "session_history",
  "args": { "days": 7 }
}

Coordinate Files

Before editing a shared file:

{
  "tool": "files_check_conflicts",
  "args": {
    "files": ["src/lib/api.ts"],
    "project_path": "/Users/me/project",
    "worktree_path": "/Users/me/worktrees/feature-1"
  }
}

Integration with GSD Workflow

The /worktree-context command should call:

session_get(branch, worktree_path, include_events: true)
session_list_active()
files_list_locks(project_path)
agent_list_active()

The /persist-session command should call:

session_end(branch, worktree_path, context_notes, next_steps, blockers, uncommitted_files)

Schema

sessions        -- One active per branch/worktree
events          -- Activity log
decisions       -- Architectural decisions
file_locks      -- Coordination between agents
agents          -- Registry of Claude instances
plan_executions -- GSD plan tracking

Querying Directly

Use the query tool for custom queries:

{
  "tool": "query",
  "args": {
    "sql": "SELECT * FROM events WHERE event_type = 'task_completed' AND timestamp > datetime('now', '-1 day')"
  }
}

Or open the database directly:

sqlite3 ~/.claude/state.db