Claude Code context and token management — official-docs-first, self-contained.
Status: v0.0.6 · public alpha — ships across four surfaces (CLI · MCP server · Claude Code plugin · slash-command skill), validated against the latest official specs (MCP
2025-11-25, Claude Code2.1.114).Honest coverage (per the blog that motivates this project): Clarity v0.0.6 addresses ~30% of the branch-point decisions the blog names. Statusline covers
continue / /clear / /compactreasoning via ctx% and cache-age./rewind, subagent suggestions, and task-switch detection are NOT yet implemented — see Roadmap and the gap table below.
Anthropic's own session-management blog identifies five decisions you face at every turn (continue, /rewind, /clear, /compact, subagents) and two main failure modes: context rot past ~300-400k tokens, and bad /compact when the model summarizes without knowing your next step.
Most Claude Code users pay these taxes silently. Claude Code doesn't warn you before a bad /compact. It doesn't tell you your cache just expired. It doesn't flag a check X prompt about to balloon into a 800M-token session.
And the real driver — poor .claude/ project structure — forces every session to re-explore the same codebase, burning tokens on work the structure should have prevented.
Clarity does three things today, all built from Anthropic's own official guidance:
- Doctor — read your session logs, your
~/.claude/and project.claude/config, your plugins and rules. Report where the tokens actually go. Recommend fixes only from official docs. - Install — set up Clarity itself in Claude Code through the plugin, CLI, MCP, and statusline surfaces. Project-specific
.claude/scaffolding is planned, but it is not shipped inv0.0.6. - Run with you — sit quietly in the statusline. Warn before cache expires, before bad
/compact, before a known trap prompt. One suggestion, one keystroke to accept.
- Run your prompts through its own servers
- Obfuscate or minify its source
- Require an external account
- Invent rules not in Anthropic's official docs
Clarity ships in four interchangeable forms. Install one or all — they share the same analyzer under the hood.
bash -lc '
set -euo pipefail
dir="$HOME/.claude/clarity"
repo="https://github.com/agent-next/clarity.git"
ref="v0.0.6"
if [ -d "$dir/.git" ]; then
git -C "$dir" fetch --tags origin
elif [ ! -e "$dir" ]; then
git -c advice.detachedHead=false clone --depth 1 --branch "$ref" "$repo" "$dir"
else
echo "$dir exists but is not a git checkout" >&2
exit 1
fi
CLARITY_REPO_REF="$ref" "$dir/install.sh"
'This installs Clarity into ~/.claude/clarity, validates the plugin, registers the local marketplace, and installs clarity@clarity so Claude Code can use /clarity-doctor. The install flow is git-based instead of depending on a raw-content endpoint, so it works with the same repo access you already use for git clone.
Manual fallback:
git -c advice.detachedHead=false clone --depth 1 --branch v0.0.6 https://github.com/agent-next/clarity.git ~/.claude/clarity
CLARITY_REPO_REF=v0.0.6 ~/.claude/clarity/install.shThe plugin ships:
/clarity-doctor [days]slash command- Skill frontmatter with
when_to_useandeffort: lowso Claude invokes it at the right moment - Plugin cache path:
~/.claude/plugins/cache/clarity/clarity/0.0.6/
Verify:
claude plugin list | grep clarityThe CLI works with or without the plugin — useful for scripting, CI, or cron jobs. If you used the recommended install above, the repo checkout already lives at ~/.claude/clarity.
# Symlink once for a short PATH entry
ln -s ~/.claude/clarity/bin/clarity /usr/local/bin/clarity
clarity doctor --since-days 30
clarity doctor --since-days 7 --json
clarity version
clarity helpExpose clarity_doctor as an MCP tool to any compliant client (Claude Code, Claude Desktop, other agents).
Add to your project's .mcp.json:
{
"mcpServers": {
"clarity": {
"command": "python3",
"args": ["/Users/you/.claude/clarity/mcp/server.py"]
}
}
}Protocol: JSON-RPC 2.0 over stdio, MCP spec 2025-11-25. Exposes one tool (clarity_doctor) with a single since_days parameter and returns the same Markdown doctor report as the CLI. No external account, no telemetry.
Append to your ~/.claude/statusline-command.sh:
# your existing statusline output first ...
clarity=$(printf '%s' "$input" | sh "$HOME/.claude/clarity/scripts/clarity-status.sh" 2>/dev/null)
[ -n "$clarity" ] && printf ' · %b' "$clarity"Output example:
main · opus 4.7 · ctx 12% · ● cache 42m · ctx 12% · OK to continue
└── Clarity's status ────────────────┘
Degrades gracefully: if the session jsonl isn't yet flushed, the cache Xm field is omitted and only ctx + traffic light show.
- Estimated 30-day cost using correct Opus 4.7 pricing (cache_read at 0.1x, not 1x — the common DIY-analyzer mistake that makes rankings unreliable)
- Top cost-concentration project (often one project dominates 80%+)
- Top 10 most expensive sessions with the first prompt that triggered each — this is where scope creep started
- Cache read/write ratio — flags if you're paying to rebuild cache too often
- 2-3 concrete recommendations citing official Anthropic docs only
| Dot | Meaning | Suggestion shown |
|---|---|---|
| 🟢 green | ctx < 25%, cache warm or unknown | OK to continue |
| 🟡 yellow | ctx 25-40%, or cache expired | fine for now or cache expired · /clear is cheap now |
| 🔴 red | ctx ≥ 40% | /compact with focus or /clear with handoff |
The cache Xm field shows minutes until prompt cache expires (60m with ENABLE_PROMPT_CACHING_1H=1, else 5m). Knowing this prevents bad /compact decisions mid-session.
| Tool | Mechanism | Auditable? | Account? | Approach |
|---|---|---|---|---|
| wozcode | Opaque hooks + obfuscated JS | No | Yes | Do it for you |
| kieranklaassen/token_analysis.py | Python log analyzer | Yes | No | Measure only |
| Clarity | Shell/Python, zero runtime deps | Yes | No | Measure + guide + install |
Clarity's reason to exist is the Anthropic blog Using Claude Code: Session Management & 1M Context. A local reference copy also lives at docs/Using Claude Code Session Management & 1M Context.md. Every feature is measured against it. Current coverage:
| Blog concept | Clarity v0.0.6 | Gap |
|---|---|---|
| 1M context awareness | Statusline ctx N% + Doctor historical |
✓ |
| Context rot ~300-400k | Statusline red at 40% used (= 400k on 1M) | ⚠ threshold is %-based, not token-absolute — misleads on non-1M models |
continue decision |
Green dot + OK to continue |
✓ |
/clear decision |
Yellow/red cues when cache expired or ctx high | ✓ |
/compact decision |
Red cue at ctx ≥ 40% | ⚠ no PreCompact steering hook (/compact focus on X) |
/rewind decision |
— | ✗ not implemented |
| Subagent decision | — | ✗ no "tool output heavy → spin subagent" hint |
| Task-switch detection | — | ✗ biggest blog ask, requires semantic diff of prompts |
| Bad-compact prevention | Proactive red cue only | ⚠ no PreCompact hook to steer auto-compact |
/handoff brief generation |
— | ✗ v0.0.7 |
v0.0.6 is honest about the ~30% coverage. Doctor + statusline solve the measurement and basic-awareness half. The per-turn decision support half (rewind, subagent, task-switch) is still future work.
- v0.0.1 — scaffold ✓
- v0.0.2 — Doctor + statusline + plugin manifest ✓
- v0.0.3 — CLI + MCP server, latest spec alignment ✓
- v0.0.4 — codex-audited hardening: symlink-safe CLI, robust jq parsing, cache TTL JSON parse, timezone-aware date filters, honest blog-coverage table
- v0.0.5 — one-line installer (
install.sh), checked-in smoke tests, fail-closed statusline behavior, unified release metadata across CLI/plugin/MCP, and real Claude Code install/update verification - v0.0.6 — (this release) public-repo cleanup: self-contained docs, git-based install guidance, and release checks that verify the documented install path
- v0.0.7 —
/rewind+ subagent guidance in statusline; PreCompact hook that asks "what's next?" before auto-compact fires - v0.0.8 — task-switch detection (keyword diff of recent prompts);
/handoffskill generates brief to.claude/handoffs/ - v0.0.9 —
clarity installCLI: scaffolds project.claude/from Doctor findings in one command
MIT. See LICENSE.