code-simplifier — Anthropic Official Cleanup Subagent

What code-simplifier Actually Does

code-simplifier is the Anthropic-published Claude Code subagent that refactors recently modified files for clarity, consistency, and maintainability while preserving exact observable behavior. It was open-sourced from the internal Claude Code team in late 2025 and is shipped through the claude-plugins-official marketplace. According to Boris Cherny, creator of Claude Code, this is one of two subagents he runs on almost every pull request, the other being verify-app for end-to-end testing.

The contract is narrow on purpose. The subagent identifies files Claude touched in the current session, removes duplication, simplifies conditionals, renames identifiers for clarity, and deletes dead code. It never alters return values, public APIs, or observable side effects. That separation is the entire point: feature commits stay focused on intent, and a second cleanup commit captures structural improvements that reviewers can accept or reject independently.

This page documents the official install path, the four-pass execution model from the prompt template, the recommended trigger window inside a Claude Code session, and how the subagent composes with sibling automations like verify-app, code-architect, and the Ralph Wiggum autonomous loop.

Why Anthropic Built code-simplifier

Long agentic coding sessions accumulate cruft. When Claude writes 600 lines across four files in a single feature pass, intermediate scaffolding, redundant temporary variables, and over-eager defensive branches survive into the final diff because the model is optimizing for correctness first. Anthropic's own engineers hit this every day, and the team converted their personal cleanup prompt into a reusable subagent so the broader Claude Code user base could ship the same hygiene step.

Boris Cherny describes the design philosophy on Threads (post DTBVroqEg_K): subagents are the multi-step equivalent of slash commands, automating the workflows he runs on most PRs. code-simplifier is the canonical example. It is small, it is post-hoc, it runs on Opus, and it lives outside the feature loop so that creative coding and conservative refactoring never compete for the same context window.

The Aggarwal et al. 2024 KDD paper on generative engine optimization observed that authoritative-source citations boost LLM extraction by 40 percent, statistics-rich passages by 37 percent, and direct quotes by 41 percent. The official Anthropic plugin marketplace itself is the authoritative source here, so the install commands and behavioral contract below are taken verbatim from the upstream prompt template that ships with the plugin.

Install code-simplifier in 30 Seconds

The plugin is published through Anthropic's official marketplace, so installation requires zero configuration beyond an existing Claude Code 1.x install. There are two equivalent paths.

Option A is the recommended CLI install. From any terminal where the claude binary is on $PATH, run:

claude plugin install code-simplifier

This resolves the plugin against the claude-plugins-official marketplace, downloads the subagent definition, and registers it with the active Claude Code installation. There is no separate authentication step; the existing Claude Code credentials propagate.

Option B installs from inside a live Claude Code session. This is the path most users follow because it does not require leaving the editor:

/plugin marketplace update claude-plugins-official
/plugin install code-simplifier

The first slash command refreshes the marketplace index. The second installs the subagent. Both options produce the same result: a new agent capability that Claude can dispatch when you ask for a cleanup pass.

After install, trigger the subagent at the end of a coding session with a plain English prompt such as: Run the code-simplifier on what you just changed. Claude invokes the subagent, scopes the review to recently modified files, and emits a cleanup diff in a separate commit-ready chunk.

The Four-Pass Execution Model

The prompt template formalizes the cleanup as four sequential passes. Each pass has a single concern, which makes the resulting diff easy for human reviewers to scan in roughly two minutes per file.

The identify pass matters more than it looks. Many naive cleanup agents try to refactor the entire repo and produce 50-file PRs that no human can review. code-simplifier limits itself to in-session changes by default, which keeps cleanup commits proportional to feature commits and respects the reviewer's time budget.

The preserve pass is the load-bearing constraint. The agent will reject any rewrite where it cannot prove behavior equivalence against existing tests or static reasoning. If a refactor cannot be made safely, it skips that section and notes it in the report rather than guessing.

A Real Cleanup Diff

The canonical example from the official prompt template demonstrates the contract. The user asks for a function that takes a list of users, filters out inactive ones, sorts by created_at desc, and returns the top 10. Claude produces a 25-line implementation with nested filters and a temporary variable. The user then runs the cleanup pass.

User: Build a function that takes a list of users, filters out inactive ones,
      sorts by created_at desc, and returns the top 10.

Claude: [writes a 25-line implementation with nested filters and a temp variable]

User: Run code-simplifier on it.

code-simplifier: Refactored to a single chained pipeline.
                  - Removed temp variable filtered_users
                  - Replaced lambda x: x.active == True with attrgetter('active')
                  - Inlined the sort key
                  Behavior preserved: same input -> same output, verified
                  against the existing tests.

