Claude Code Context Monitor
CLI tool to monitor and analyze context usage in Claude Code sessions. Track token consumption, cache efficiency, context window utilization, and get "lost-in-middle" risk warnings.
Know your context. Ship better prompts. 🧠
Claude Code's 200k context window is powerful, but invisible. You don't know when you're:
- Approaching the limit
- Wasting tokens on stale tool outputs
- At risk of the "lost-in-middle" effect (important info getting ignored)
ccmon parses your local Claude Code session logs and surfaces the metrics that matter.
npm install -g ccmonOr run directly:
npx ccmon listccmon list # Show 10 most recent sessions
ccmon list -n 20 # Show more📋 Recent Claude Code Sessions
┌──────────┬─────────────────────────────┬──────────┬────────┬────────┬──────────────────┐
│ ID │ Project │ Messages │ Input │ Output │ Last Activity │
├──────────┼─────────────────────────────┼──────────┼────────┼────────┼──────────────────┤
│ 697e63d5 │ ~/dev/myproject │ 1241 │ ↑51.7k │ ↓2.1k │ Jan 25, 09:41 AM │
│ 44446268 │ ~/dev/another-project │ 34 │ ↑198 │ ↓99 │ Jan 24, 11:46 PM │
└──────────┴─────────────────────────────┴──────────┴────────┴────────┴──────────────────┘
ccmon analyze # Analyze most recent session
ccmon analyze 697e63d5 # Analyze by ID (partial match works)
ccmon analyze -d # Include per-turn breakdown
ccmon analyze -j # Output as JSON🔍 Session Analysis
Session: 697e63d5
Project: ~/dev/myproject
Started: 1/22/2026, 6:23:20 PM
📊 Summary
┌─────────────────────────┬────────────────────────────────────────┐
│ Total Turns │ 1241 │
│ Total Input Tokens │ ↑ 51.7k │
│ Total Output Tokens │ ↓ 2.1k │
│ Cache Created │ 4.4M │
│ Cache Read │ 76.5M │
│ Peak Input │ 11.9k (turn 1114) │
│ Tool Use Turns │ 345 │
│ Models │ claude-sonnet-4-5 │
│ │ claude-opus-4-5 │
└─────────────────────────┴────────────────────────────────────────┘
📈 Context Utilization
██░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 5.9%
🟢 Context healthy
Peak: 11.9k / 200.0k
📍 Lost-in-Middle Risk: LOW
Context size manageable
ccmon watch # Live-tail the most recent sessionUpdates in real-time as you interact with Claude Code.
| Metric | Description |
|---|---|
| Input/Output Tokens | Tokens sent to and received from Claude |
| Cache Created | New tokens added to Claude's cache |
| Cache Read | Tokens served from cache (saves cost!) |
| Context Utilization | % of 200k window used at peak |
| Lost-in-Middle Risk | Warning when important context might be ignored |
| Tool Use Turns | Turns where Claude used tools (often token-heavy) |
Claude Code stores session logs locally at ~/.claude/projects/. ccmon parses these JSONL files and extracts token usage from the API response metadata — no additional API calls needed.
- Node.js 20+
- Claude Code installed (logs must exist in
~/.claude/)
src/
├── core/
│ ├── types.ts # Type definitions
│ ├── parser.ts # Parse ~/.claude/ session logs
│ └── analyzer.ts # Compute metrics and insights
└── cli/
├── index.ts # CLI entry point
├── list.ts # ccmon list
├── analyze.ts # ccmon analyze
└── watch.ts # ccmon watch
- MCP server for in-session queries ("check my context budget")
- Breakdown by content type (tool results vs thinking vs text)
- Historical trends and charts
- Export reports (markdown, HTML)
- VS Code extension
MIT
PRs welcome! Ideas:
- Support for other AI coding tools (Cursor, Copilot, etc.)
- Better "lost-in-middle" heuristics
- Token cost estimation