Claude Code and other AI coding assistants silently eat your context window before the conversation even starts.
Two sources dominate the bleed:
MCP tool schemas. A typical multi-server configuration loads all tool schemas upfront. Anthropic's own documentation puts this at approximately 55,000 tokens before Tool Search kicks in — and Tool Search only applies to MCP tools, not to skills or CLAUDE.md files. (confirmed: platform.claude.com)
Skill descriptions. Every installed skill has its description and when_to_use injected into the system context at session start. There is no lazy-loading equivalent for skills — ToolSearch does not cover user-defined skills. Users with 60+ skills report approximately 15–20k tokens of description overhead per session. (confirmed issue: github.com/anthropics/claude-code/issues/36023; token count is user-reported)
Neither Claude Code nor any other tool in the ecosystem today gives you a ranked breakdown of what is consuming your context budget and by how much. You are flying blind.
agentctx scan analyzes your Claude Code configuration and reports what's consuming context budget:
$ agentctx scan
agentctx scan — context budget report
──────────────────────────────────────────────────
Source Tokens % Budget
──────────────────────────────────────────────────
MCP schemas (12 servers) 54,892 44.2%
Skills / commands (67 files) 18,341 14.8%
CLAUDE.md files (3) 2,104 1.7%
Tools baseline 8,192 6.6%
──────────────────────────────────────────────────
Total context consumed 83,529 67.3%
Available for conversation 40,471 32.7%
──────────────────────────────────────────────────
Top contributors:
1. mcp:filesystem 12,340 tokens (remove or trim?)
2. mcp:github 9,821 tokens
3. skills/feishu.md 3,201 tokens (low usage signal)
| agentctx | Microsoft APM | |
|---|---|---|
| Focus | Context budget visibility & optimization | Agent workflow orchestration & monitoring |
| Target | Developer CLI tool for Claude Code config | Enterprise agent management platform |
| Scope | Static analysis of context sources | Runtime agent lifecycle management |
The roadmap follows a build track (sequential, dependency-ordered) plus a continuous Research & Ecosystem Watch track. See .backlog/docs/research/19-roadmap-v2.md for the full design.
| Milestone | Description | Status |
|---|---|---|
| M0 Foundation & Research | Vision, ACG vocabulary seed, research baseline | ✅ Done |
| M1 Context Scanner / Bundle Analyzer | agentctx scan — measure context contributors, no LLM, CI-runnable |
✅ Done |
| M2 Context Analysis Foundation | Content-aware tokenizer, stable schema, graph.json, source-map, search, cache, skill lint, efficiency badge | ✅ Done |
| M3 Cross-runtime Context Compiler | agentctx compile — RuntimeAdapter + cheap/accurate/cache-aware strategies (deep IR compiler in progress) |
✅ Core done |
| M4 MCP Auditor & Supply-Chain Security | MCP risk scoring, secret/injection/hook scans, threat model, lockfile enforcement | ○ Next |
| M5 Profile Resolver & PGO | agentctx.json, profiles, tree-shaker, profile-guided optimization |
○ Planned |
| M6 Lifecycle Compression & Eval | keep/compress/hide/disable/rewrite, compression eval harness, benchmark | ○ Planned |
| M7 Telemetry / Runtime Attribution | Session traces feed source-map utility fields, runtime cost attribution | ○ Planned |
| M8 DevTools / Registry / Ecosystem | Badge registry, MCP search adapter, multi-target emitters, GUI | ○ Planned |
| M-R Research & Ecosystem Watch | Continuous: competitor monitoring, ecosystem-format tracking, research ingestion | ⟳ Ongoing |
pnpm add -g @agentctx/cli
agentctx scanagentctx scan reads your ~/.claude/ configuration, measures the token cost of each context source (MCP servers, skill files, CLAUDE.md), and prints a ranked report so you can make informed decisions about what to keep, trim, or remove.
Want to see the output before running it? examples/report/ contains a real report.md / report.json / graph.json generated by running agentctx scan against the bundled fixtures/sample-project fixture, with the exact command to reproduce it.
Run agentctx scan on every PR, upload the report as an artifact, and fail the build over a token budget — see docs/ci.md and the example workflow at .github/workflows/agentctx-scan.yml.
See CONTRIBUTING.md for local setup, good first issues, and PR guidelines.