Skip to content
← 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.

FollowFork

Files

README.md

175 lines · 9.9 KB · Markdown

@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

IdTriggerNotes
legacy-reaperCron Mon 2:00 AM America/Denverreports +/- lines per track
docs-freshnessCron daily 3:00 AM America/Denverscoped to docs changes since the last cleanup merge; full sweep Sundays
keep-tests-tightCron daily 3:30 AM America/Denverscoped to test changes since the last cleanup merge; full sweep Sundays
general-auditCron Mon 3:00 AM America/DenverOne Devin session in Fusion mode: security, performance, accessibility, code health; private findings report
prod-ci-failureGitHub 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/<automation>-, 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/<automation>-<date>[-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):

  • 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)