simplify-codebase: an Agent Skill that makes you prove a deletion before you make it

The problem simplify-codebase targets is maintenance burden, not line count

Most cleanup tooling optimizes for what can be deleted. simplify-codebase optimizes for something narrower: whether a change reduces the number of facts, states and contracts the team has to keep consistent afterwards. The README states the principle directly, that deleting lines of code is only the result and the real gain is removing a fact, a state, a contract or a concept that would otherwise need long-term maintenance.

The project is aimed at engineers working on existing repositories, not greenfield ones. The README lists the shapes redundancy actually takes: duplicated state, abstractions that no longer have an owner, interfaces that only tests still consume, compatibility paths that stopped being valid, and half-finished features left inside shared files. None of those are reliably detectable by a linter, which is the gap this skill occupies.

It is delivered as an Agent Skill rather than a standalone binary. The repository carries a SKILL.md as the main workflow and judgment criteria, plus a references/ directory with separate files on investigation, boundaries and lifecycle, execution and recovery, decision records, and integrating findings. The audience is therefore people already running a coding agent that reads SKILL.md, most explicitly Codex.

Focused versus Broad, Survey versus Change: the four modes in SKILL.md

The workflow is a two-by-two grid. One axis is scope: Focused digs into a single subsystem, state machine or suspected duplication point, while Broad partitions the whole repository and returns candidates, counter-evidence and blind spots. The other axis is intent: Survey is read-only audit, Change is authorized modification.

Change work is batched along ownership boundaries, and each batch is verified independently. That matters because a single passing narrow test is not treated as evidence of correctness. The README says explicitly that a small-scope test passing will not be packaged as full runtime or user acceptance.

Every candidate has to produce a proof record with a fixed set of fields. According to the README, that record must state which ownership boundary, symbol and file the candidate sits in, with line numbers where they can be verified; what maintenance burden it adds; who the production, test, dynamic and external consumers are; where the complete deletion boundary falls, including members inside shared files; what observable behavior or compatibility would be given up; which minimal verification would reveal a wrong deletion; and whether the complexity reduction outweighs any migration or replacement mechanism introduced.

The skill is also allowed to conclude that nothing should be removed. The README states that when a real consumer is found, a boundary is not yet clear, or the simplification merely moves complexity elsewhere, the recommendation is to keep the code rather than force a deletion to produce output. That is an unusual default for a tool in this category and it is the part most worth reading SKILL.md for.

Installing the skill into a Codex skills directory

The README gives two installation routes. The first is to ask Codex to install it from the repository URL. The prompt is short and the agent handles the placement.

Install the simplify-codebase skill from https://github.com/tt-a1i/simplify-codebase

The second is manual. Clone the repository into the user-level Codex skills directory. The README uses exactly this path.

git clone https://github.com/tt-a1i/simplify-codebase.git \
  ~/.codex/skills/simplify-codebase

After installing, the README says to start a new task so the skill directory is reloaded. Other agent environments that support SKILL.md can place the repository in their own skills directory instead; the README does not enumerate which ones.

One packaging detail worth noting: the interactive Cleanup Map is bundled inside the skill and does not require a separate Archify install. The renderer needs Node.js 18 or higher and pulls in no additional npm packages, and the README states the delivered HTML does not request external fonts.

A first run: audit without writing, then narrow to one question

The safest first use is the read-only survey over the whole repository. The README provides this prompt verbatim, and the instruction not to modify files is part of it.

使用 $simplify-codebase 审计这个仓库，列出最安全、收益最高的简化候选。不要修改文件。

What comes back, per the README, is coverage, ranked proof records, important counter-examples, open questions and the next piece of evidence needed. Expect a document, not a patch. If the output is a diff, the skill was not in Survey mode.

A second prompt narrows to a single ambiguity. The README's example is about readiness flags that might express different lifecycle guarantees or might be duplicate state.

使用 $simplify-codebase 判断这些 readiness 标志是在表达不同的生命周期保证，还是重复状态。

Only after a candidate has been proven safe does the Change prompt make sense. The README's wording asks for the deletion, preservation of still-valid contracts, verification, an operation receipt and a rollback path.

使用 $simplify-codebase 删除一个高置信度的偶然复杂度来源。保留仍然有效的契约，完成验证，并给出操作回执和撤销路径。

