# @kentcdodds/codebase-cleanup ## Intent Kody-owned jobs and a GitHub webhook that launch Cursor cloud agents to keep a codebase clean, plus a weekly Devin general audit. Each automation has its own **enabled** flag, **repos** list, and **notify** target in package storage, so you choose which repos each one runs on and how agents reach you, without editing prompts. Success: scheduled and CI-triggered agents run only on the repos you listed, skip expensive spawns when a daily automation has nothing to do (docs and tests runs hand an agent only the files a triage model flagged since the last cleanup merge), and a red branch gets at most one fix agent per red stretch: the CI webhook waits a minute, re-checks that the branch head is still red, and skips when something is already working on it. ## Automations | Id | Trigger | Notes | | --- | --- | --- | | `legacy-reaper` | Cron Mon 2:00 AM America/Denver | reports +/- lines per track | | `docs-freshness` | Cron daily 3:00 AM America/Denver | scoped to docs changes since the last cleanup merge; full sweep Sundays | | `keep-tests-tight` | Cron daily 3:30 AM America/Denver | scoped to test changes since the last cleanup merge; full sweep Sundays | | `general-audit` | Cron Mon 3:00 AM America/Denver | One Devin session in Fusion mode: security, performance, accessibility, code health; private findings report | | `prod-ci-failure` | GitHub webhook `github-ci-failure` (`check_suite` / `workflow_run`; `check_run` optional) | waits `recheckDelaySeconds` (60), re-checks the head, one agent per red stretch | Default model: **Grok 4.6** with effort `high` and fast `true` (Cursor id `grok-4.6`). Defaults are safe: no repos, no notify target, and every automation `enabled: false` in storage until you configure it. `general-audit` launches one Devin session instead of a Cursor agent, in Devin's Fusion (multi-model routing) mode by default (`devinMode`, optional `maxAcuLimit`). For the package owner, the Cursor jobs, the general audit, and the webhook are live. ## How docs-freshness and keep-tests-tight pick their work Each daily run, per repo: 1. **Range.** The base is the later of the merge commit of the last merged PR whose branch starts with `cleanup/-`, and the stored `last_scanned_sha`. With neither, it starts from the commits of the last 24h. The head is the branch head. Files come from the GitHub compare API; past its 300 file cap the range is split by commit and merged. 2. **Scope.** `docs-freshness` looks at markdown, `docs/`, `AGENTS.md`, and skill files, plus code changes that edit an export (docs may describe it). `keep-tests-tight` looks at test files, plus code changes whose sibling test file exists (`a.ts` with `a.test.ts`). 3. **Triage.** Jev (`typesafe/jev` through `@kentcdodds/jev`) answers one choice per file: a reason such as `inaccurate`, `too-much-detail`, `missing-progressive-disclosure`, `tautological`, or `fine`. A file is kept when P(not fine) is at least `triageThreshold` (0.6). If Jev fails (for example HTTP 402, no gateway credits), a keyword heuristic decides instead. 4. **Chunks.** Clef groups kept files by area; chunks hold 10 to 15 files. 5. **Agents.** One Cursor agent (Grok 4.6) per chunk, at most `maxAgentsPerDay` (3) per automation per day. Each prompt lists the exact paths and reasons and requires the branch `cleanup/-[-n]`, which is how the next run finds the merge. 6. **Nothing to do.** No agent, a `no-relevant-changes` launch record, and `last_scanned_sha` moves to the head. It also moves when every chunk got an agent; chunks over the daily cap wait for the next run. On `fullSweepWeekday` (default 0, Sunday; `null` turns it off) the run uses the full-repo prompt instead, if the branch had commits in the last 7 days. `runNow({ automation: 'docs-freshness', dryRun: true })` returns the range, the triage, and the chunks without spawning or moving the floor. Pass `scopedOnly: true` to skip the full sweep, or `fullSweep: true` to force it. Launch records include `outcome` and `files`. ## How general-audit works and keeps findings private Each run starts exactly one Devin session per configured repo. That session walks four lanes in order, finishing each before the next: 1. **Security:** authn/authz gaps, multi-tenant isolation, secrets handling and leakage, injection, SSRF, unsafe deserialization, webhook signature checks, CORS/cookies, and reachable dependency advisories. 2. **Performance:** data access (N+1, unbounded queries, indexes), request paths, caching, memory and resource use, client bundle and render cost, background work. 3. **Accessibility:** semantics, keyboard and focus, names and labels, ARIA, contrast and motion. 4. **Code health:** dead code, dependency drift, and test gaps. It never probes or load tests production. - Findings go only to the automation's `notify` target as a private report. The report has one section per lane, in lane order, each with counts by severity and, per finding, severity, confidence, title, affected files, and a suggested fix. A lane with no findings still gets its section, marked "None found." The report ends with a link to the Devin session. Exploit details stay in the Devin session. `formatAuditReport` in `src/shared.ts` renders this format, and the prompt embeds its skeleton. - Config saved under the old `security-audit` id is read as `general-audit` (and rewritten under the new id on the next save), so enabled, repos, notify, schedule, devinMode, and maxAcuLimit carry over. - With no `notify` target, the report stays in the Devin session. It never falls back to a PR description. - No public issues, PRs, branches, commits, or comments about findings in any lane. - The only PRs it may open are low-risk hygiene changes that disclose nothing (for example a routine dependency bump), and it leaves them unmerged. Point `notify` at something only you can read. ## How prod-ci-failure decides 1. A failed `check_suite` / `workflow_run` (/ `check_run`) on the configured branch never launches anything in the webhook. It schedules one deferred re-check (`./ci-recheck`) through Kody `workflows.create` with `runAt = now + recheckDelaySeconds` (default 60). Events from the same CI run share a check suite id, so they collapse onto one re-check. 2. The re-check reads the branch head from GitHub and judges it by the newest attempt of each push-triggered Actions workflow on that commit (`ciWorkflows` narrows which ones; empty = all): - still running or no runs yet → do nothing (the head's own completion re-checks) - green → close any open red episode; nothing launches - red → launch only if no red episode is open for that repo + branch and no open PR already names the red SHA or failing run (best effort) 3. An open episode means something already owns this red stretch: an agent this package launched, a manual agent you recorded with `ci-episode.markHandled`, or an open PR. Every later red commit on the branch is skipped until the head goes green. Green completions re-check while an episode is open, and a green head closes it, so the next red launches again. 4. If the launch fails, the episode is released so the next failure retries. ## Prerequisites 1. A Cursor API key saved as the `cursorApiKey` secret (used by `@kentcdodds/cursor`). Optional: `githubPersonalAccessToken` for agents. For `general-audit`: a Devin service user key saved as `devinServiceUserKey` and your Devin org id saved through `@kentcdodds/devin/settings`. Devin needs access to the repo, and a Kody MCP connection if you want it to call your `notify` export. The session is created as the default Devin user saved in `@kentcdodds/devin/settings` (`createAsUserId`), so it gets that user's Kody MCP and Kody CLI access; with no default saved, it runs as the service user. 2. A GitHub OAuth connection named `github-bot` (used by `@kentcdodds/github` for the 24h commit check). 3. Optional: a Kody export your agents can call over MCP to message you (for example a Discord or email "message me" export). Set it as `notify`. Without it, agents report in the PR description instead. ## Fork it 1. Fork this package plus `@kentcdodds/cursor`, `@kentcdodds/github`, and `@kentcdodds/devin` (all public). Kody imports never cross orgs, so rewrite the `kody:@kentcdodds/cursor/...`, `kody:@kentcdodds/github/...`, and `kody:@kentcdodds/devin/...` imports in `src/run.ts`, `src/github.ts`, `src/devin.ts`, and `package.json#kody.dependencies` to your copies. 2. Add your repos and notify target, then enable the automations you want (`config.addRepo`, `config.set`). Preview with `run({ dryRun: true })`. 3. Enable the jobs for yourself (`jobUpdate` + `enablementEnable`), and adjust the cron times / timezone in `package.json` if you like. 4. Mint your own `github-ci-failure` webhook endpoint and add it to each repo (events: `check_suite`, `workflow_run`, optionally `check_run`). It is verified with GitHub's `x-hub-signature-256` HMAC. If the branch is already red and someone is on it when you connect, record that first with `ci-episode.markHandled` so the first event does not launch a duplicate. ## Manage which repos each automation runs on From any Kody execute session (agent notes in [`AGENTS.md`](./AGENTS.md)): - List config → see every automation’s `repos`, `enabled`, `branch`, `model`, `notify` - `addRepo` / `removeRepo` → attach or detach `owner/repo` per automation - `set` → change `enabled`, `branch`, `model`, `notify`, the commit gate, for `prod-ci-failure` `ciWorkflows` / `recheckDelaySeconds`, and for `general-audit` `devinMode` / `maxAcuLimit` - `ci-episode` → `list` red episodes, `markHandled` a red branch someone is already fixing, or `reset` one by hand - `run` with `dryRun: true` → preview resolved prompt + target repo without spawning (for `general-audit`, also the exact Devin create-session request)