One command. A reviewable branch. Evidence before confident-sounding advice.
Codebase Audit asks Cursor, Codex, or Claude Code to trace a repository's real behavior, reproduce important failures safely, apply small fixes it can verify, run available checks, and write .code-audit/report.md. Run it once locally or schedule a weekly pull request. It also includes 25 focused prompts for deeper investigations.
A green test can mean a fixture passed while the live path broke. A queued job can be called “done” before a customer sees anything. This project asks where the outcome actually becomes true.
See a real finding in this repository · Read the design principles · Browse the prompts
Install and sign in to the Cursor CLI, Codex CLI, or Claude Code CLI. From the root of a clean Git repository you want to audit:
curl -fsSL https://raw.githubusercontent.com/samjhill/codebase-audit/main/run.sh | bashThe runner selects the first available CLI in this order: Cursor → Codex → Claude. To choose one explicitly, append -s -- --agent claude (or cursor or codex) to the command. It creates an audit/* branch, keeps code changes there, and asks the agent for a report. Review the diff and report before merging. The agent can execute commands and edit files; your plan limits or API charges apply.
your repository
├── audit/* branch ← reviewable edits
└── .code-audit/report.md ← findings, evidence, checks, unknowns
The runner fails if the agent exits with an error or omits a nonempty report. A successful exit means the CLI returned zero and wrote a report; it does not establish that every finding or fix is correct. The runner contract tests use disposable repositories and stub CLIs; earlier Cursor and Codex smoke runs fixed a seeded bug. A live Claude run and the scheduled workflows still need validation with your own credentials.
Copy the Cursor workflow or Claude workflow into the repository you want to audit as .github/workflows/audit.yml. Add CURSOR_API_KEY or ANTHROPIC_API_KEY as the corresponding GitHub Actions secret. In Settings → Actions → General → Workflow permissions, enable Allow GitHub Actions to create and approve pull requests.
The example runs weekly or on manual dispatch and opens a PR only when code changes. Review every PR before merging. Scheduled runs consume agent API usage and GitHub Actions minutes. Cursor Automations are another option for focused audits.
| Question | Required evidence |
|---|---|
| What failed? | The entry point, state transition, and intended user outcome |
| Why believe it? | Exact code path and a safe reproduction or clearly labeled inference |
| What changed? | The smallest practical fix and a reviewable diff |
| What passed? | Checks labeled unit/fixture, integration, staging, or live; mocked dependencies named |
| What remains unknown? | Missing telemetry, credentials, provider behavior, or manual verification |
The self-audit follows this pattern for a real runner failure. The operational truth prompt applies it to a product's customer outcome.
Open a prompt in Cursor, Codex, or Claude Code and fill in its bracketed placeholders. Focused prompts start with investigation; sensitive billing and security prompts are read-only.
| If you need to… | Start here |
|---|---|
| Find a broken customer flow | Customer journey |
| Catch misleading success signals | Operational truth |
| Check whether onboarding is truly ready | Onboarding readiness |
| Trace subscription and payment state | Billing lifecycle |
| Investigate security exposure | Evidence-based security audit |
| Find expensive or fragile infrastructure | Infrastructure |
| Remove unused code | Dead code |
| Reduce CI time or cost | GitHub Actions CI cost |
All 25 focused prompts
Investigate first: customer journey · onboarding readiness · billing lifecycle · security audit · infrastructure
Cross-cutting code: operational truth · boundaries · dead code · dependencies · naming · type safety · complexity · state ownership · edge cases · test suite · performance · engineer onboarding · CI cost
Frontend: code cleanup · logic cleanup · accessibility
Backend: code cleanup · logic cleanup · logging
The older code security pass is a shorter fix-oriented checklist.
These are prompts and an agent runner, not a deterministic scanner or a security certification. A plausible finding is not a verified bug. Repo access cannot establish what happened in production; fixtures cannot prove live acceptance. High-risk changes need human review and safe validation. A codebase-wide pass cannot guarantee it found or fixed every bug.
This project reflects the engineering approach of Sam Hill. Concrete counterexamples and false positives are especially useful: open an issue or contribute a prompt improvement. Licensed under MIT.