← Public packages
@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 — agent notes
Human intent, setup, and fork steps: README.md.
Do not enable or disable package jobs, or mint/rotate/apply the GitHub webhook,
unless the owner explicitly asks. Prefer run({ dryRun: true }) when testing.
Secrets / credentials
By dependency (names only):
- Cursor:
cursorApiKey(via@kentcdodds/cursor) - Devin (
general-audit):devinServiceUserKeyplus thedevinOrgIdstorage value (via@kentcdodds/devin) - GitHub:
github-botOAuth connection (via@kentcdodds/github; this package only reads commits) - Notify: optional per-automation
notifyexport spec in storage. Spawned agents call it via MCP; it is not imported by this package
https://kody.codes/account/secrets/new — never paste values.
Import paths
| Export | Import |
|---|---|
| overview | kody:@kentcdodds/codebase-cleanup |
| config | kody:@kentcdodds/codebase-cleanup/config |
| run-now | kody:@kentcdodds/codebase-cleanup/run |
| prompts | kody:@kentcdodds/codebase-cleanup/prompts |
| CI webhook | kody:@kentcdodds/codebase-cleanup/handle-ci-failure |
| CI re-check (workflow entry) | kody:@kentcdodds/codebase-cleanup/ci-recheck |
| CI red episodes | kody:@kentcdodds/codebase-cleanup/ci-episode |
| jobs | kody:@kentcdodds/codebase-cleanup/jobs/legacy-reaper (also docs-freshness, keep-tests-tight, general-audit) |
Prefer static kody:@kentcdodds/codebase-cleanup/... imports (local CLI
execute --local when available). In a fork, use your own scope.
Manage repos
import { listConfig, addRepo, removeRepo, set } from 'kody:@kentcdodds/codebase-cleanup/config'
export default async function main() {
await addRepo({ automation: 'legacy-reaper', repo: 'acme/widgets' })
await removeRepo({ automation: 'legacy-reaper', repo: 'acme/other' })
await set({ automation: 'legacy-reaper', notify: 'kody:@acme/chat/send-me-a-message' })
await set({ automation: 'docs-freshness', enabled: true })
return await listConfig()
}Smoke / dryRun
import runNow from 'kody:@kentcdodds/codebase-cleanup/run'
export default async function main() {
return await runNow({ automation: 'legacy-reaper', dryRun: true })
}import runNow from 'kody:@kentcdodds/codebase-cleanup/run'
export default async function main() {
const ids = ['legacy-reaper', 'prod-ci-failure', 'docs-freshness', 'keep-tests-tight', 'general-audit']
const out = {}
for (const automation of ids) {
out[automation] = await runNow({ automation, dryRun: true, skipCommitGate: true })
}
return out
}import handleCiFailure from 'kody:@kentcdodds/codebase-cleanup/handle-ci-failure'
import ciRecheck from 'kody:@kentcdodds/codebase-cleanup/ci-recheck'
export default async function main() {
// Webhook: dryRun previews the deferred re-check without scheduling it.
const webhook = await handleCiFailure({
dryRun: true,
request: {
headers: { 'x-github-event': 'check_suite', 'x-github-delivery': 'test' },
json: {
action: 'completed',
check_suite: { id: 1, conclusion: 'failure', head_branch: 'main', head_sha: 'dryrunsha' },
repository: { full_name: 'acme/widgets' },
},
},
})
// Re-check: dryRun reads GitHub and reports would-launch / skip without claiming.
const recheck = await ciRecheck({ repo: 'acme/widgets', branch: 'main', dryRun: true })
return { webhook, recheck }
}import { list, markHandled, reset } from 'kody:@kentcdodds/codebase-cleanup/ci-episode'
export default async function main() {
// Someone is already fixing red main: block launches until it goes green.
await markHandled({ repo: 'acme/widgets', branch: 'main', sha: 'abc123', note: 'Manual agent on it' })
return await list()
}general-audit (Devin)
import runNow from 'kody:@kentcdodds/codebase-cleanup/run'
export default async function main() {
// Returns prompt + devinRequest ({ method, path, body }) and devinOrgConfigured. No session, no ACUs.
return await runNow({ automation: 'general-audit', dryRun: true })
}- Launcher is Devin, not Cursor (
automationLaunchersinsrc/shared.ts).src/devin.tsbuilds the request; a live run sends that same object throughkody:@kentcdodds/devin/requesttoPOST /v3/organizations/{org_id}/sessions. devinModedefaults tofusion;maxAcuLimit: nulluses the Devin org default.modelis ignored for Devin automations.- Never
forcea live run to "test" it: every session costs ACUs. Use dryRun. - Prompt uses its own footer (
devinPromptFooter), not the Cursor shipping footer. Withnotify: nullthe report stays in the Devin session; it never falls back to a PR description. - Do not paste audit findings (any lane) into issues, PRs, commits, or public chat.
- One run = one Devin session per configured repo. The prompt walks four lanes
in order (security, performance, accessibility, code health); lanes are
auditLanesinsrc/shared.ts, andformatAuditReportrenders the four-section report format the prompt asks for. - Renamed from
security-audit.legacyAutomationIdsmaps the old id so stored config carries over (read-time; rewritten on the next config save). The job id is nowpackage-job:<package_id>:general-audit.
Edge cases
- Default model id:
grok-4.6with paramseffort=high,fast=true. docs-freshness/keep-tests-tightare scoped (src/scoped-run.ts), ignoringskipIfNoCommits24h. Range = later of the last mergedcleanup/<automation>-*PR's merge_commit_sha andscan_state.last_scanned_sha, to the branch head (src/scope.ts). Pure logic (scope, Jev request and parsing, heuristic, chunk packing) lives insrc/scope-core.ts; Jev and Clef calls insrc/triage.ts. Tunables per automation:maxAgentsPerDay(3),chunkMin(10),chunkMax(15),triageThreshold(0.6),fullSweepWeekday(0 = Sunday,null= off).- No kept files: no agent, launch
skipped/outcome=no-relevant-changes, floor moves to head. Chunks over the daily cap:over-daily-cap, floor stays. dryRun never moves the floor. - Agents must use the exact branch in the prompt; a renamed branch means the next run will not see that merge and falls back to the floor.
- Jev failure (402 without AI Gateway credits) falls back to the heuristic;
results show
triage.sourceandtriage.errors. prod-ci-failure: the webhook only schedules./ci-recheckviaworkflows.create({ runAt: now + recheckDelaySeconds })(default 60s; never sleep in the webhook). Idempotency key = repo + branch + head SHA + check suite id, so check_suite / workflow_run / check_run for one run share one re-check. The re-check launches only when the head is still red (newest attempt of a push-triggered workflow isfailure/timed_out; filter withciWorkflows) and noci_episodesrow is open for repo + branch. The claim is one atomicINSERT … ON CONFLICT … WHERE status='closed' RETURNING, so concurrent re-checks launch once. Green head closes the episode. The older per-SHAci_dedupetable still guardsrunNow.- Open PR detection is best effort: an open PR into the branch whose title or body names the red SHA (7+ chars) or a failing run id/URL.
- A failed launch releases the episode (
status='closed', notereleased: …). runNow({ automation: 'prod-ci-failure', force: true })still launches directly and bypasses all of the above; use it only when the owner asks.notify: null→ prompts tell agents to report in the PR description.- Prompt templates: edit
src/prompts/templates.ts, then republish. - Package jobs are
enabled: trueinpackage.json; each owner still enables them for themselves, and nothing spawns until storage lists repos andenabled: true. - Cursor usage limits can make live
createAgentfail; dryRun still works.