claude-agent-radar 0.1.0__tar.gz

claude_agent_radar-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Claude Code 個人/本機設定 (不應共享)
+.claude/settings.local.json
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+venv/
+
+# Build artifacts (hatchling / pip / uv)
+build/
+dist/
+*.egg-info/
+
+# Local-only credentials for one-off publishes (never committed)
+_token_*.txt
+
+# 掃描輸出 (本機產物,保留 sample-scan.json + report.html 作示範)
+scan.json
+session.json
+usage.json
+merged.json
+report-merged.html
+report-session.html
+test-*.json
+test-*.html

claude_agent_radar-0.1.0/CLAUDE.md

@@ -0,0 +1,65 @@
+# CLAUDE.md
+
+Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+---
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

claude_agent_radar-0.1.0/LICENSE

@@ -0,0 +1,200 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may accept support,
+      warranty, indemnity, or other liability obligations and/or rights
+      consistent with this License. However, in accepting such obligations,
+      You may, on Your own behalf and on Your sole responsibility, not on
+      behalf of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Miller Lai
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

claude_agent_radar-0.1.0/PKG-INFO

@@ -0,0 +1,291 @@
+Metadata-Version: 2.4
+Name: claude-agent-radar
+Version: 0.1.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 · AI Agent Capability Boundary Diagnostic
+
+Detects the *capability boundary* of how an individual or a team uses the Claude Code
+ecosystem. It scans filesystem fingerprints and quantifies a person's mastery of
+CLAUDE.md, skills, MCP, hooks, subagents, and so on into six dimensions of maturity
+score (0–100), then outputs an HTML radar-chart report.
+
+**Two-layer measurement:**
+
+- `agent-radar scan` measures *configuration completeness* (static fingerprints, six config dimensions)
+- `agent-radar session` reads local `~/.claude/projects/*.jsonl` to measure *actual usage*
+  (which tools, Skills, MCP servers actually fire, plus user correction rate)
+
+The gap between the two is the most concrete improvement checklist. The repo itself
+is also a Claude Code skill (see `SKILL.md`) — drop it into `~/.claude/skills/agent-radar/`
+and it works out of the box.
+
+## Core Idea
+
+How well someone uses Claude Code gets imprinted into their filesystem and session
+logs. This tool reads those fingerprints rather than monitoring conversation content.
+
+- **Configuration completeness** (static) reflects how much you've *written down*: CLAUDE.md, skills, MCP.
+- **Actual usage** (dynamic) reflects whether those configs *actually fire* during sessions.
+
+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 exactly what
+agent-radar visualizes — two overlaid radar polygons make it obvious.
+
+## Six Config Dimensions (agent-radar scan)
+
+| Dimension | What it detects |
+|---|---|
+| CLAUDE.md maturity | Presence, user/project layering, structured sections, imperative tone, concision, `@import` modularization, **size lint** |
+| Skills usage | Whether skills exist, SKILL.md `description` trigger quality, progressive disclosure, **frontmatter & token-hygiene lint** |
+| MCP integration | Number of MCP servers and breadth of types (data / saas / cloud / search / files) |
+| Automation | hooks, subagents, custom slash commands, plugins |
+| Context hygiene | user/project settings separation, shared vs. personal config distinction (gitignore), modular references |
+| Iteration & maintenance | Whether configs have been repeatedly tuned over time (via git history) |
+
+**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). They are
+reimplemented in pure Python — no external dependencies.
+
+The total score maps onto five levels: L0 (unaware) → L4 (mastery).
+
+## Six Usage Dimensions (agent-radar session)
+
+| Dimension | What it measures |
+|---|---|
+| tool_diversity | How many distinct tools have been called in the session |
+| skill_triggered | How many times the `Skill` tool actually fired (signal that skill descriptions trigger) |
+| mcp_triggered | How many `mcp__*` tool calls happened (signal that MCP is really used) |
+| low_correction | Rate of corrective user messages (inverted — lower is better) |
+| context_efficiency | Rate of repeated reads of the same file in one session (inverted) |
+| session_volume | Session count and message volume (exposure baseline) |
+
+## Install
+
+**Prerequisites**: Python 3.8+ (standard library only — zero external deps).
+
+### Option A · Install from PyPI / source (recommended)
+
+Works with `pip`, `uv`, and `poetry`. After install, verify the command
+is on your `PATH`:
+
+```bash
+agent-radar --help
+```
+
+If the verify step prints help, you're done. If it fails with
+`command not found`, see **"`agent-radar` not on PATH?"** below — the
+module form `python -m agent_radar` always works as a drop-in
+replacement.
+
+```bash
+# pip (system / venv)
+pip install agent-radar
+
+# pip --user (no admin needed; see PATH note below on Windows)
+pip install --user agent-radar
+
+# uv
+uv pip install agent-radar
+# or, as a uv-managed tool (handles PATH for you)
+uv tool install agent-radar
+
+# pipx (isolated env, handles PATH for you — recommended on Windows)
+pipx install agent-radar
+
+# poetry
+poetry add agent-radar
+
+# Local / editable install while hacking on the source
+git clone <repo-url> agent-radar
+cd agent-radar
+pip install -e .
+agent-radar --help
+```
+
+#### `agent-radar` not on PATH?
+
+Two common causes:
+
+1. **`pip install --user` on Windows** drops `agent-radar.exe` into
+   `%APPDATA%\Python\Python3XX\Scripts\`, which is **not** on `PATH` by
+   default. Either add that folder to `PATH`, or reinstall via
+   `pipx install agent-radar` / `uv tool install agent-radar` — both
+   wire up the entry point automatically.
+2. **Using a venv that isn't activated** — activate it, or call the
+   binary by its full path.
+
+In all cases, this module form is a drop-in replacement that needs no
+PATH setup:
+
+```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
+`pip install`-ed first (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
+[**`agent-radar` not on PATH?**](#agent-radar-not-on-path) 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.