Session Analytics & Coverage Intelligence

trace-mcp includes a built-in analytics engine that parses AI agent session logs, tracks token savings, detects wasteful patterns, and assesses technology coverage.

How it works

Session logs (JSONL)                   Project manifests
  Claude Code: ~/.claude/projects/       package.json, composer.json,
  Claw Code: <project>/.claw/sessions/  requirements.txt, go.mod, ...
         │                                        │
         ▼                                        ▼
┌─────────────────────────┐         ┌──────────────────────────┐
│  Log Parser             │         │  Tech Detector           │
│  Extracts:              │         │  Parses manifests,       │
│  - tool calls + results │         │  classifies deps,        │
│  - token usage          │         │  matches against         │
│  - model info           │         │  known-packages catalog  │
│  - target files         │         │  (~200 packages)         │
└──────────┬──────────────┘         └──────────┬───────────────┘
           │                                   │
           ▼                                   ▼
┌─────────────────────────┐         ┌──────────────────────────┐
│  Analytics DB (SQLite)  │         │  Coverage Report         │
│  ~/.trace-mcp/          │         │  covered / gaps /        │
│    analytics.db         │         │  unknown deps            │
│  Tables:                │         └──────────────────────────┘
│  - sessions             │
│  - tool_calls           │
│  - sync_state           │
└──────────┬──────────────┘
           │
     ┌─────┴──────┬──────────────┬─────────────────┐
     ▼            ▼              ▼                  ▼
 Analytics    Optimization    Real Savings       Benchmark
 Report       Report          Analysis           Engine
 (per tool,   (8 rules,       (Read vs           (synthetic,
  per file,    savings est.)   get_symbol)        5 scenarios)
  per model)

Supported clients

Client	Session log location	Config files
Claude Code	`~/.claude/projects/<encoded-path>/<session-id>.jsonl`	`CLAUDE.md`, `.claude/settings.json`
Claw Code	`<project>/.claw/sessions/<session-id>.jsonl`	`.claw.json`, `.claw/settings.json`

Both formats are auto-detected during sync. No configuration needed.

Local-machine scoping

get_session_analytics, get_optimization_report, get_real_savings, and analyze_perf (for window other than "session") only see session logs that physically exist on the machine running the MCP server — they read ~/.claude/projects/<encoded-path>/ and <project>/.claw/sessions/ directly, they do not fetch data from any other machine. If you invoke them from a fresh checkout, a remote/cloud agent runtime, or a CI sandbox that never ran a local Claude Code / Claw Code session for this project, there is nothing to find and the tools report that. get_session_analytics/get_optimization_report/get_real_savings distinguish this from “checked, nothing to report” by adding a _warnings field when both the discoverable log files and the aggregated result are empty. analyze_perf with a persistent window additionally requires telemetry.enabled: true in config (off by default) and returns an explicit error when it’s off.

JSONL format differences

	Claude Code	Claw Code
Record types	`{type: "assistant"}`, `{type: "user"}`	`{type: "message"}` with `message.role`
Tool result delivery	Embedded in `user` message	Separate `tool` role message
Tool input format	JSON object	JSON string (parsed automatically)
Session metadata	`timestamp`, `sessionId` on each record	`{type: "session_meta"}` header record

MCP Tools

`get_session_analytics`

Token usage, cost breakdown by tool/server, top files, models used. Auto-syncs logs before querying.

get_session_analytics({ period?: "today" | "week" | "month" | "all" })

Returns: session count, total tokens (input/output/cache), estimated cost, breakdown by tool server (builtin, trace-mcp, jcodemunch, phpstorm, …), top tools by token output, top files by read tokens, models used.

`get_optimization_report`

Detects wasteful tool call patterns and recommends trace-mcp alternatives.

get_optimization_report({ period?: "today" | "week" | "month" | "all" })

8 built-in rules:

Rule	Severity	Detects	Recommends
`repeated-file-read`	high	Same file Read 3+ times per session	`get_outline` + `get_symbol`
`bash-grep`	high	`Bash` with grep/rg/ack commands	`search` tool
`bash-cat`	medium	`Bash` with cat/head/tail commands	`get_symbol` or `Read`
`large-file-read`	medium	`Read` with output > 5000 chars	`get_outline` → `get_symbol`
`phpstorm-read-indexed`	medium	PhpStorm file read on indexed files	`get_symbol`
`phpstorm-search-indexed`	medium	PhpStorm text search on indexed project	`search`
`unused-trace-tools`	low	Sessions without trace-mcp but with Read/Grep	Enable trace-mcp tools
`agent-for-indexed`	medium	Agent subagent calls (~50K tokens each)	`get_feature_context` / `get_task_context`

`get_real_savings`

