edsger

Agentic CLI to benchmark and audit repositories and review / resolve pull requests against industrial-grade engineering standards.

edsger runs the Claude Agent SDK over your code. The standards it applies (security, maintainability, testing, delivery, language-specific quality) live in edsger-assets and are fully overridable — use the sensible defaults with zero config, or point edsger at your team's own standards.

npm install -g edsger        # or: npx edsger ...

The agent authenticates with your Claude Code login — run claude once to sign in and edsger reuses those credentials. (You can still override with an ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN env var if you prefer.)

Commands

edsger benchmark

Score the repository in the current directory and write a report to .edsger/benchmark/ (report.md + report.json).

edsger benchmark                 # score the current repo
edsger benchmark -C ./service    # score another directory
edsger benchmark --json          # also print JSON to stdout
edsger benchmark --no-write      # don't write files into the repo

The agent detects the project's language(s), loads the matching rubric, inspects the code, scores every criterion with evidence, and edsger aggregates the weighted total into a 0–100 score and a letter grade.

Every run is archived under .edsger/benchmark/runs/<timestamp>/ and appended to .edsger/benchmark/history.jsonl, so the JSON data is committable and the dashboard can show history and trends over time.

edsger audit — nitpick the whole repo

Comb through the repository hunting for anything unprofessional, outdated, fragile, or sloppy — deprecated APIs, legacy patterns, swallowed errors, dead code, dependency rot, missing tooling, and more — and write an organised, evidence-backed issue report to .edsger/audit/ (report.md + report.json). edsger review is an alias.

edsger audit                          # audit the current repo
edsger audit --serve                  # …and open the findings dashboard
edsger audit --focus "error handling" # concentrate the audit on one concern
edsger audit --only outdated,dependencies   # restrict to specific dimension ids
edsger audit --fail-on high           # CI gate: exit 2 on high/critical findings
edsger audit --json                   # also print JSON to stdout
edsger audit serve                    # browse existing findings (filter by severity/dimension)
edsger audit report --html audit.html # export a self-contained shareable viewer

Findings are grouped by dimension (correctness, security, outdated patterns, dependency health, error handling, craftsmanship, architecture, testing, tooling, docs, performance — plus language-specific dimensions), sorted by severity, each with the file/line evidence, why it matters, a concrete fix, and an effort estimate. Repeated instances of the same issue are folded into one finding listing all locations, and reports are capped at the standard's policy.maxFindings (default 60, lowest severity dropped first) so they stay readable. Low-effort fixes surface in a Quick wins section, and runs are archived under .edsger/audit/runs/<timestamp>/ with a history.jsonl trend index, exactly like benchmark.

edsger serve — dashboard (current, history, trends)

Serve an interactive dashboard for the benchmark results in the current repo — overall score, category breakdown, per-criterion evidence, run history, and trend charts. Reads .edsger/benchmark/; writes nothing.

edsger serve                     # open the dashboard in your browser
edsger serve --port 8080         # pick a port
edsger serve --no-open           # just print the URL
edsger benchmark --serve         # benchmark, then open the dashboard

edsger report --html <path> — shareable export

Export a self-contained HTML file (all data inlined, no server needed) for sharing or committing. HTML is only written when you ask for it.

edsger report --html report.html         # write a single shareable file
edsger report --html report.html --open  # …and open it

edsger diagram — generate diagrams from the code

Analyse the repository, decide which professional diagrams actually fit this project (a library needs different diagrams than a microservice), and generate each as renderable Mermaid. Writes to .edsger/diagrams/ (diagrams.md + diagrams.json, with each run archived under runs/<timestamp>/).

edsger diagram                   # generate diagrams for the current repo
edsger diagram -C ./service      # …for another directory
edsger diagram --serve           # generate, then open the diagram dashboard
edsger diagram --only er-diagram,request-sequence   # just specific diagrams
edsger diagram --json            # also print JSON to stdout

The agent detects the project's language(s), loads the matching diagram catalog (from edsger-assets, fully overridable), profiles the project, and emits diagrams grounded in real files: C4 system-context/container/component/deployment, module dependency graphs, class & domain models, ER database schemas, sequence flows, function flowcharts, state machines, data-flow, CI/CD pipelines, and more — plus language-specific ones (React component trees, JPA entity models, goroutine pipelines…).

The diagrams.md renders directly on GitHub. For an interactive, browsable view:

edsger diagram serve             # serve the diagram dashboard (renders Mermaid)
edsger diagram report --html diagrams.html   # export a self-contained HTML file

The dashboard renders every diagram as Mermaid with per-diagram zoom, a source/copy toggle, and SVG / PNG download; each generated diagram also gets a static Mermaid sanity check whose warnings surface in the CLI, in diagrams.md, and on the card.

edsger mindmap — implementation mind map of the code

Analyse the repository and build an implementation mind map: an outline tree whose root is the project and whose branches explain how the code is actually implemented — entry points, core flows, module structure, domain model, integrations — with every leaf citing the real files it describes. Writes to .edsger/mindmap/ (mindmap.md + mindmap.json, with each run archived under runs/<timestamp>/).

edsger mindmap                   # mind-map the current repo
edsger mindmap -C ./service      # …another directory
edsger mindmap --serve           # generate, then open the interactive viewer
edsger mindmap --focus "the auth subsystem"   # concentrate the depth somewhere
edsger mindmap --json            # also print JSON to stdout

