agentscore-cli

agentscore

Lighthouse for AI agent development environments

Language: 한국어 | English | 中文

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.

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)

Grades

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.

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

1. Zero context overhead — agentscore itself never adds context to Claude Code sessions
2. On-demand only — completely silent during normal use, runs only when invoked
3. Local only — all data stored in ~/.agentscore/, no external servers
4. 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 framework
• rich — terminal output
• httpx — GitHub API (for agentscore check)
• stdlib only: json, pathlib, re, datetime

Environment Variables

License

MIT