# Claude Session MCP
An MCP (Model Context Protocol) server that provides Claude Code with **programmatic session awareness** - the ability to query context usage, read todos, track session history, sync planning docs, and make intelligent reset recommendations.
## Why This Exists
Claude Code agents, slash commands, and hooks need to make smart decisions about session management:
- **Before spawning a sub-agent:** Check if there's enough context budget remaining
- **Before expensive operations:** Verify we're not at 90% context and about to trigger compaction
- **When resuming work:** Know what todos are already in progress to avoid duplication
- **During long sessions:** Programmatically update `.context/dev/{branch}/` planning docs
- **End of task:** Get intelligent recommendations on whether to reset context
This MCP server makes all of that possible by exposing session state through 5 core tools.
---
## Features
### 5 Session Awareness Tools
| Tool | Purpose | Use Cases |
|------|---------|-----------|
| **`check_context_budget`** | Query context window usage and remaining capacity | Gate operations when context is critical, warn before spawning agents |
| **`get_session_state`** | Unified snapshot of todos, git state, context files, session info | Check existing todos before creating new ones, verify branch state |
| **`get_session_history`** | What's been accomplished (files modified, todos completed, commits) | Auto-generate session summaries, resume after context reset |
| **`sync_planning_doc`** | Programmatically update `.context/dev/{branch}/` planning docs | Log decisions as you work, mark tasks complete in real-time |
| **`should_reset_context`** | Intelligent recommendations for when to reset context | End-of-task automation, proactive warnings |
---
## Installation
### Prerequisites
- Python 3.11+ (tested on 3.13)
- [uv](https://github.com/astral-sh/uv) package manager
- Claude Code CLI
### Install Steps
```bash
# Clone the repository
git clone https://github.com/yourusername/ccsession
cd ccsession
# Install with uv
uv venv
uv pip install -e ".[dev]"
```
---
## Configuration
### Option 1: Global Configuration
Add to `~/.claude/mcp.json`:
```json
{
"mcpServers": {
"ccsession": {
"command": "uv",
"args": ["run", "python", "-m", "ccsession"],
"cwd": "/home/your-username/path/to/ccsession"
}
}
}
```
### Option 2: Project-Level Configuration
Add to `<your-project>/.claude/mcp.json`:
```json
{
"mcpServers": {
"ccsession": {
"command": "uv",
"args": ["run", "python", "-m", "ccsession"],
"cwd": "/home/your-username/path/to/ccsession"
}
}
}
```
### Verify Installation
After restarting Claude Code, the tools will be available to agents and slash commands. You can verify by asking:
> "Can you check the context budget using the MCP tools?"
---
## Tool Reference
### 1. `check_context_budget`
Query current context window usage and remaining capacity.
**Parameters:**
- `context_limit` (optional): Maximum context tokens. Default: 156,000 (200K × 0.78 threshold)
**Returns:**
```json
{
"tokens_used": 45230,
"tokens_remaining": 110770,
"percentage_used": 29.0,
"context_limit": 156000,
"status": "sufficient"
}
```
**Status Values:**
- `sufficient`: < 60% used
- `low`: 60-80% used
- `critical`: > 80% used
**Example Usage in Slash Command:**
```markdown
<!-- .claude/commands/check-budget.md -->
Use the `check_context_budget` MCP tool to see how much context we have left.
If status is "critical", warn me and recommend resetting context.
```
---
### 2. `get_session_state`
Get a unified snapshot of current session state.
**Parameters:**
- `working_directory` (optional): Working directory for git operations. Defaults to current directory.
**Returns:**
```json
{
"todos": {
"pending": [
{
"content": "Deploy to production",
"status": "pending",
"activeForm": "Deploying to production"
}
],
"in_progress": [
{
"content": "Update documentation",
"status": "in_progress",
"activeForm": "Updating documentation"
}
],
"completed": [
{
"content": "Implement auth middleware",
"status": "completed",
"activeForm": "Implementing auth middleware"
}
]
},
"git": {
"branch": "feat/auth",
"has_uncommitted_changes": true,
"uncommitted_file_count": 3,
"is_git_repo": true
},
"context_files": {
"branch_dir": ".context/dev/feat/auth",
"plan_path": ".context/dev/feat/auth/feat-auth-detailed-plan.md",
"exists": true
},
"session": {
"start_time": "2025-12-03T14:00:00+00:00",
"duration_minutes": 45,
"session_id": "73cc9f9a-1234-5678-9abc-def012345678"
}
}
```
**Example Usage in Agent:**
```python
# Before creating new todos, check what's already in progress
state = await get_session_state()
if any(t["content"] == "Implement authentication" for t in state["todos"]["in_progress"]):
print("Authentication implementation already in progress, skipping duplicate todo")
```
---
### 3. `get_session_history`
Get what has been accomplished this session.
**Parameters:**
- `working_directory` (optional): Working directory for git operations. Defaults to current directory.
**Returns:**
```json
{
"completed_todos": [
"Implement auth middleware",
"Add tests",
"Update documentation"
],
"files_modified": {
"created": ["src/auth/middleware.ts"],
"edited": ["src/server.ts", "README.md"],
"deleted": []
},
"tool_calls": {
"bash_commands": ["npm test", "git commit -m 'feat: add auth'"],
"agents_spawned": ["Explore", "Plan"],
"files_read": 23,
"files_written": 5
},
"git_commits": [
{
"sha": "a3f5d2c",
"message": "feat(auth): add middleware"
}
]
}
```
**Example Usage in `/reset-context` Command:**
```markdown
<!-- .claude/commands/reset-context.md -->
1. Use `get_session_history` to see what was accomplished
2. Generate a concise summary from completed_todos and git_commits
3. Save summary to `.context/session-summaries/{date}-{session-id}.md`
4. Reset context with summary as reload context
```
---
### 4. `sync_planning_doc`
Programmatically update `.context/dev/{branch}/` planning documents.
**Parameters:**
- `mode` (required): One of:
- `append_progress_log`: Add timestamped entry to Progress Log
- `update_active_work`: Replace Active Work section
- `mark_tasks_complete`: Mark tasks as `[x]` in Implementation Plan
- `completed_tasks` (array): Tasks completed (for `append_progress_log` or `mark_tasks_complete`)
- `in_progress` (string): Current work description (for `update_active_work`)
- `decisions` (array): Key decisions made (for `append_progress_log`)
- `blockers` (array): Current blockers (for `update_active_work` or `append_progress_log`)
- `next_steps` (array): Next immediate steps (for `update_active_work`)
- `working_directory` (optional): Working directory. Defaults to current directory.
**Returns:**
```json
{
"success": true,
"plan_path": ".context/dev/feat-auth/feat-auth-detailed-plan.md",
"sections_updated": ["Progress Log"]
}
```
**Example 1: Append Progress Log**
```json
{
"mode": "append_progress_log",
"completed_tasks": ["Phase 1.1: Database schema", "Phase 1.2: API endpoints"],
"decisions": ["Using bcrypt for password hashing", "JWT tokens expire after 24h"],
"blockers": []
}
```
**Example 2: Update Active Work**
```json
{
"mode": "update_active_work",
"in_progress": "Implementing user registration endpoint",
"next_steps": [
"Add input validation",
"Write unit tests",
"Test with Postman"
],
"blockers": ["Waiting for design review on error messages"]
}
```
**Example 3: Mark Tasks Complete**
```json
{
"mode": "mark_tasks_complete",
"completed_tasks": [
"Implement authentication",
"Write tests"
]
}
```
This will change:
```markdown
- [ ] Implement authentication
- [ ] Write tests
```
To:
```markdown
- [x] Implement authentication
- [x] Write tests
```
---
### 5. `should_reset_context`
Get intelligent recommendation on whether to reset context.
**Parameters:**
- `working_directory` (optional): Working directory. Defaults to current directory.
**Returns:**
```json
{
"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,
"blockers": [],
"suggested_summary": "Completed: auth middleware, tests, documentation"
}
```
**Decision Logic:**
| Condition | Recommendation |
|-----------|----------------|
| Context >80% + clean git + todos done | `should_reset: true`, `confidence: high` |
| Context 60-80% + todos done + clean git | `should_reset: true`, `confidence: high` |
| Context 60-80% + clean git | `should_reset: true`, `confidence: medium` |
| Context >60% + uncommitted changes | `should_reset: false`, `safe_to_reset: false` |
| Session >60min + todos done + clean git | `should_reset: true`, `confidence: medium` |
**Example Usage in Hook:**
```json
// .claude/hooks/before-agent-spawn.json
{
"command": "bash -c 'claude-code mcp call should_reset_context | jq -r .should_reset'",
"on_success": "proceed",
"on_failure": "warn"
}
```
---
## Use Cases
### Use Case 1: Smart Agent Spawning
**Problem:** Agent spawns a sub-agent, but context is at 85%, causing immediate compaction and lost context.
**Solution:**
```markdown
<!-- In your agent prompt -->
Before spawning any sub-agents, ALWAYS:
1. Call `check_context_budget`
2. If status is "critical" or "low", call `should_reset_context`
3. If reset recommended, warn user and ask permission before proceeding
```
### Use Case 2: Avoid Duplicate Todos
**Problem:** After context reset, agent creates duplicate todos for work already in progress.
**Solution:**
```markdown
<!-- In your slash command -->
Before creating todos:
1. Call `get_session_state`
2. Check if any `todos.in_progress` or `todos.pending` match your planned work
3. Only create new todos for work not already tracked
```
### Use Case 3: Real-Time Planning Doc Updates
**Problem:** Planning docs in `.context/dev/{branch}/` only get updated at end of session, losing valuable decision history.
**Solution:**
```markdown
<!-- In your agent prompt -->
After completing each major task:
1. Call `sync_planning_doc` with mode="append_progress_log"
2. Include completed_tasks and any key decisions made
3. This keeps planning docs as living documents
```
### Use Case 4: Automated Session Summaries
**Problem:** Manually writing session summaries before context reset is tedious and error-prone.
**Solution:**
```markdown
<!-- .claude/commands/auto-reset.md -->
1. Call `get_session_history` to get completed_todos and git_commits
2. Generate 2-3 sentence summary
3. Call `should_reset_context` to verify safe to reset
4. If safe, save summary and reset context with /reset command
```
---
## Architecture
### How It Works
1. **Transcript Discovery**: Scans `/tmp/claude-code-transcripts/` for the most recent `.jsonl` file
2. **Token Counting**: Parses transcript to sum `input_tokens + output_tokens + cache_creation_input_tokens + cache_read_input_tokens`
3. **Todo Parsing**: Reads `~/.claude/todos/{session_id}*.json` files (handles agent spawns)
4. **Git Operations**: Subprocess calls to `git` CLI for branch, status, commits
5. **Planning Doc Updates**: Markdown section parsing with regex, preserves formatting
### File Locations
```
~/.claude/
├── todos/{session_id}.json # Main session todos
├── todos/{session_id}-agent-*.json # Agent spawn todos
└── mcp.json # MCP server config
/tmp/claude-code-transcripts/
└── {session_id}.jsonl # Session transcript
<project>/.context/dev/{branch}/
└── {branch}-detailed-plan.md # Planning document
```
### Context Limit Calculation
Claude Code triggers `/compact` at ~78% of the 200K context window:
```python
DEFAULT_CONTEXT_LIMIT = int(200_000 * 0.78) # 156,000 tokens
```
Thresholds:
- **Sufficient**: < 60% of limit (< 93,600 tokens)
- **Low**: 60-80% of limit (93,600 - 124,800 tokens)
- **Critical**: > 80% of limit (> 124,800 tokens)
---
## Development
### Running Tests
```bash
# Run all tests
uv run pytest
# Run with verbose output
uv run pytest -v
# Run specific test file
uv run pytest tests/test_transcript.py
# Run with coverage
uv run pytest --cov=ccsession
```
### Test Coverage
- **47 passing tests** covering:
- Transcript parsing (token counting, session start time, edge cases)
- Git utilities (state detection, commits, planning doc paths)
- Todo parsing (session todos, agent spawns, latest todos)
- All 5 MCP tools (integration tests with mocked dependencies)
### Project Structure
```
ccsession/
├── src/ccsession/
│ ├── __init__.py
│ ├── __main__.py # Entry point
│ ├── server.py # MCP server + all 5 tools
│ └── parsers/
│ ├── transcript.py # JSONL parsing, token counting
│ ├── git.py # Git operations
│ └── todos.py # Todo file parsing
├── tests/
│ ├── conftest.py # Shared fixtures
│ ├── test_transcript.py # Transcript parser tests
│ ├── test_git.py # Git utilities tests
│ ├── test_todos.py # Todo parser tests
│ ├── test_mcp_tools.py # Integration tests
│ └── fixtures/ # Test data
├── pyproject.toml # Package config
└── README.md
```
### Adding New Features
1. **New parser:** Add to `src/ccsession/parsers/`
2. **New tool:** Add handler in `server.py` under `handle_tool_call()`
3. **Add tests:** Create `tests/test_*.py` with fixtures
4. **Update docs:** Document in this README
---
## Troubleshooting
### MCP server not found
**Error:** `MCP server 'claude-session' not found`
**Solution:**
1. Check `~/.claude/mcp.json` or `<project>/.claude/mcp.json` exists
2. Verify `cwd` path points to correct directory
3. Restart Claude Code to reload MCP config
### No transcript found
**Error:** Tools return empty/zero values
**Solution:**
1. Verify `/tmp/claude-code-transcripts/` directory exists
2. Check that `.jsonl` files are being created during sessions
3. MCP uses most recent file by modification time
### Planning doc not found
**Error:** `sync_planning_doc` returns "Plan file not found"
**Solution:**
1. Verify `.context/dev/{branch}/{branch}-detailed-plan.md` exists
2. Check you're on the correct git branch
3. Planning doc path follows pattern: branch name with dashes, not slashes
### Tests failing
**Error:** Import errors or test failures
**Solution:**
```bash
# Reinstall in development mode
uv pip install -e ".[dev]"
# Clear pytest cache
rm -rf .pytest_cache
# Run with full traceback
uv run pytest -v --tb=long
```
---
## Acknowledgments
- **Transcript parsing logic** ported from [ccusage](https://github.com/ryoppippi/ccusage) by [@ryoppippi](https://github.com/ryoppippi)
- Built with the [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- Designed for [Claude Code](https://www.anthropic.com/claude/code)
---
## License
MIT License - see LICENSE file for details
---
## Contributing
Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch (`git checkout -b feat/amazing-feature`)
3. Add tests for new functionality
4. Ensure all tests pass (`uv run pytest`)
5. Submit a pull request
---
## Future Enhancements
Potential Wave 2+ features (see `PLAN.md` for full list):
- **Session comparison:** Diff two sessions to see what changed
- **Cost tracking:** Token usage → USD cost estimates
- **Time tracking:** How long was spent on each task
- **Planning doc templates:** Auto-generate planning docs from templates
- **Multi-session search:** Find when/where specific work was done
- **Session replay:** Reconstruct what happened in a previous session
See something missing? [Open an issue](https://github.com/yourusername/ccsession/issues)!
