Cortex MCP

Claude Code token usage analytics + prompt coaching — track your AI usage, get efficiency tips, and improve your prompting right inside Claude Code.

Cortex reads your local ~/.claude/ data and exposes it as MCP tools. No network calls. No data leaves your machine.

Quick Start

Add to your Claude Code config (~/.claude/settings.json):

{
  "mcpServers": {
    "cortex": {
      "command": "npx",
      "args": ["-y", "cortex-token-monitor"]
    }
  }
}

Or install globally:

npm install -g cortex-token-monitor

Then add to settings:

{
  "mcpServers": {
    "cortex": {
      "command": "cortex-token-monitor"
    }
  }
}

Slash Commands (Optional)

Copy the files from commands/ into ~/.claude/commands/ to get slash commands:

cp commands/*.md ~/.claude/commands/

Then use /analyze-session, /efficiency-tips, or /prompt-score in any Claude Code session.

Available Tools

Usage Analytics

| Tool | Description | Example Prompt | |------|-------------|----------------| | get_daily_usage | Token usage for a specific day | "How many tokens did I use today?" | | get_usage_history | Usage over last N days with trends | "Show my usage trend this week" | | get_project_breakdown | Tokens per project | "Which project burns the most tokens?" | | get_model_usage | Breakdown by model (Opus/Sonnet/Haiku) | "What models am I using?" | | get_session_stats | Overall session statistics | "How many sessions have I had?" | | get_health_score | Efficiency score (0-100) with grade | "What's my health score?" | | get_peak_hours | When you're most active | "When do I code the most?" |

Prompt Coaching

| Tool | Description | Example Prompt | |------|-------------|----------------| | analyze_session | Deep-dive a session — retries, errors, bloat, prompt quality | "Analyze my last session" | | get_efficiency_tips | Actionable tips from recent sessions | "How can I be more efficient?" | | get_prompt_score | Score your prompting patterns (0-100) | "Score my prompting" |

What It Detects

Prompt Retries

Finds correction phrases ("no I meant", "not that", "actually") and estimates tokens wasted on the wrong response.

Error Chains

Consecutive tool failures (e.g., Read failing 3 times on wrong paths). Suggests checking prerequisites first.

Redundant File Reads

Files read multiple times in a session, especially without offset/limit targeting.

Session Bloat

Sessions over 300 messages where context degradation kicks in.

Prompt Specificity

Scores each prompt on word count, file references, constraints, and context. Tells you exactly what's missing.

Health Score

A composite efficiency score based on:

• Cache Efficiency (30%) — how well prompt caching is working
• Session Efficiency (25%) — optimal session length vs context bloat
• Tool Utilization (20%) — productive use of tools
• Consistency (25%) — regular usage patterns

Grades: S (90+), A (80+), B (70+), C (60+), D (50+), F (<50)

Data Sources

Cortex reads these files (all local, read-only):

• ~/.claude/stats-cache.json — aggregated daily stats
• ~/.claude/projects/ — session JSONL files per project
• ~/.claude/projects/*/sessions-index.json — session metadata

Requirements

• Node.js 18+
• Claude Code installed (the ~/.claude/ directory must exist)

Development

git clone https://github.com/hjw808/cortex-mcp.git
cd cortex-mcp
npm install
npm run build

Test with MCP inspector:

npx @modelcontextprotocol/inspector node dist/index.js

License

MIT