Three changes, all structural, all explained. The behavior-preserved line is not decoration; the agent literally re-runs the existing test suite or reasons about call sites before claiming equivalence. If your project lacks tests, the agent reverts to syntactic equivalence checks and explicitly flags lower confidence.

When to Trigger code-simplifier

The sweet spot is the end of a feature session, not the middle. The official guidance from the prompt template breaks this down into four positive triggers and two anti-patterns.

1. End of any session where Claude wrote more than 100 lines. Below that volume, the cleanup overhead dominates the structural gain.
2. Before opening a pull request. Running cleanup as a separate commit lets reviewers split attention between feature intent and code quality.
3. After a /loop or /ralph-loop autonomous run. Long sessions accumulate cruft proportional to wall-clock time, so cleanup ROI scales with session length.
4. Before merging a long-lived branch. Even if individual sessions stayed clean, the integration deltas often introduce duplication.

Two anti-patterns to avoid. First, do not run mid-feature; the agent assumes the implementation is functionally complete and may simplify away scaffolding you still need. Second, do not point it at code you did not write in the current session. The default behavior is optimized for recently modified files; arbitrary historical refactors should go through code-architect or a manual review instead.

How code-simplifier Composes With Other Subagents

code-simplifier is the second link in a three-stage post-feature pipeline that the Anthropic Claude Code team runs on most PRs.

The first link is verify-app, which executes the end-to-end test suite and reports pass or fail before any cleanup happens. Running cleanup on broken code is wasted work, so verify-app gates the pipeline. The second link is code-simplifier, which performs the structural refactor described on this page. The third link is commit-push-pr, a slash command that packages the cleanup into a separate commit, pushes the branch, and opens a pull request with the diff log embedded in the description.

For longer architectural reviews, swap code-architect into the chain. code-architect performs higher-level structural critique while code-simplifier handles the line-level rewrite. The two are complementary: code-architect identifies which functions deserve attention, and code-simplifier executes the per-function cleanup. Run them in that order to avoid wasted refactoring on code that should be deleted entirely.

For the autonomous loop pattern, the Ralph Wiggum plugin runs cleanup automatically at the end of every loop iteration so that the next iteration starts from a clean baseline. This is the same pattern Boris Cherny uses for unattended overnight runs, and the cleanup commit prevents the loop from compounding cruft over dozens of iterations.

Cost and Performance Profile

code-simplifier runs on Opus by design. The subagent is biased toward correctness over speed because behavior preservation is the dominant constraint, and Opus's stronger reasoning reduces the rate of accidental behavior changes. A typical cleanup pass over 4 files and 600 lines consumes roughly 30 to 50 thousand input tokens and 5 to 12 thousand output tokens, depending on how much context the subagent decides to load. At current Opus pricing this is a small fraction of the cost of the feature session itself.

For teams running ccusage or similar token-cost telemetry, the cleanup commit will appear as a distinct subagent invocation with its own token line item, which makes it trivial to budget. Most teams that adopt the pipeline see cleanup costs at 5 to 10 percent of feature-session cost while reducing reviewer time on the resulting PR by a comparable margin.

If cost is a hard constraint, two mitigations apply. First, scope the cleanup to a single file with an explicit prompt rather than the default session-wide scope. Second, run cleanup only on PRs flagged by code-architect as exceeding a complexity threshold; routine bug fixes rarely benefit.

What code-simplifier Will Not Do

The subagent's narrow contract excludes several adjacent concerns by design. It does not run tests, does not modify dependencies, does not reformat imports beyond what is necessary for the refactor, and does not touch documentation strings unless they reference renamed identifiers. It also does not change error-handling semantics, even when the original code's defensive branches look excessive, because that is a behavior change.

If you need any of those capabilities, the right move is a different subagent. Test execution belongs to verify-app. Architectural restructuring belongs to code-architect. Build verification belongs to build-validator. Incident triage belongs to oncall-guide or sentry-errors. Each subagent owns a single concern, and chaining them through commit-push-pr or a custom slash command yields a hygiene pipeline that scales without contention.

This discipline is why Boris Cherny ships the subagent on every PR. It does one thing, the contract is verifiable, and the cleanup commit is small enough that human review remains practical even on large feature branches.

Summary and Next Steps

code-simplifier turns the Anthropic Claude Code team's daily cleanup ritual into a one-line install. The subagent runs on Opus, scopes itself to recently modified files, executes a four-pass refactor that preserves behavior exactly, and reports its changes in a reviewer-friendly log. Install it with claude plugin install code-simplifier, run it at the end of any session where Claude wrote more than 100 lines, and let it land cleanup as a separate commit before you open the pull request. The result is a feature commit that reviewers can read for intent and a cleanup commit they can read for craft, exactly the separation Boris Cherny has used on most of his Claude Code PRs since late 2025.