Guides
Tune-up
Measure how well a repository is set up for a coding agent and where your agent sessions lose time — readiness score, repeated errors, retry loops, refused commands, unchecked code, unused MCP servers. Runs locally with npx, no account needed.
An agent works as well as the place it works in and the habits it falls into. The tune-up looks at both, on your machine, and tells you what to change — biggest gain first. Two reports, no account and no key:
npx -y @codexguild/mcp@latest readiness # how ready this repository is for an agent (0–100) npx -y @codexguild/mcp@latest coach # where your agent sessions here lost time (last 7 days)
Both are also MCP tools of the stdio server — codexguild_readiness and
codexguild_coach — so you can ask your agent "how do I make you work better in this repo?" and it runs them.
Nothing is uploaded: files and transcripts are read locally and only the report is printed.
Readiness: is the repository set up for an agent?
| Check | Points | Why it matters |
|---|---|---|
| Agent instructions | 20 | an AGENTS.md / CLAUDE.md, scored by the instruction linter (size, signal, secrets, leftovers) |
| Commands in the instructions | 10 | the exact build and test commands — otherwise the agent guesses |
| Test command | 15 | something the agent can run to check its work: package scripts (root, workspaces, app folders), pytest, go test, cargo test, Makefile, Gradle/Maven |
| Type-check / lint command | 10 | catches most agent mistakes in seconds |
| Pinned dependencies | 10 | a lockfile, so versions are exact for the agent and for CodexGuild |
| Secrets kept out of git | 10 | .env* ignored and no tracked key files |
| CI runs the checks | 10 | a change is checked even when the agent skipped it |
| Agent workflows are safe | 5 | no high-risk GitHub workflow that runs an agent (workflow review) |
| CodexGuild hooks | 10 | notes, known fixes, package and API guards and the done-gate run automatically |
Watchers and interactive scripts (test:watch, dev, --ui) never count — an agent would wait on them forever.
Coach: where did the sessions lose time?
The coach reads the Claude Code / OpenClaude transcripts on this machine (~/.claude/projects, ~/.openclaude/projects)
for this repository — including sessions started in a parent folder, counting only what happened inside the
project — and reports:
| Finding | The fix it suggests |
|---|---|
| the same error in several sessions | save what fixes it as an agent note — the next session starts with it |
| retry loops (the same error 3+ times in a row) | the CodexGuild hooks tell the agent to stop and change approach on the third repeat |
| sessions that ended with code changed and nothing checked after it | the done-gate (below) |
| refused tool calls | permissions.allow entries for the read-only and check commands you keep approving |
| edits that missed the file | re-read before editing after a long gap |
| the same file read again and again in a session | put what the agent keeps looking up into the instruction file |
| compactions | a short status file the agent keeps updated, plus the compaction hooks |
| MCP servers configured but never called | disable them for this project — their tool definitions still cost context |
Options: --days N (default 7, max 90), --all for every project on the machine, or a directory as the first
argument. Error lines are shown with your home folder as ~ and anything shaped like a key or password masked.
The done-gate
Part of the CodexGuild Stop hook (from @codexguild/mcp 1.12.0, same hook setup).
When the agent changed code in the project during the session and ran nothing that checks it after the last change,
it gets one message before it can end the turn:
CodexGuild done-gate: you changed code (src/math.js) and nothing checked it after the last change. Before finishing, run the project's checks — e.g.
npm test,npx tsc --noEmit— and report the result. If they can't run here, say exactly what you did not verify instead.
- What counts as a check: tests, type-check, lint or build commands (
npm test,pnpm -C apps/web run lint,npx tsc --noEmit,pytest,go test,cargo clippy, …). A failing check counts — the agent saw the result. - What counts as code: source files inside the project. Docs, prose, lockfiles and scratch files elsewhere don't.
- Never a loop: once per edit (a second stop with the same last change goes through), never while another Stop hook is active, and silent when the project has no check command it can name.
- Off switch:
CODEXGUILD_DONE_GATE=offin the environment.
It reads the session transcript the harness passes to the hook; local only, no key.