# ContextAnalyzerTerminal

> 📊 Per-tool-call context window analyzer for Claude Code

- **Type:** MCP server
- **Install:** `agentstack add mcp-roeimichael-contextanalyzerterminal`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [roeimichael](https://agentstack.voostack.com/s/roeimichael)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [roeimichael](https://github.com/roeimichael)
- **Source:** https://github.com/roeimichael/ContextAnalyzerTerminal

## Install

```sh
agentstack add mcp-roeimichael-contextanalyzerterminal
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

Know exactly which tool call ate your context window.

  
  
  
  
  
  

---

Claude Code shows you total token usage -- but not *which* tool call caused the spike. Was it that `Bash` command that ran a find on your entire repo? The `Read` that loaded a 3,000-line file? CAT answers that question in real time.

It hooks silently into your Claude Code sessions, tracks token cost **per tool call**, builds rolling baselines, and fires an alert the moment something anomalous hits -- with a plain-language explanation of *why*.

  

  

## Quick Start

```bash
git clone https://github.com/roeimichael/ContextAnalyzerTerminal.git
cd ContextAnalyzerTerminal
uv sync                         # install deps (Python 3.11+ and uv required)
uv sync --extra classifier      # optional: LLM root-cause analysis (~$0.0001/event)

context-analyzer-tool install   # inject hooks into Claude Code
context-analyzer-tool serve     # start the collector (keep this running)
context-analyzer-tool dashboard # open the live TUI
```

That's it. Use Claude Code normally -- CAT tracks everything in the background.

## Why CAT?

Claude Code's built-in `/cost` and `/context` commands show snapshots -- no trends, no per-tool attribution, no cache TTL awareness. CAT fills that gap:

- You'll know which tool type consistently burns the most tokens in your workflow
- You'll get warned *before* your context fills, with actionable suggestions (`/compact`, `/clear`)
- You'll stop guessing and start optimizing

## What You Get

| Feature | What it does |
|:--------|:-------------|
| **Per-tool-call tracking** | See exactly how many tokens each Read, Bash, Grep, etc. costs |
| **Rolling baselines** | Learns normal cost per task type using Welford's algorithm |
| **Anomaly detection** | Flags tool calls that exceed baseline by configurable Z-score |
| **Root-cause analysis** | Haiku classifier explains *why* in plain language |
| **Context cost breakdown** | See fresh-session vs current overhead ratio |
| **Live dashboard** | Rich TUI with sessions, cost timeline, and anomaly feed |
| **Notifications** | Statusline badges, system alerts, Slack/Discord webhooks |
| **Multi-session** | Tracks concurrent Claude Code sessions independently |

## CLI Reference

```
context-analyzer-tool install         Install hooks into Claude Code
context-analyzer-tool uninstall       Remove hooks from Claude Code
context-analyzer-tool serve           Start the collector server
context-analyzer-tool dashboard       Launch the live TUI dashboard
context-analyzer-tool status          View active sessions and recent tasks
context-analyzer-tool anomalies       List recent anomalies with root causes
context-analyzer-tool context-cost    Show context cost breakdown
context-analyzer-tool health          Collector health check
context-analyzer-tool rtk-status      Show RTK integration status and savings
context-analyzer-tool prune           Clean up old data
context-analyzer-tool clear           Clear all stored data and start fresh
```

## Configuration

Config lives at `~/.context-analyzer-tool/config.toml` (created automatically on first `install`). Every setting can be overridden with environment variables using the `CAT_` prefix.

```toml
[collector]
host = "127.0.0.1"
port = 7821

[anomaly]
z_score_threshold = 2.0      # Std devs above mean to flag
min_sample_count = 5          # Data points before detection kicks in
cooldown_seconds = 60         # Debounce duplicate alerts

[classifier]
enabled = true                # Requires: uv sync --extra classifier
model = "claude-haiku-4-5-20251001"

[notifications]
statusline = true             # Badge in Claude Code statusline
system_notification = true    # OS notifications (macOS/Linux)
in_session_alert = true       # In-session alert messages
webhook_url = ""              # Slack/Discord webhook
```

Environment variable overrides:
```bash
CAT_COLLECTOR_PORT=8080
CAT_ANOMALY_Z_SCORE_THRESHOLD=3.0
CAT_CLASSIFIER_ENABLED=false
```

## How It Works

Claude Code hooks don't include token counts. CAT correlates two data streams:

1. **Hook events** (PostToolUse, SubagentStop, Stop, etc.) carry tool metadata
2. **Statusline snapshots** provide real-time token counts

The delta engine matches them by session ID + timestamps to compute per-call costs. Anomalies are detected via Z-score over a rolling 20-sample window per task type, then classified by Haiku.

```
Hooks + Statusline → Collector → Delta Engine → Anomaly Detection → Classifier → Notifications
                                       │
                                   SQLite DB
                                       │
                                   Dashboard
```
## Contributing

We welcome contributions! Check out our **[Good First Issues](https://github.com/roeimichael/ContextAnalyzerTerminal/labels/good%20first%20issue)** for beginner-friendly tasks with clear guidance.

```bash
uv sync --all-extras          # Install with dev + classifier deps
uv run pytest tests/ -v       # Run full test suite
uv run ruff check src tests   # Lint
uv run pyright                # Type check (strict mode)
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for architecture overview, reading order, and contribution guidelines.

## Tech Stack

**FastAPI** + **Uvicorn** (async collector) -- **SQLite** + **aiosqlite** (persistence) -- **Pydantic** (validation) -- **Typer** + **Rich** (CLI/TUI) -- **Anthropic SDK** (optional classifier)

## License

[MIT](LICENSE)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [roeimichael](https://github.com/roeimichael)
- **Source:** [roeimichael/ContextAnalyzerTerminal](https://github.com/roeimichael/ContextAnalyzerTerminal)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-roeimichael-contextanalyzerterminal
- Seller: https://agentstack.voostack.com/s/roeimichael
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.