@kentcdodds/codebase-cleanup
Cursor cloud agents for legacy cleanup, docs freshness, tight tests, and prod CI fixes, plus a weekly Devin general audit.
Files
@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:
- Range. The base is the later of the merge commit of the last merged PR
whose branch starts with
cleanup/<automation>-, and the storedlast_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. - Scope.
docs-freshnesslooks at markdown,docs/,AGENTS.md, and skill files, plus code changes that edit an export (docs may describe it).keep-tests-tightlooks at test files, plus code changes whose sibling test file exists (a.tswitha.test.ts). - Triage. Jev (
typesafe/jevthrough@kentcdodds/jev) answers one choice per file: a reason such asinaccurate,too-much-detail,missing-progressive-disclosure,tautological, orfine. A file is kept when P(not fine) is at leasttriageThreshold(0.6). If Jev fails (for example HTTP 402, no gateway credits), a keyword heuristic decides instead. - Chunks. Clef groups kept files by area; chunks hold 10 to 15 files.
- 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 branchcleanup/<automation>-<date>[-n], which is how the next run finds the merge. - Nothing to do. No agent, a
no-relevant-changeslaunch record, andlast_scanned_shamoves 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:
- Security: authn/authz gaps, multi-tenant isolation, secrets handling and leakage, injection, SSRF, unsafe deserialization, webhook signature checks, CORS/cookies, and reachable dependency advisories.
- Performance: data access (N+1, unbounded queries, indexes), request paths, caching, memory and resource use, client bundle and render cost, background work.
- Accessibility: semantics, keyboard and focus, names and labels, ARIA, contrast and motion.
- Code health: dead code, dependency drift, and test gaps.
It never probes or load tests production.
- Findings go only to the automation's
notifytarget 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.formatAuditReportinsrc/shared.tsrenders this format, and the prompt embeds its skeleton. - Config saved under the old
security-auditid is read asgeneral-audit(and rewritten under the new id on the next save), so enabled, repos, notify, schedule, devinMode, and maxAcuLimit carry over. - With no
notifytarget, 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
- 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 Kodyworkflows.createwithrunAt = now + recheckDelaySeconds(default 60). Events from the same CI run share a check suite id, so they collapse onto one re-check. - 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
(
ciWorkflowsnarrows 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)
- 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. - If the launch fails, the episode is released so the next failure retries.
Prerequisites
- A Cursor API key saved as the
cursorApiKeysecret (used by@kentcdodds/cursor). Optional:githubPersonalAccessTokenfor agents. Forgeneral-audit: a Devin service user key saved asdevinServiceUserKeyand 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 yournotifyexport. 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. - A GitHub OAuth connection named
github-bot(used by@kentcdodds/githubfor the 24h commit check). - 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
- Fork this package plus
@kentcdodds/cursor,@kentcdodds/github, and@kentcdodds/devin(all public). Kody imports never cross orgs, so rewrite thekody:@kentcdodds/cursor/...,kody:@kentcdodds/github/..., andkody:@kentcdodds/devin/...imports insrc/run.ts,src/github.ts,src/devin.ts, andpackage.json#kody.dependenciesto your copies. - Add your repos and notify target, then enable the automations you want
(
config.addRepo,config.set). Preview withrun({ dryRun: true }). - Enable the jobs for yourself (
jobUpdate+enablementEnable), and adjust the cron times / timezone inpackage.jsonif you like. - Mint your own
github-ci-failurewebhook endpoint and add it to each repo (events:check_suite,workflow_run, optionallycheck_run). It is verified with GitHub'sx-hub-signature-256HMAC. If the branch is already red and someone is on it when you connect, record that first withci-episode.markHandledso 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):
- List config → see every automation’s
repos,enabled,branch,model,notify addRepo/removeRepo→ attach or detachowner/repoper automationset→ changeenabled,branch,model,notify, the commit gate, forprod-ci-failureciWorkflows/recheckDelaySeconds, and forgeneral-auditdevinMode/maxAcuLimitci-episode→listred episodes,markHandleda red branch someone is already fixing, orresetone by handrunwithdryRun: true→ preview resolved prompt + target repo without spawning (forgeneral-audit, also the exact Devin create-session request)