harness-review

A fortnightly self-review of your AI coding-agent sessions, packaged as a skill for Claude Code and Codex.

It summarizes your local session transcripts (tool calls, error rates, skills used and unused, subagent routing, hook activity, keyword-matched corrections) and has the agent turn the numbers into a short report: what works, what needs attention, what is unused, and what happened to last time's recommendations. The skill never edits your configuration: it is read-only except for the report it writes (and, with your approval, one memory note).

Privacy

• The script reads transcript files on your machine (~/.claude/projects or ~/.codex/sessions) and prints a Markdown summary. It makes no network requests and sends nothing anywhere.
• The report holds counts, tool names, skill names, project directory names and short error messages (digits normalized, truncated to 100 characters). Before printing, error texts and snippets are redacted on a best-effort basis: your home directory and other /Users/ or /home/ paths become ~, and credential-looking strings (key=value pairs, bearer tokens, common API-key prefixes, JWTs, URL passwords, long random tokens) and file contents quoted in edit errors are removed. Redaction is heuristic, so read the report before sharing it.
• User messages are not quoted unless you pass --include-corrections, which adds redacted snippets of at most 160 characters. Which messages count as corrections is a keyword match (Russian and English phrases such as "that's wrong" or "undo"); treat the number as a hint, not a measurement.
• The skill itself runs inside your agent, so the report is read by the model you already use. Check it before sharing.

Install

Claude Code:

/plugin marketplace add rpegorov/harness-review
/plugin install harness-review@harness-review

Codex (the install was verified against a temporary CODEX_HOME):

codex plugin marketplace add rpegorov/harness-review
codex plugin add harness-review@harness-review

DeepSeek Harness (package plugins/dsh-harness-review, a skill provider with a cordis.patch.yml bundle row):

dsh plugin --profile  add

The skill defaults to Claude Code transcripts (--agent claude) and can review Codex sessions with --agent codex; DeepSeek Harness's own transcripts are not supported.

Then ask: "review my agent sessions" or "run a harness health check".

Running every two weeks

Ask the agent manually, or schedule it from the agent itself: a Claude Code /schedule routine, or a scheduled task in the Claude or Codex desktop app, with the prompt "Run the harness-review skill". A plain cron job that launches claude or codex is not recommended: it runs unattended with your permissions and without a place to show the result.

Reports

The skill looks for the previous review and saves the new one in this order:

1. A Drafta note titled AUDIT — harness —, when a drafta MCP server is connected.
2. Otherwise harness-review-.md in ~/.local/share/harness-review/.

If a memory MCP server is configured, a cross-project lesson found during the review may be saved there.

Script

plugins/harness-review/scripts/session-audit is a Python 3 script using only the standard library.

session-audit [--agent claude|codex] [--days N | --since YYYY-MM-DD] [--split YYYY-MM-DD]
[--root PATH] [--skills-dir PATH] [--metrics-file PATH]
[--hooks NAME,NAME] [--memory-tool REGEX] [--include-corrections]

• --agent selects the transcript format. Claude Code reads ~/.claude/projects/**/*.jsonl; Codex reads ~/.codex/sessions/**/rollout-*.jsonl.
• The window is applied to each record's timestamp, not the file's modification time. Default: last 14 days.
• --split adds before/after columns for subagent routing and main-thread code edits, to measure a rule change.
• --skills-dir defaults to ~/.claude/skills or ~/.codex/skills; installed skills never called in the window are listed as unused. Installed means user skills plus plugin skills found in a plugins directory beside it; project-level skills are not discovered. Slash-command use (``) counts as use.
• Unreadable or vanished transcript files are skipped and counted in the report; malformed lines are counted too.
• --hooks counts the given hook names in tool results; --memory-tool enables a "memory search before first code read" section; --metrics-file adds a TSV of external executor runs (columns time in UTC, model, subtype). Each section is omitted when its option is not given.
• Codex transcripts have no interrupt, compaction or model-override records; the report lists these as not available.

Development

python3 -m unittest discover -s tests
ruff check .
scripts/sync.sh          # refresh the Codex plugin copies
scripts/sync.sh --check  # fail if they drifted

The Claude Code plugin under plugins/harness-review holds the canonical script and skill. plugins/harness-review-codex and plugins/dsh-harness-review carry a copy of the script and a skill derived from it, because those packages must be self-contained. The DeepSeek Harness package has its own check: npm test in that directory.

License

MIT