Analyzes actual session logs to compute how much could be saved by using trace-mcp instead of raw file reads. For each Read/Bash cat/PhpStorm read, finds the file in the index and estimates the compact alternative cost.

get_real_savings({ period?: "today" | "week" | "month" | "all" })

Returns: per-file breakdown (reads, current tokens, alternative tokens, savings %), tool replacement stats, and A/B comparison (sessions with vs without trace-mcp).

`benchmark_project`

Synthetic benchmark comparing raw file reads vs trace-mcp compact responses.

benchmark_project({ queries?: number, seed?: number, format?: "json" | "markdown" })

5 scenarios: symbol lookup, file exploration, search, impact analysis, call graph. Uses actual index data with seeded randomness for reproducibility.

`get_coverage_report`

Technology profile — which dependencies are covered by trace-mcp plugins and which are not.

get_coverage_report()

Parses: package.json, composer.json, requirements.txt, pyproject.toml, go.mod, Gemfile. Classifies each dependency by category (framework/orm/ui/testing/infra/utility) and priority (high/medium/low/none). Reports covered deps, gaps, and unknowns.

`get_usage_trends`

Daily token usage trends over time.

get_usage_trends({ days?: number })

Returns daily breakdown: sessions, tokens, estimated cost, tool calls. Good for spotting cost spikes and tracking optimization progress.

`get_session_stats`

Real-time token savings of the current trace-mcp session (in-memory tracker, no log parsing).

get_session_stats()

`audit_config`

Audit AI agent config files (CLAUDE.md, .cursorrules, .claw.json, etc.) for stale references, dead paths, token bloat, scope leaks, and redundancy.

audit_config()

CLI Commands

All analytics commands are under trace-mcp analytics:

# Sync session logs into analytics DB
trace-mcp analytics sync [--full]

# Token usage report
trace-mcp analytics report [--period today|week|month|all] [--format text|json]

# Optimization recommendations
trace-mcp analytics optimize [--period today|week|month|all] [--format text|json]

# Real savings analysis
trace-mcp analytics savings [--period today|week|month|all] [--format text|json]

# Synthetic benchmark
trace-mcp analytics benchmark [--queries 10] [--seed 42] [--format text|json|markdown]

# Technology coverage
trace-mcp analytics coverage [--format text|json]

# Usage trends
trace-mcp analytics trends [--days 30] [--format text|json]

Storage

Analytics data lives in ~/.trace-mcp/analytics.db (separate from project indexes):

sessions       — one row per parsed session (tokens, model, timestamps)
tool_calls     — one row per tool call (name, server, output size, target file)
sync_state     — file paths + mtime for incremental sync

Session savings (in-memory tracker) persist to ~/.trace-mcp/savings.json.

Incremental sync

analytics sync only re-parses files whose mtime has changed since last sync. Use --full to force a complete rescan. Sync runs automatically before every analytics tool call.

Example output

`trace-mcp analytics report`

📊 Session Analytics (week)

Sessions: 24
Tool calls: 1203
Input tokens: 346,523
Output tokens: 1,200,000
Cache read: 8,500,000
Estimated cost: $61.86

Top tools:
  Read: 380 calls (~350,000 tokens)
  Bash: 290 calls (~95,000 tokens)
  Edit: 180 calls (~12,000 tokens)
  mcp__trace-mcp__search: 45 calls (~8,000 tokens)

Top files:
  src/server.ts: 35 reads (~45,000 tokens)
  src/db/store.ts: 22 reads (~32,000 tokens)

`trace-mcp analytics optimize`

🔍 Optimization Report (week)

Current usage: 1,200,000 tokens (~$6.00)

[high] repeated-file-read: 85 occurrences
  Current: 350,000 tokens → Potential: 70,000 tokens
  Savings: 280,000 tokens (80%)
  Use get_outline + get_symbol instead of reading the full file repeatedly.

[high] bash-grep: 42 occurrences
  Current: 95,000 tokens → Potential: 19,000 tokens
  Savings: 76,000 tokens (80%)
  Use trace-mcp search tool instead of Bash grep/rg.

Total potential savings: 400,000 tokens (~$2.00, 33%)

`trace-mcp analytics benchmark`

⚡ Token Efficiency Benchmark

Project: /Users/me/my-app
Index: 651 files, 3342 symbols

symbol_lookup: 41,211 → 2,098 tokens (94.9% reduction)
file_exploration: 16,366 → 762 tokens (95.3% reduction)
search: 22,860 → 8,000 tokens (65.0% reduction)
impact_analysis: 96,717 → 4,841 tokens (95.0% reduction)
call_graph: 178,661 → 10,723 tokens (94.0% reduction)
composite_task: 71,076 → 2,033 tokens (97.1% reduction)

Total: 426,891 → 28,457 (93.3% reduction)

Last updated: August 30, 2026