# Claude Session MCP - Development Plan
## Overview
Build an MCP server that gives Claude Code **programmatic session awareness** - the ability to query context usage, read todos, track session history, sync planning docs, and make intelligent reset recommendations.
**Repository:** `/home/tim/Github/claude-session-mcp`
**Language:** Python (matches existing statusline.py patterns)
## Core Tools (5 Tools)
### 1. `check_context_budget`
Query current context window usage and remaining capacity.
```python
# Returns:
{
"tokens_used": 45230,
"tokens_remaining": 110770,
"percentage_used": 29.0,
"context_limit": 156000, # 200K * 0.78 threshold
"status": "sufficient" | "low" | "critical"
}
```
**Implementation:**
- Reuse logic from `statusline.py` (parse transcript, find latest usage block)
- Read `transcript_path` from MCP context or discover from `/tmp/claude-code-transcripts/`
- Thresholds: sufficient (<60%), low (60-80%), critical (>80%)
**Use cases:**
- Agents check before spawning sub-agents
- Slash commands decide whether to proceed with expensive operations
- Hooks gate operations when context is critical
---
### 2. `get_session_state`
Unified snapshot of current session state.
```python
# Returns:
{
"todos": {
"pending": [{"content": "...", "status": "pending"}],
"in_progress": [...],
"completed": [...]
},
"git": {
"branch": "feat/social-network-phase-6",
"has_uncommitted_changes": true,
"uncommitted_file_count": 3
},
"context_files": {
"branch_dir": ".context/dev/feat/social-network-phase-6",
"plan_path": ".context/dev/feat/social-network-phase-6/feat-social-network-phase-6-detailed-plan.md",
"exists": true
},
"session": {
"start_time": "2025-12-03T14:00:00Z",
"duration_minutes": 45
}
}
```
**Implementation:**
- Read todos from `~/.claude/todos/{session_id}.json` (discover session ID from transcript path)
- Run `git branch --show-current`, `git status --porcelain`
- Construct `.context/dev/{branch}/` path, check if plan exists
- Parse transcript for session start timestamp
**Use cases:**
- Agents check existing todos before creating duplicates
- Slash commands get full context in one call
- Determine if `.context` planning doc exists for current branch
---
### 3. `get_session_history`
What has been accomplished this session (for plan syncing, resumption).
```python
# Returns:
{
"completed_todos": ["Implement auth middleware", "Add tests"],
"files_modified": {
"created": ["src/auth/middleware.ts"],
"edited": ["src/server.ts"],
"deleted": []
},
"tool_calls": {
"bash_commands": ["npm test", "git commit"],
"agents_spawned": ["Explore", "Plan"],
"files_read": 23,
"files_written": 5
},
"git_commits": [
{"sha": "a3f5d2c", "message": "feat(auth): add middleware"}
]
}
```
**Implementation:**
- Parse transcript JSONL for:
- Tool calls (Write, Edit, Bash with git commit)
- Agent spawns (Task tool with subagent_type)
- TodoWrite calls to track completed todos
- Run `git log --oneline -n 10` and filter to session timeframe
- Track files modified via Write/Edit tool calls in transcript
**Use cases:**
- `/reset-context` can auto-generate session summary
- After reset, agents know what was already done
- End-of-session verification: "did we complete the plan?"
---
### 4. `sync_planning_doc`
Programmatically update `.context/dev/{branch}/` planning documents.
```python
# Input:
{
"updates": {
"completed_tasks": ["Phase 1.1", "Phase 1.2"],
"in_progress": "Phase 2: Backend API",
"decisions": ["Using bcrypt for hashing"],
"blockers": null
},
"mode": "append_progress_log" | "update_active_work" | "mark_tasks_complete"
}
# Returns:
{
"success": true,
"plan_path": ".context/dev/feat-auth/feat-auth-detailed-plan.md",
"sections_updated": ["Active Work", "Progress Log"]
}
```
**Implementation:**
- Auto-detect branch via `git branch --show-current`
- Construct plan path: `.context/dev/{branch}/{branch}-detailed-plan.md`
- Parse markdown sections (regex for `## Active Work`, `## Progress Log`, etc.)
- Append/update sections based on mode
- Preserve existing content, only modify targeted sections
**Use cases:**
- Agents log decisions as they work (not just at reset time)
- Slash commands mark items complete in real-time
- Keeps planning docs as living documents
---
### 5. `should_reset_context`
Intelligent recommendation engine for context reset.
```python
# Returns:
{
"should_reset": true,
"confidence": "high",
"reasoning": [
"Context 82% full (critical threshold)",
"All in_progress todos completed",
"Clean git state (no uncommitted changes)",
"Session duration: 2h 15m"
],
"safe_to_reset": true, # false if uncommitted changes
"blockers": [], # ["3 uncommitted files"] if unsafe
"suggested_summary": "Completed auth feature: middleware + tests"
}
```
**Implementation:**
- Combine signals from other tools:
- `check_context_budget()` for usage %
- `get_session_state()` for todos, git state
- `get_session_history()` for completion analysis
- Decision logic:
- Critical context (>80%) + clean git = strong recommend
- Low context (60-80%) + all todos done = moderate recommend
- Uncommitted changes = block until committed
- Generate summary from completed todos for reload context
**Use cases:**
- Hooks check before major operations
- Agents warn proactively: "I need 50K tokens but only 20K remain"
- End-of-task automation: detect clean state, suggest reset
---
## Architecture
```
claude-session-mcp/
├── pyproject.toml # Package config, dependencies
├── README.md # Usage documentation
├── src/
│ └── claude_session_mcp/
│ ├── __init__.py
│ ├── server.py # MCP server entry point
│ ├── tools/
│ │ ├── __init__.py
│ │ ├── context.py # check_context_budget
│ │ ├── state.py # get_session_state
│ │ ├── history.py # get_session_history
│ │ ├── planning.py # sync_planning_doc
│ │ └── advisor.py # should_reset_context
│ └── parsers/
│ ├── __init__.py
│ ├── transcript.py # JSONL transcript parsing
│ ├── todos.py # Todo file parsing
│ └── git.py # Git operations
└── tests/
├── test_context.py
├── test_state.py
└── fixtures/
└── sample_transcript.jsonl
```
---
## Implementation Phases
### Phase 1: Project Setup & Core Infrastructure
- [ ] Initialize Python project with pyproject.toml
- [ ] Set up MCP server skeleton using `mcp` library
- [ ] Create transcript parser (port logic from statusline.py)
- [ ] Create git utilities module
- [ ] Create todo file parser
**Key files:**
- `pyproject.toml` - dependencies: `mcp`, `jsonlines`
- `src/claude_session_mcp/server.py` - MCP server boilerplate
- `src/claude_session_mcp/parsers/transcript.py` - JSONL parsing
### Phase 2: Implement Core Tools
- [ ] `check_context_budget` - token counting from transcript
- [ ] `get_session_state` - todos + git + context files
- [ ] `get_session_history` - transcript analysis for accomplishments
- [ ] `sync_planning_doc` - markdown section updates
- [ ] `should_reset_context` - decision engine combining all signals
**Key files:**
- `src/claude_session_mcp/tools/*.py` - one file per tool
### Phase 3: Testing & Integration
- [ ] Unit tests for each tool
- [ ] Integration test with sample transcript
- [ ] Test MCP server registration
- [ ] Test from Claude Code (manual verification)
### Phase 4: Configuration & Polish
- [ ] Add MCP to Claude Code config (`~/.claude/mcp.json` or project-level)
- [ ] Add configurable thresholds (context %, TTL, etc.)
- [ ] Error handling for missing files, permissions
- [ ] Documentation (README, usage examples)
---
## Technical Decisions
### Transcript Discovery
- Scan `/tmp/claude-code-transcripts/` for most recent `.jsonl` file by mtime
- Cache transcript path after first discovery
- Invalidate cache when:
- A newer transcript file appears (new session started)
- Current file's mtime changes (new content written)
- Parse transcript lazily (only read what's needed, start from end for token counts)
### Todo File Location
- Pattern: `~/.claude/todos/{session_id}*.json`
- Session ID extracted from transcript filename
- Handle multiple todo files per session (agent spawns)
### Git Operations
- Use subprocess calls to `git` CLI (simple, reliable)
- Wrap in try/except for non-git directories
### Planning Doc Parsing
- Use regex for section detection (`^## .*$`)
- Preserve formatting, only modify targeted sections
- Create backup before modifying (`.bak` file)
### Error Handling
- All tools return structured errors, never crash
- Missing transcript = return zeros/empty with warning
- Non-git directory = omit git section, not error
---
## MCP Configuration
After implementation, add to `~/.claude/mcp.json`:
```json
{
"mcpServers": {
"claude-session": {
"command": "python",
"args": ["-m", "claude_session_mcp"],
"cwd": "/home/tim/Github/claude-session-mcp"
}
}
}
```
Or use `uv` for dependency management:
```json
{
"mcpServers": {
"claude-session": {
"command": "uv",
"args": ["run", "python", "-m", "claude_session_mcp"],
"cwd": "/home/tim/Github/claude-session-mcp"
}
}
}
```
---
## Success Criteria
- [ ] All 5 tools implemented and returning correct data
- [ ] MCP server registers successfully with Claude Code
- [ ] `check_context_budget` matches statusline.py output
- [ ] `get_session_state` correctly reads todos and git state
- [ ] `sync_planning_doc` updates .context files without corruption
- [ ] `should_reset_context` gives sensible recommendations
- [ ] Slash commands can call MCP tools programmatically
- [ ] Hooks can use context budget to gate operations
---
## Dependencies
```toml
[project]
dependencies = [
"mcp>=1.0.0", # MCP Python SDK
"jsonlines", # Efficient JSONL parsing
]
[project.optional-dependencies]
dev = [
"pytest",
"pytest-asyncio",
]
```
---
## Alternative: ccusage Integration
[ccusage](https://github.com/ryoppippi/ccusage) is an existing CLI/MCP tool that provides detailed token usage analytics from Claude Code JSONL files.
### What ccusage provides:
- Token counting (input, output, cache tokens)
- Cost calculation
- Daily/monthly/session aggregation
- MCP server component (`@ccusage/mcp`)
### What ccusage does NOT provide (our value-add):
- Todo list awareness
- Planning doc sync (.context files)
- Session history tracking (files modified, tools used)
- Intelligent reset recommendations
- Git state integration
### Integration Options:
**Option A: Hybrid approach (recommended)**
- Use ccusage's MCP for detailed token analytics
- Build our MCP for session intelligence features
- Both MCPs can run simultaneously
- `check_context_budget` wraps/calls ccusage or implements simple version
**Option B: Standalone**
- Port statusline.py logic for token counting (simpler, fewer dependencies)
- Self-contained, no npm/node dependency
- Slightly less detailed analytics but sufficient for context decisions
### Recommendation: Start with Option B (standalone)
- Simpler to implement and test
- No external dependencies
- Can add ccusage integration later if needed
- Focus on unique session intelligence features
---
## Reference: ccusage Analysis
Analyzed [ccusage](https://github.com/ryoppippi/ccusage) (cloned to `/home/tim/Github/ccusage`) for best practices.
### Transcript JSONL Format (from ccusage)
**Entry structure:**
```json
{"type":"assistant","message":{"usage":{"input_tokens":1000,"output_tokens":50,"cache_creation_input_tokens":100,"cache_read_input_tokens":500}}}
```
**Token calculation (ccusage's `_token-utils.ts`):**
```typescript
total = input_tokens + output_tokens + cache_creation_input_tokens + cache_read_input_tokens
```
### Claude Code Statusline Hook JSON
From `ccusage/apps/ccusage/test/statusline-test.json`:
```json
{
"session_id": "73cc9f9a-2775-4418-beec-bc36b62a1c6f",
"transcript_path": "/path/to/session.jsonl",
"cwd": "/working/directory",
"model": {"id": "claude-sonnet-4-20250514", "display_name": "Sonnet 4"},
"workspace": {"current_dir": "...", "project_dir": "..."},
"version": "1.0.88",
"cost": {"total_cost_usd": 0.056266, ...},
"exceeds_200k_tokens": false
}
```
**Key insight:** Claude Code already provides `transcript_path` and `exceeds_200k_tokens` via the statusline hook!
### Edge Cases Handled (from ccusage)
1. **Missing optional fields** - Cache tokens default to 0
2. **Deduplication** - Uses `messageId:requestId` hash to prevent double-counting
3. **Invalid JSON** - Skips silently (try/catch around JSON.parse)
4. **Synthetic models** - Filters out `<synthetic>` model entries
5. **Empty lines** - Skipped before parsing
6. **Stream processing** - Uses readline interface for memory efficiency
### .context structure (to support)
- Branch workspace: `.context/dev/{branch-name}/`
- Plan document: `.context/dev/{branch-name}/{branch-name}-detailed-plan.md`
- Sections to parse: `## Active Work`, `## Progress Log`, `## Implementation Plan`
---
## Implementation Progress
### Completed
- [x] `pyproject.toml` - Project configuration
- [x] Directory structure created
- [x] `parsers/transcript.py` - Full transcript parser with:
- Token counting (all 4 types)
- Context budget calculation (sufficient/low/critical)
- Tool call extraction
- Files modified tracking
- Agents spawned tracking
- Deduplication support
- Caching with mtime invalidation
- [x] `parsers/git.py` - Git utilities with:
- Branch detection
- Uncommitted changes tracking
- Recent commits
- .context path resolution
### In Progress
- [ ] `parsers/todos.py` - Todo file parser
- [ ] `server.py` - MCP server skeleton
### Pending
- [ ] Tool implementations (5 tools)
- [ ] Tests
- [ ] Documentation