Visual output is opt-in. The README says the default deliverable is the full text report, and that even when a question spans multiple components, states or consumers, the skill first explains what a diagram would clarify and waits for confirmation before generating one. The schema and renderer live in visualization/, with cleanup-map.schema.json as the semantic contract and render-cleanup-map.mjs as the compiler.

Where the proof-record model breaks down

The method depends on the agent being able to trace consumers, and the README itself concedes the limits. Static checks, it says, can provide clues but cannot by themselves prove a deletion is safe. The skill compensates by chasing runtime consumers, dynamic registration, persisted formats, public interfaces, historical decisions and verification boundaries. That is a research process, and research processes have a failure mode: the absence of a found consumer is not proof that no consumer exists.

The README handles this by allowing an unresolved verdict, and by asking for the next piece of evidence needed rather than a decision. In practice that means a Broad survey of a large repository can return a long list of candidates marked unresolved. If you were hoping for a cleanup queue you can work through mechanically, this is the wrong shape of tool.

The skill is also explicit that it cannot replace product decisions. Deleting a still-reachable capability, a supported interface, a persisted representation or a compatibility path requires explicit authorization from the user. So the tool will not tell you whether a feature should die; it will tell you what would break if it did.

Finally, the visual layer is a companion, not a substitute. The README states the text proof record is the authoritative result, that a diagram does not replace consumer proof, the Change operation receipt or the rollback path, and that when topology is unproven or the diagram adds no explanatory value, the full text report with precise file locations is what you keep. The bundled renderer is also scoped: the Architecture renderer, the Signal Flow visual system and the desktop viewer runtime were brought in, while other diagram types, the repository CLI, and the publishing and gallery flows were not.

How it differs from linters and from a plain agent cleanup prompt

The obvious comparison is a static analysis or dead-code tool. The difference is the evidence standard. A linter reports that a symbol has no reference in the analyzed source. simplify-codebase asks a broader question first: who consumes this at runtime, through dynamic registration or a plugin path, through a persisted format that has to stay readable, through a public interface, or from outside the repository entirely. The README lists exactly those categories as things the skill treats carefully, alongside authorization, isolation, input validation, data-loss protection, concurrency, cancellation, cleanup, lifecycle ownership, generated files, shared resources and still-valid ADRs, RFCs and architecture constraints.

The second comparison is a bare agent instruction like "remove dead code from this repo". That produces a diff with no artifact explaining why each removal was believed safe. simplify-codebase produces a proof record per candidate and, in Change mode, a layered verification result, residual risk, an operation receipt and an executable rollback path. Whether that overhead is worth it depends on how expensive a wrong deletion is in your system. For a small application with a fast test suite, a plain prompt plus a green build may be sufficient. For anything with persisted data, external consumers or plugin registration, the proof record is the part that survives review.

Maintenance, licence and what to check before relying on it

The repository is not archived, and the last push was on 2026-09-04. There are no retrieved releases, so installation is from the default branch rather than a tagged version. That has a practical consequence: pinning to a commit is the only way to get a reproducible skill, since the clone command in the README tracks main.

The project is MIT licensed. The visualization directory carries its own provenance note, with sources, modification boundaries and the MIT licence retained under visualization/, because the bundled renderer and viewer core come from Archify. If you plan to redistribute the generated HTML or the renderer, read that directory rather than assuming the top-level LICENSE covers every file in the same way. This is a description of what the repository states, not legal advice.

On quality evidence, the README claims validation across Change, Broad, Integration and Decision-record scenarios, and a full-repository audit on a 973-file Python and TypeScript project. The test method and known boundaries are said to be recorded in docs/validation.md. That file is the first thing to read before trusting the workflow on your own repository, because it is where the project documents what it has and has not exercised. The README does not document rollback for the skill installation itself, only the rollback path expected as part of a Change operation.

Editorial conclusion

Adopt simplify-codebase if you maintain a repository where dead-looking code might still be reachable through dynamic registration, persisted formats or external consumers, and you want the reasoning written down before anything is deleted. Do not use it as a blanket cleanup pass on a codebase nobody understands, and do not expect it to make product decisions about which capabilities are allowed to disappear. Before your first run, read SKILL.md for the judgment criteria and docs/validation.md for the tested scenarios and known limits, then start with the read-only survey prompt so the first output is a ranked candidate list rather than a diff.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. tt-a1i/simplify-codebase on GitHub