Metadata-Version: 2.4
Name: claude-agent-radar
Version: 0.2.0
Summary: AI Agent capability boundary diagnostic — scan Claude Code filesystem fingerprints into six-dimension maturity scores.
Project-URL: Homepage, https://github.com/millerlai/agent-radar
Project-URL: Repository, https://github.com/millerlai/agent-radar
Project-URL: Issues, https://github.com/millerlai/agent-radar/issues
Author-email: Miller Lai <miller.lai@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent,claude-code,diagnostic,maturity,radar,skill
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# 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](https://raw.githack.com/millerlai/agent-radar/main/report.en.html)
- 🇹🇼 **繁體中文** · [report.zh.html](https://raw.githack.com/millerlai/agent-radar/main/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`](https://github.com/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.

```bash
# 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:

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

If `--version` looks older than the [latest PyPI release](https://pypi.org/project/claude-agent-radar/),
upgrade with `pipx upgrade claude-agent-radar` or `uv tool upgrade claude-agent-radar`.

### Install the coach skill (optional but recommended)

```bash
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):

```bash
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:

```bash
# 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:

```bash
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)**

```bash
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:

```bash
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:

```bash
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:

```bash
# 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

```bash
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](LICENSE).

Copyright 2026 Miller Lai.
