agentscore
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.
$ agentscore
Context Efficiency ██████████░░░░░░ 17.0/25
Coverage ████████████████ 20.0/20 ✓
Conflict Detection ████████████░░░░ 16.0/20
Config Quality ████████████████ 15.0/15 ✓
Security ████████████░░░░ 8.0/10
Freshness ████████████████ 10.0/10 ✓
Quick Wins ──────────────────────────────────────────────
1. plugin-a · plugin-b are high context-cost (🔴). Disable when not in use.
2. tool-x · tool-y · tool-z all provide qa. Pick one and remove the rest.
3. Review permissions.allow in settings.local.json — restrict to what you need.
Why agentscore?
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 |
Installation
pip install agentscore-cli
Requirements: Python 3.11+, Claude Code installed
Or install from source:
git clone https://github.com/calintzy/agentscore
cd agentscore
pip install -e .
Usage
# 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
Scoring (100 points total)
| Dimension | Points | Description |
|---|---|---|
| Context Efficiency | 25 | CLAUDE.md size, dead-weight tools, duplicate instructions |
| Coverage | 20 | Required tool category coverage for your profile |
| Conflict Detection | 20 | Duplicate tools providing the same capability |
| Config Quality | 15 | Model setting, inactive plugins, CLAUDE.md presence |
| Security | 10 | Dangerous permission patterns (Bash(*), Bash(sudo:*), etc.) |
| Freshness | 10 | Plugin last-updated timestamps |
Grades
| Grade | Score | Meaning |
|---|---|---|
| S | 90-100 | Optimized environment |
| A | 75-89 | Well configured, minor improvements needed |
| B | 55-74 | Basics covered, important improvements needed |
| C | 35-54 | Significant gaps exist |
| D | 0-34 | Reconfiguration recommended |
Context ROI
Measures context cost as a value-to-cost ratio, not an absolute value.
Context ROI = (Profile Fit × 0.6 + Config Priority × 0.4) / Context Cost
- ROI < 0.3: Dead Weight — high-cost tool you're not using (penalty)
- ROI > 2.0 + low cost: Ideal — high value at low cost (bonus)
Config Priority Signals
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 |
Profile System
agentscore # Tier 0: generic (instant, no profile)
agentscore --profile backend # Tier 1: role-based evaluation
agentscore setup # Save role → applied automatically afterwards
Supported 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).
agentscore check
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 —
Conflict Detection 12.0 14.0 +2.0
...
History
agentscore history # Last 10 score snapshots
agentscore history --limit 30
agentscore diff # Compare with previous scan
agentscore diff 2026-05-01 # Compare with specific date
History is stored in ~/.agentscore/history/ and auto-pruned after 30 days.
Design Principles
- 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)"
Scanned Files
~/.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
Tech Stack
- Python 3.11+
click— CLI frameworkrich— terminal outputhttpx— GitHub API (foragentscore check)- stdlib only:
json,pathlib,re,datetime
Environment Variables
| Variable | Description |
|---|---|
GITHUB_TOKEN |
GitHub personal access token (raises rate limit from 60 to 5,000 req/hr for agentscore check) |
License
MIT
Metadata
Release files for agentscore-cli 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agentscore_cli-0.1.2.tar.gz | 37.5 kB | Without provenance | Details for agentscore_cli-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentscore_cli-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for agentscore_cli-0.1.2-py3-none-any.whl |
Total release size: 75.0 kB
Release files / agentscore_cli-0.1.2.tar.gz
| Download URL | agentscore_cli-0.1.2.tar.gz |
|---|---|
| Size | 37.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5b0206cccfd756b26505fad0945cb89c22d05af078b519af13283f02da84e930
|
|
BLAKE2b-256 checksum How to use checksums |
3ef5d213f0489e447da44f73788b52431d9ebb02a1e0a1dcb0eb586eae226229
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.7
|
Release files / agentscore_cli-0.1.2-py3-none-any.whl
| Download URL | agentscore_cli-0.1.2-py3-none-any.whl |
|---|---|
| Size | 37.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f4d5576c099395e05f2990bcc6edebc53c5e7cc5534b5b1d1dc94d59409d99ba
|
|
BLAKE2b-256 checksum How to use checksums |
747b9ac4a10fee92e46580401d4f401330eb62f7998d07e04898224882c94abf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.7
|
Security for agentscore-cli 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.