# @kentcdodds/codebase-cleanup — agent notes Human intent, setup, and fork steps: [`README.md`](./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`): `devinServiceUserKey` plus the `devinOrgId` storage value (via `@kentcdodds/devin`) - GitHub: `github-bot` OAuth connection (via `@kentcdodds/github`; this package only reads commits) - Notify: optional per-automation `notify` export 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 ```ts 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 ```ts import runNow from 'kody:@kentcdodds/codebase-cleanup/run' export default async function main() { return await runNow({ automation: 'legacy-reaper', dryRun: true }) } ``` ```ts 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 } ``` ```ts 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 } } ``` ```ts 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) ```ts 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 (`automationLaunchers` in `src/shared.ts`). `src/devin.ts` builds the request; a live run sends that same object through `kody:@kentcdodds/devin/request` to `POST /v3/organizations/{org_id}/sessions`. - `devinMode` defaults to `fusion`; `maxAcuLimit: null` uses the Devin org default. `model` is ignored for Devin automations. - Never `force` a live run to "test" it: every session costs ACUs. Use dryRun. - Prompt uses its own footer (`devinPromptFooter`), not the Cursor shipping footer. With `notify: null` the 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 `auditLanes` in `src/shared.ts`, and `formatAuditReport` renders the four-section report format the prompt asks for. - Renamed from `security-audit`. `legacyAutomationIds` maps the old id so stored config carries over (read-time; rewritten on the next config save). The job id is now `package-job::general-audit`. ## Edge cases - Default model id: `grok-4.6` with params `effort=high`, `fast=true`. - `docs-freshness` / `keep-tests-tight` are scoped (`src/scoped-run.ts`), ignoring `skipIfNoCommits24h`. Range = later of the last merged `cleanup/-*` PR's merge_commit_sha and `scan_state.last_scanned_sha`, to the branch head (`src/scope.ts`). Pure logic (scope, Jev request and parsing, heuristic, chunk packing) lives in `src/scope-core.ts`; Jev and Clef calls in `src/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.source` and `triage.errors`. - `prod-ci-failure`: the webhook only schedules `./ci-recheck` via `workflows.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 is `failure` / `timed_out`; filter with `ciWorkflows`) and no `ci_episodes` row is open for repo + branch. The claim is one atomic `INSERT … ON CONFLICT … WHERE status='closed' RETURNING`, so concurrent re-checks launch once. Green head closes the episode. The older per-SHA `ci_dedupe` table still guards `runNow`. - 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'`, note `released: …`). - `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: true` in `package.json`; each owner still enables them for themselves, and nothing spawns until storage lists repos and `enabled: true`. - Cursor usage limits can make live `createAgent` fail; dryRun still works.