claude-agent-radar 0.2.0

AI Agent capability boundary diagnostic — scan Claude Code filesystem fingerprints into six-dimension maturity scores.

agent-radar · Activation Gap Diagnostic for Claude Code

The one thing this tool does that nothing else can: it sees both what you configured on disk AND what actually fires inside your Claude Code sessions — and the gap between the two is your improvement headroom.

• agent-radar scan reads filesystem fingerprints → configured side of five axes
• agent-radar session reads local ~/.claude/projects/*.jsonl → activated side of the same axes
• agent-radar merge + agent-radar report → HTML showing the activation gap

The companion /agent-radar-coach skill (install via agent-radar install-skill) walks you through closing the biggest gaps one at a time, evidence-driven, ask-before-edit.

See a sample report

Sample reports rendered from a real repo are checked into this repo — GitHub doesn't preview HTML inline, so view them through a CDN:

• 🇬🇧 English · report.en.html
• 🇹🇼 繁體中文 · report.zh.html

Each shows the dual-track radar, the bidirectional Top Gaps (click each row to expand the underlying configured + activated findings), and per-target detail.

Core Idea

Most "Claude Code health" tools stop at "did you write a CLAUDE.md?" That's fingerprint detection — necessary but not interesting. What's interesting is that plenty of people write a thorough CLAUDE.md and install five MCP servers, but nothing in those configs gets exercised during real sessions. That gap is what agent-radar visualizes — two overlaid radar polygons make it obvious.

agent-radar does NOT try to grade the quality of your CLAUDE.md — heuristics like "count of imperative verbs" don't actually measure quality, they just pretend to. Quality judgement is interpretive and lives in the coach skill, where Claude can read the content and reason about it.

Five Axes

For each axis, scan produces a Configured score (0–100) and session produces an Activated score (0–100). The gap is improvement headroom.

Axis	Configured (scan)	Activated (session)
claude_md	Presence, size, @import refs, iteration evidence (git commits + content patterns like "lessons learned / do not repeat / dated rules")	(1 - correction_rate) × 100 — low correction rate = CLAUDE.md is guiding effectively
skills	SKILL.md count + lint hygiene (frontmatter compliance, no ASCII-art banners, size limits)	Skill tool dispatch count × 10
mcp	Configured server count + category breadth (data / saas / cloud / search / files)	mcp__* tool call count × 8
automation	Hooks, subagents, custom commands, plugins (fact counts)	Agent tool dispatches × 10 (hooks/commands aren't visible in JSONL)
context_hygiene	User/project split + settings.local.json gitignore + @import modularization	Blend: (1 - read_repeat_rate) × 50 + @-mention_rate × 50

Lint signals are borrowed from felixgeelhaar/cclint and the agentskills.io Skill Linter (required frontmatter fields, line-count limits, ASCII-art / decorative-content detection, oversized-CLAUDE.md warnings), reimplemented in pure Python — no external dependencies.

Migrating from 0.1.x? The iteration dimension is gone — folded into claude_md as a fact-based sub-signal (git commit count + content-regex patterns). The 0-100 "overall maturity" score is also gone; the same number still exists but is now framed as "Configured Coverage" not "Maturity". Heuristic sub-checks (imperative-pattern count, structure-headers-score, word-count concise bucket, skills description quality grade) were removed — they pretended to measure quality the CLI cannot actually evaluate.

Install

Prerequisites: Python 3.8+ (standard library only — zero external deps).

Option A · Install from PyPI (recommended)

The PyPI distribution name is claude-agent-radar (PyPI rejected the shorter agent-radar because of a name collision with an unrelated package). The CLI command and module are still agent-radar and agent_radar respectively.

The two recommended install methods put agent-radar.exe on your PATH automatically — no manual edits needed.

# Recommended · pipx (works out-of-the-box on every OS)
pipx install claude-agent-radar

# Recommended · uv tool (if you already use uv)
uv tool install claude-agent-radar

# Inside an activated virtualenv
python -m venv .venv
.venv\Scripts\activate           # Windows
source .venv/bin/activate        # macOS / Linux
pip install claude-agent-radar

# Editable install while hacking on the source
git clone https://github.com/millerlai/agent-radar
cd agent-radar
pip install -e .

After install, verify:

agent-radar --version   # prints e.g. `agent-radar 0.1.3`
agent-radar --help

If --version looks older than the latest PyPI release, upgrade with pipx upgrade claude-agent-radar or uv tool upgrade claude-agent-radar.

Install the coach skill (optional but recommended)

agent-radar install-skill

This copies the bundled Claude Code skill into ~/.claude/skills/agent-radar-coach/. Open any Claude Code session and invoke /agent-radar-coach — it walks you through your scan / session results and applies targeted fixes one at a time (evidence-driven, ask-before-edit). Re-run with --force to overwrite an existing copy, or --dest <dir> to install elsewhere.

If pipx / uv tool install succeeded but agent-radar is still command not found, your shell hasn't picked up the tool-bin dir yet — run pipx ensurepath or uv tool update-shell, then reopen the shell.

⚠️ Avoid pip install --user claude-agent-radar on Windows. The executable lands in %APPDATA%\Python\Python3XX\Scripts\, which is not on PATH by default, so agent-radar will print command not found immediately after install. Use pipx instead.

If for any reason the CLI isn't on PATH, python -m agent_radar is a drop-in replacement (same arguments):

python -m agent_radar --help
python -m agent_radar scan ...     # same args as `agent-radar scan ...`

Option B · Install as a Claude Code skill (recommended for daily use)

The repo itself is a Claude Code skill (the root contains SKILL.md). Copy it into your user-space skills directory:

# macOS / Linux / Cygwin
cp -r /path/to/agent-radar ~/.claude/skills/agent-radar

# Windows PowerShell
Copy-Item -Recurse C:\path\to\agent-radar $env:USERPROFILE\.claude\skills\agent-radar

After that, in any Claude Code session, just say something like the following — Claude will load the skill and walk you through the scan:

• "audit my Claude Code maturity"
• "scan this repo's Claude Code setup"
• "find the blind spots in my agent config"
• "benchmark our team's Claude Code adoption"

The skill invokes the same agent-radar CLI, so the package must be installed first (pipx install claude-agent-radar is the path of least resistance), or you must launch it via python -m agent_radar from inside the skill directory.

Run

30-second quick start

Scan the current repo + your user-space, generate the full HTML report including the actual-usage radar. Run from the repo you want to scan:

agent-radar scan --include-home . -o scan.json
agent-radar session -o session.json
agent-radar report scan.json --session session.json -o report.html

# Open the report
open report.html        # macOS
xdg-open report.html    # Linux
start report.html       # Windows (PowerShell / cmd)

If agent-radar is not found, swap every agent-radar for python -m agent_radar (same arguments). See the install notes above.

Subcommands

Subcommand	Purpose
agent-radar scan	Scan filesystem fingerprints (six config dimensions)
agent-radar session	Scan local ~/.claude/projects/*.jsonl for actual-usage metrics
agent-radar report	Build single-file HTML radar report
agent-radar usage	Score OTel events into usage.json
agent-radar merge	Merge scan.json + usage.json into merged.json

Each subcommand has its own --help. Long form: python -m agent_radar <sub> ....

Three scan scenarios

Scenario 1 · Single repo (simplest)

agent-radar scan /path/to/repo -o scan.json
agent-radar report scan.json -o report.html

Scenario 2 · Personal full-body scan (includes user-space)

Pulls ~/.claude/ into the scan so you can see user-level vs project-level config separation:

agent-radar scan --include-home /path/to/repo -o scan.json
agent-radar report scan.json -o report.html

Scenario 3 · Team benchmark (multi-repo)

Scan many repos at once. The report auto-generates a ranking table:

agent-radar scan /repos/a /repos/b /repos/c -o scan.json
agent-radar report scan.json -o report.html

Add actual-usage measurement (full two-layer analysis)

agent-radar session reads local ~/.claude/projects/*.jsonl and emits usage metrics — actual tool invocations, Skill firings, MCP calls, and user-correction rate. Pair it with agent-radar report --session to get a second radar in the HTML:

# 1. Scan all projects (defaults to ~/.claude/projects/)
agent-radar session -o session.json

# Or restrict to specific repos
agent-radar session /path/to/repo -o session.json

# 2. Cygwin / cross-OS: point at the actual projects dir
agent-radar session --projects-dir /c/Users/<you>/.claude/projects -o session.json

# 3. Build the two-layer radar report
agent-radar report scan.json --session session.json -o report.html

Output files

File	Produced by	Contents
scan.json	agent-radar scan	Config completeness: six dimension scores + per-signal detail
session.json	agent-radar session	Actual usage: per-project tool calls, Skill / MCP triggers, correction rate
report.html	agent-radar report	Single-file, offline-viewable HTML report with radars + ranking + accordions

Full CLI flags

agent-radar --help                  # list subcommands + version
agent-radar scan --help             # paths, --include-home, -o
agent-radar session --help          # paths, --projects-dir, -o
agent-radar report --help           # input, --session, --merged, --lang, -o
agent-radar usage --help            # --otel-log, --scan, --target, --account, ...
agent-radar merge --help            # scan.json, usage.json, -o

Limitations

• Only effective for targets you have filesystem access to (your own / your team's repos).
• For strangers with only code or a conversation, reliable detection is impossible, and it edges into the gray area of surveilling others — not recommended.
• agent-radar session only reads local JSONL; cross-machine measurement needs OpenTelemetry (agent-radar usage).
• Correction rate is matched on literal patterns (no/don't/stop/不對/還原…); semantic corrections (a long explanation of why Claude was wrong) are not detected.
• The scoring weights are tunable heuristics — calibrate them against your team's reality before doing cross-person comparisons.

License

Apache License 2.0 — see LICENSE.

Copyright 2026 Miller Lai.