# 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

```bash
# 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):

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

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

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

## Database Location

Default: `~/.claude/state.db`

Override with environment variable:
```bash
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:
```json
{
  "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:
```json
{
  "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:
```json
{
  "tool": "session_list_active"
}
```

### Query History

```
What did I work on last week?
```

Claude calls:
```json
{
  "tool": "session_history",
  "args": { "days": 7 }
}
```

### Coordinate Files

Before editing a shared file:

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

```sql
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:

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

Or open the database directly:

```bash
sqlite3 ~/.claude/state.db
```