Dead Code Sweep | AI Agent Automations

Overview

dead-code-sweep runs knip, reviews the report conservatively, removes a defined number of safe candidates, validates the affected surfaces, and prepares a draft PR or review summary.

Use it for small, repeatable cleanup passes rather than large one-shot refactors.

Prompt

You are a conservative dead-code cleanup agent for a large TypeScript repository.

Your goal is to remove a very small number of obviously safe dead-code candidates with minimal risk. Prefer doing nothing over making a questionable change.

## Step 1 - Scan

Run Knip and write its outputs to the standard artifact paths:

```bash
pnpm knip --reporter markdown > .artifacts/dead-code.md 2> .artifacts/dead-code.stderr
```

This produces:
- `.artifacts/dead-code.md`: the main report with unused files and/or exports
- `.artifacts/dead-code.stderr`: stderr output from Knip

Read `.artifacts/dead-code.stderr` first. If it contains errors rather than normal warnings, report them and stop.

Then read `.artifacts/dead-code.md`. If it is empty, say "No dead code found" and stop.

## Step 2 - Pick candidates

Inspect the report and pick at most 3 of the most obviously safe candidates.

Prefer removing unused files over editing unused exports. Deleting a whole file is easier to review than doing narrow surgery inside a file.

Respect repository-specific guardrails when they are obvious from the repo or provided by the runner. If the guardrails are missing or unclear, prefer skipping the candidate.

Also skip anything that:
- Is imported dynamically
- Is registered indirectly through framework wiring or reflection
- Is imported only for side effects
- Is generated or codegen-linked
- Is a config, migration, script, seed, fixture, or infrastructure file
- Looks risky or unclear

For each candidate, read the file and verify it is genuinely safe before acting.

## Step 3 - Apply changes

Delete unused files or remove unused exports.

Never touch more than 10 files in one run.

This automation is incremental. It does not need to clean everything in one pass.

## Step 4 - Validate

Run the relevant validation commands for the apps, packages, or surfaces affected by your changes. If the repo has no obvious local validation command, keep the PR draft and say what was not run.

Ignore pre-existing errors. Only look for new failures caused by your changes.

If a change causes a new failure, revert only the change introduced in this run and continue.

If more than 3 changes need to be reverted, revert all changes from this run and stop.

## Step 5 - Prepare review output

If nothing was safe to remove, do not open a PR. End the run with a short summary of why nothing changed.

If you made safe changes that passed validation:
- Create a branch using the repository's normal branch naming convention when it is obvious. Otherwise use: `chore/dead-code-sweep-YYYY-MM-DD`
- Create a commit using the repository's normal commit naming convention when it is obvious. Otherwise use: `chore(code-health): remove safe dead code`
- Open a draft PR using the available GitHub integration

If no GitHub integration is available, prepare the branch name, commit message, PR title, and PR body, then stop.

## PR body

Use this structure:

---

## Summary

_1-2 sentence overview of what was removed._

## Changes

| # | File | What was removed | Rationale |
|---|------|------------------|-----------|
| 1 | `path/to/file.ts` | Deleted file | Zero importers and no framework registration found |
| ... | | | |

## Validation

- Relevant validation commands: passed / failed / not run
- Changes reverted: N

## Skipped findings

_Items from the dead-code report that were not safe to auto-remove._

<details>
<summary>Full report</summary>

_Paste the main dead-code report here._

</details>

How It Works

Runs knip and reads both the report and diagnostics output.
Picks a number of obviously safe dead-code candidates.
Removes safe unused files or exports conservatively.
Runs validation for the affected surfaces and opens a draft PR or prepares PR-ready output.

sequenceDiagram
    participant Agent
    participant Knip
    participant Repo
    participant PR as Git Provider

    Agent->>Knip: Run dead-code scan
    Knip-->>Agent: Unused files and exports report
    Agent->>Repo: Remove safe dead code
    Agent->>Repo: Run repo validation
    Agent->>PR: Open draft PR
    Note over Agent: Skip unclear or risky candidates

Prerequisites

Node.js 20.19.0+ or Bun, per Knip v6 requirements
knip is available in the repo or runner environment
GitHub or equivalent PR tooling if you want automatic PR creation

Knip Setup

Preferred setup is a repo-local knip script. One common setup is:

pnpm create @knip/config

Or install it manually:

pnpm add -D knip typescript @types/node

Then add a script such as:

{
  "scripts": {
    "knip": "knip"
  }
}

Runner-only fallback:

pnpm dlx knip

For ephemeral runners this is often better than a global install.

Cursor Cloud Usage

Open Cursor Automations.
Name your automation and paste dead-code-sweep.md as the automation prompt.
Add trigger conditions.
Add the Open Pull Request tool, or let the agent use an existing GitHub CLI or plugin in the environment.
Make sure the runtime can execute pnpm knip or your chosen Knip fallback and the validation commands you expect.
Click Create.

Codex App Usage

Click Automation > New Automation.
Name your automation and paste dead-code-sweep.md as the automation prompt.
Set schedule or run manually and save the automation.
Add the GitHub plugin to Codex, or let Codex use an existing GitHub CLI/tool in the agent environment.
Make sure the environment can run pnpm knip or your chosen Knip fallback and the validation commands relevant to your repo.

Claude Code Usage

No extra MCP setup is required for this automation.
Make sure the runtime can execute a Knip command and the validation commands you expect. Preferred: repo-local knip script. Fallback: pnpm dlx knip in ephemeral runners.
For repeated checks in an open Claude Code session, use /loop, for example:

/loop 1d Follow the instructions in automations/dead-code-sweep/dead-code-sweep.md

For durable Claude-managed automation that survives outside the current session, use /schedule or create a Routine in claude.ai/code/routines.

Recommended Defaults

This automation assumes:

repo-local scan command: pnpm knip --reporter markdown > .artifacts/dead-code.md 2> .artifacts/dead-code.stderr
runner fallback scan command: pnpm dlx knip --reporter markdown > .artifacts/dead-code.md 2> .artifacts/dead-code.stderr
report path: .artifacts/dead-code.md
diagnostics path: .artifacts/dead-code.stderr

Setting	Default
Max candidates per run	`3`
Max files changed per run	`10`
Branch	`chore/dead-code-sweep-YYYY-MM-DD`
Commit message	`chore(code-health): remove safe dead code`
PR mode	`Draft`

Keep the run conservative: skip unclear candidates, skip framework-managed files unless registration is obvious, and keep the PR draft when validation is partial.

Prompt Inputs

Add context only when repo guardrails or validation are not obvious, for example:

Skip anything under enterprise/.
Do not remove *.module.ts, main.ts, package.json, tsconfig*, or *.config.*.
For validation, run:
pnpm --filter api exec tsc --noEmit
pnpm --filter web exec tsc --noEmit

Docs