Lighthouse for AI agent development environments
A CLI tool that analyzes Claude Code users' MCP servers, plugins, and skill environments — scoring them and suggesting improvements.
Claude Code environments have grown as complex as Kubernetes clusters, yet there's no equivalent of kubectl describe to diagnose them.
| Problem | Description |
|---|---|
| No visibility | No way to know if your setup is healthy |
| Unknown gaps | Critical tools may be missing without you knowing |
| Hidden conflicts | 3 of your 20 plugins might be conflicting |
| Context waste | No idea which tools are silently burning context |
Other Claude Code health-checkers exist — agentscore's edge is in how it scores:
- Explainable, reproducible scoring. Every deduction maps to a documented reason, and the score is a pure, deterministic function of your config — same setup, same score, no LLM in the loop. The grade boundaries ship with a reproducible verification sweep:
python scripts/score_distribution.py. - Capability-level analysis. Each tool is classified by the capability it provides, so redundant overlap and role mismatches get flagged — not just whether a setting is toggled.
- Decisions before you install.
agentscore check <url>estimates a tool's score impact before you add it.
Scope, known limits, the competitive landscape, and the roadmap are collected in docs/DIFFERENTIATION.md.
Install from source (recommended — includes the current scoring model):
git clone https://github.com/calintzy/agentscore
cd agentscore
pip install -e .Or from PyPI (v0.1.2 — predates the recalibrated scoring; a new release will follow):
pip install agentscore-cliRequirements: Python 3.11+, Claude Code installed
# Instant scan (auto-detect profile)
agentscore
# Specify role explicitly
agentscore --profile backend
# JSON output
agentscore --json
# No color (for CI environments)
agentscore --no-color
# Simulate impact before installing a new tool
agentscore check https://github.com/upstash/context7
# View score history
agentscore history
# Compare against a previous snapshot
agentscore diff
agentscore diff 2026-05-01
# Save profile setting
agentscore setup
# Show version
agentscore --version| Dimension | Points | Description |
|---|---|---|
| Context Efficiency | 25 | Substantive instructions plus role-fit tools, minus dead-weight tools burning context |
| Coverage | 20 | Capability coverage for your role (breadth of useful capabilities for generic) |
| Tool Hygiene | 20 | Specialized tools earn points; redundant tools providing the same capability deduct |
| Config Quality | 15 | An explicit model setting and a real global CLAUDE.md |
| Security | 10 | Dangerous permission patterns scored by severity — any critical pattern (a blanket Bash(*)) caps this dimension at half |
| Freshness | 10 | How recently your plugins have been maintained |
| Grade | Score | Meaning |
|---|---|---|
| S | 90-100 | Optimized environment |
| A | 78-89 | Well configured, minor gaps |
| B | 58-77 | Basics in place, room to improve |
| C | 38-57 | Significant gaps |
| D | 0-37 | Needs reconfiguration |
agentscore scores what you've earned, not the mere absence of problems. An empty setup lands in D, not A — because there's nothing good to reward.
- Three earned dimensions (Context Efficiency, Coverage, Config Quality — 60 pts) start at zero and build up as you add substantive instructions, tools that fit your role, and intentional configuration.
- Three hygiene dimensions (Tool Hygiene, Security, Freshness — 40 pts) start from a neutral floor and lose points for redundancy, risky permissions, or staleness.
Every score is a pure, deterministic function of your local config files: the same setup always yields the same number, with no network calls and no LLM in the loop.
Why these weights? Context budget is the scarcest resource in an agent environment, so Context Efficiency carries the most (25). Coverage and Tool Hygiene (20 each) are two sides of the same question — the right tools, and no redundant ones. Config Quality (15) signals an intentional setup. Security and Freshness (10 each) are high-impact when violated but otherwise rare or weak signals, kept lower so a clean setup isn't over-rewarded — real problems still surface as issues.
Measures "how intentionally are you using this?" from config files alone — no log parsing.
| Signal | Priority |
|---|---|
| Directly mentioned in CLAUDE.md | High |
Activated in enabledPlugins |
Medium |
Registered in enabledMcpjsonServers |
Medium |
Configured in mcp.json |
Medium |
| Installed but nowhere else | Low |
agentscore # Tier 0: generic (instant, no profile)
agentscore --profile backend # Tier 1: role-based evaluation
agentscore setup # Save role → applied automatically afterwardsSupported roles: backend, frontend, fullstack, ml, devops
Without a profile, agentscore auto-detects from file patterns in the current directory (many .py files → backend/ml, package.json → frontend, Dockerfile + k8s manifests → devops).
Analyze the impact of a new GitHub project before installing it.
$ agentscore check https://github.com/some-org/some-tool
agentscore check — some-org/some-tool
⭐ 1,234 stars 📄 MIT 🟢 Recently updated
✅ Installation recommended +3.0pts improvement expected
Score prediction: 82.0 → 85.0 (+3.0)
Dimension Before After Delta
Context Efficiency 17.0 17.0 —
Coverage 20.0 20.0 —
Tool Hygiene 12.0 14.0 +2.0
...agentscore history # Last 10 score snapshots
agentscore history --limit 30
agentscore diff # Compare with previous scan
agentscore diff 2026-05-01 # Compare with specific dateHistory is stored in ~/.agentscore/history/ and auto-pruned after 30 days.
- Zero context overhead — agentscore itself never adds context to Claude Code sessions
- On-demand only — completely silent during normal use, runs only when invoked
- Local only — all data stored in
~/.agentscore/, no external servers - Honest estimates — uncertain values are marked as "(estimated)"
~/.claude/settings.json enabledPlugins, model settings
~/.claude/settings.local.json permissions.allow, enabledMcpjsonServers
~/.claude/mcp.json MCP server list
~/.claude/CLAUDE.md Global instructions
~/.claude/plugins/installed_plugins.json Installed plugins + update timestamps
.claude/CLAUDE.md Project-level instructions
CLAUDE.md Project root instructions
- Python 3.11+
click— CLI frameworkrich— terminal outputhttpx— GitHub API (foragentscore check)- stdlib only:
json,pathlib,re,datetime
| Variable | Description |
|---|---|
GITHUB_TOKEN |
GitHub personal access token (raises rate limit from 60 to 5,000 req/hr for agentscore check) |
MIT