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

AGENTS.md

170 lines · 7.7 KB · Markdown

@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): 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

ExportImport
overviewkody:@kentcdodds/codebase-cleanup
configkody:@kentcdodds/codebase-cleanup/config
run-nowkody:@kentcdodds/codebase-cleanup/run
promptskody:@kentcdodds/codebase-cleanup/prompts
CI webhookkody:@kentcdodds/codebase-cleanup/handle-ci-failure
CI re-check (workflow entry)kody:@kentcdodds/codebase-cleanup/ci-recheck
CI red episodeskody:@kentcdodds/codebase-cleanup/ci-episode
jobskody:@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 (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:<package_id>: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/<automation>-* 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.