The agent detects the project's language(s), loads the matching mind-map standard (from edsger-assets, fully overridable), keeps only the branches this project's code supports, and grows each into a faithful subtree. mindmap.md is a nested outline that reads well on GitHub; for the interactive view:

edsger mindmap serve             # serve the mind-map viewer
edsger mindmap report --html mindmap.html   # export a self-contained HTML file

The viewer browses the tree Workflowy-style: collapse/expand any node, click a bullet to zoom into that subtree (with a breadcrumb back up), navigate with the keyboard (↑/↓/←/→, Enter to zoom, Esc to zoom out), and search across titles, summaries, and file paths.

edsger testcases — manual test-case plan for the repo

Analyse the repository and derive a manual test-case plan: an outline tree whose root is the project, whose branches are the areas a human tester should exercise — core flows, inputs & edge cases, errors & recovery, data integrity, integrations, configuration — and whose leaves are concrete test cases (preconditions, exact steps, one expected result, a priority) that a tester who has never read the code can execute. These are not automated code tests. Writes to .edsger/testcases/ (testcases.md + testcases.json, with each run archived under runs/<timestamp>/).

edsger testcases                 # derive a test plan for the current repo
edsger testcases -C ./service    # …another directory
edsger testcases --serve         # generate, then open the interactive viewer
edsger testcases --focus "the export feature"   # concentrate the depth somewhere
edsger testcases --json          # also print JSON to stdout

The agent detects the project's language(s), loads the matching test-case standard (from edsger-assets, fully overridable), keeps only the test areas this project's code supports, and grounds every case in real behaviour — commands, flags, routes, screens, and error branches — citing the files that implement it. testcases.md is a nested Markdown checklist a tester can tick off; for the interactive view:

edsger testcases serve           # serve the test-case viewer
edsger testcases report --html testcases.html   # export a self-contained HTML file

The viewer browses the plan Workflowy-style like the mind map — collapse/expand, zoom with breadcrumbs, keyboard navigation, search — plus test-case extras: priority badges with a filter (critical/high/medium/low), per-branch case counts, and expandable case details showing preconditions, numbered steps, and the expected result.

edsger pr-review <pr> (requires gh)

Review a pull request against the review standard. Previews by default; pass --post to submit the review (with inline comments) to GitHub.

gh auth login
edsger pr-review 123             # preview a review of PR #123
edsger pr-review 123 --post      # submit it to GitHub
edsger pr-review https://github.com/org/repo/pull/123 --repo org/repo

edsger pr-resolve <pr> (requires gh)

Address review feedback (or a specific instruction), edit the code, run the tests, and optionally commit & push.

edsger pr-resolve 123                                   # apply fixes to the working tree
edsger pr-resolve 123 --instruction "fix the failing CI test"
edsger pr-resolve 123 --push                            # commit and push when done

Customising standards

Zero config uses the bundled defaults. To customise, edsger resolves standards in this order (highest precedence last):

1. Bundled defaults (from edsger-assets).
2. A configured override in edsger.config.yaml — a local path or a git repo.
3. A repo-local .edsger/<kind>/ directory.
4. An explicit --standard <path> flag.

Layers merge by id, so you can override a single category weight or add one criterion without copying the whole rubric.

# edsger.config.yaml
model: claude-sonnet-4-6
standards: git+https://github.com/acme/eng-standards#main
# or per-kind:
benchmark:
  standards: ./standards

Drop a partial overlay into your repo to tweak the defaults:

# .edsger/benchmark/base.yaml
categories:
  - id: security
    weight: 30 # bump security's weight
    criteria:
      - id: threat-model
        title: A documented threat model exists
        guidance: Look for docs/threat-model.md or an equivalent.

Use it inside Claude Code

If you already have the CLI, one command wires up the /benchmark, /pr-review, and /pr-resolve skills in Claude Code — no marketplace or paths to remember:

edsger skills install            # for the current user (all projects)
edsger skills install --project  # or scope to ./.claude/skills
edsger skills list               # see what's installed
edsger skills uninstall          # remove them

This copies the skills into ~/.claude/skills/ and points them at the bundled standards. Open Claude Code and run /benchmark, /pr-review, or /pr-resolve.

Without the CLI, the same standards are also a Claude Code plugin:

/plugin marketplace add stevenzg/edsger-assets
/plugin install edsger@edsger-assets

Global options

| Option | Description | | --------------------- | ------------------------------------------------------------ | | -C, --cwd <dir> | repository to operate on | | -m, --model <id> | agent model (default claude-sonnet-4-6, or EDSGER_MODEL) | | --standard <path> | custom standards dir or file | | --assets <path> | override the entire assets root | | --lang <id> | force a language, skipping detection | | --max-turns <n> | cap on agentic turns (default: unlimited) | | --timeout <minutes> | hard wall-clock limit per agent run (default: no limit) | | --json | machine-readable JSON on stdout | | --dry-run | run the agent but make no persistent/external changes | | -v, --verbose | verbose logging |

Requirements

• Node.js ≥ 18.17
• A Claude Code login for the agent (run claude to sign in), or an ANTHROPIC_API_KEY / CLAUDE_CODE_OAUTH_TOKEN env var
• GitHub CLI (gh), authenticated, for the PR commands

License

MIT