simplify-codebase: an Agent Skill that makes you prove a deletion before you make it
Prove and remove accidental codebase complexity without breaking behavior.
At a glance
- What is it?
- This is a Codex-style Agent Skill for removing accidental complexity from existing repositories, built around a written proof record rather than a linter's verdict. Its value depends on whether your team will actually read the proof, and its own README admits the Skill cannot make product decisions for you.
- Who is it for?
- Adopt it on repositories where dead state, ownerless abstractions and half-removed compatibility paths have accumulated faster than anyone can audit them, and where a reviewer will read a written proof record before approving a diff.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 12 days ago.
- What is it written in?
- Mainly HTML, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem is redundancy that a linter can flag but cannot clear
Most dead-code tooling answers one question: is this symbol referenced? The README argues that is the easy case. The harder cases it names are duplicated state, abstractions that have lost an owner, interfaces whose only remaining consumer is a test, compatibility paths that no longer correspond to any supported version, and half-finished features parked in shared files. In each of those, a static check produces a lead, not a proof, because the thing being removed may still be reachable through runtime registration, a persisted format, a public interface, or a decision recorded in an ADR or RFC. The Skill is aimed at engineers maintaining a repository they did not write, where the cost of a wrong deletion is a production incident and the cost of a right one is a concept the team stops having to keep consistent. The README states the principle directly: deleting lines is the outcome, and the gain is deleting a fact, a state, a contract or a concept that would otherwise need long-term maintenance.
Two axes: Focused or Broad scope, Survey or Change mode
The workflow is a four-cell grid. Focused plus Survey means going deep on one subsystem, state machine or suspected duplication point. Broad plus Survey means partitioning the whole repository and returning candidates, counter-evidence and blind spots. Focused plus Change means proving and completing one clear simplification boundary. Broad plus Change means editing in batches along ownership boundaries, with each batch verified independently. That grid is the most useful thing in the README, because it tells you the Skill has a read-only mode and that you are expected to use it first. The prompts in the usage section map onto the grid: an audit of the whole repository with an explicit instruction not to modify files, an investigation of whether a set of readiness flags express different lifecycle guarantees or duplicate state, a removal of one high-confidence source of accidental complexity, and a pass that reviews and consolidates simplification suggestions from a pull request while keeping the evidence and discarding the candidate count.
The proof record is the actual product
Every candidate is supposed to produce a record answering seven questions: which ownership boundary, symbol and file it sits in, with line numbers where verifiable; what maintenance burden it adds; who the production, test, dynamic and external consumers are; where the complete deletion boundary lies, including members inside shared files; what observable behaviour or compatibility would be given up; which minimal verification would expose a mistaken deletion; and whether the reduction in complexity exceeds any migration or replacement mechanism introduced. That last item is the one most refactoring proposals skip, and it is the reason this Skill is not simply a delete-more tool. A Survey delivery is coverage plus ranked proof records plus important counter-examples plus open questions plus the next piece of evidence required. A Change delivery adds the actual diff, layered verification results, residual risk, an operation receipt and an executable rollback path. The README is explicit that a passing narrow test will not be presented as full runtime or user acceptance.
Getting it installed: a git clone into the Codex skills directory
There is no package manager step. The README offers two routes. The first is to ask Codex to install the skill, with the prompt text: Install the simplify-codebase skill from https://github.com/tt-a1i/simplify-codebase. The second is manual, cloning into the user-level Skill directory:
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 skill directory. The optional Cleanup Map does not need a separate Archify install: the renderer core is bundled under visualization/archify-core/, with cleanup-extension.* layering Survey and Change interactions on top. The renderer requires Node.js 18 or higher and pulls in no additional npm packages, and the README states the delivered HTML does not request external fonts. The repository layout puts the main workflow in SKILL.md, the product positioning in PRODUCT.md, agent metadata in agents/openai.yaml, and the detailed references under references/. The validation notes live in docs/validation.md and a report format example in docs/visual-report-example.md.
The visual layer is opt-in and deliberately narrow
The default delivery is the full text report. If the user explicitly asks for a visualization, the Skill can generate a validated desktop interactive HTML from the bundled renderer. If the user does not ask, the README says the Skill will first explain what a diagram would help clarify, and only generate one after confirmation. That is an unusual default, and it is a deliberate one: the README treats the proof record as authoritative and the diagram as a visual companion, not a replacement for consumer proof, the Change operation receipt or the rollback path. The visual contract is narrow on purpose. Only confirmed components and relationships are drawn, and the README warns against calling a relationship that is reachable on the diagram a runtime impact scope. The bundled renderer is the Architecture renderer, Signal Flow visual system and desktop viewer runtime from Archify, with Finding, Survey and Change phases, deletion boundaries and an on-demand evidence drawer added. Other diagram types, the repository CLI, publishing and the diagram library workflow were not carried over. Provenance, modification boundaries and the MIT licence are kept under visualization/.
Where it will disappoint you
The Skill has no mechanical enforcement. Nothing in the material describes a checker that fails a build when a candidate lacks a consumer analysis, so the proof record is a document a human or an agent must choose to honour. The README itself concedes the boundary: the Skill cannot replace product decisions, and removing still-reachable capability, a supported interface, a persisted representation or a compatibility path still requires explicit authorization from the user. That means the tool is at its weakest exactly where the stakes are highest, because the decision to delete a public endpoint or a persisted field is a product call the Skill can only surface. It is also the wrong tool for large mechanical refactors, where the bottleneck is edit volume rather than uncertainty. The validation section is thin in the material provided: the README states the release was validated across Change, Broad, Integration and decision-record scenarios and that a full-repository audit was performed on a 973-file Python and TypeScript project, with method and known boundaries in docs/validation.md. No benchmark numbers, no false-positive rates and no comparison against other tools appear in the README, and the primary language listed for the repository is HTML, which reflects the bundled renderer rather than the Skill's own logic. Treat the validation claim as a pointer to a document you should read, not as a measurement.
How it differs from a dead-code analyzer
The obvious comparison is a conventional dead-code detector such as a linter or a coverage-driven unused-export report. Those tools work by reachability analysis over a call graph and a test suite, and they output a list of suspects with confidence scores. simplify-codebase inverts the burden: instead of asking whether a symbol is reachable, it asks who the consumers are across production, test, dynamic and external surfaces, what behaviour would be lost, and what minimal verification would catch a mistake. The difference in practice is that a detector's output is a queue of deletions, while this Skill's output is a set of arguments you can disagree with. That is a real trade: the detector runs in CI and never forgets, while this Skill runs when someone invokes it and depends on the quality of the agent doing the reasoning. A team that wants continuous enforcement should keep its linter. A team that keeps discovering that the interesting redundancy is invisible to the linter is the audience here.
Maintenance cost and what the MIT licence leaves open
The Skill is a set of Markdown references plus a bundled renderer, so its own maintenance surface is documentation that must track how agents behave. The README's contribution section asks for failure cases, missed consumers, wrong-deletion risks and reproducible verification gaps rather than more rules, which is a reasonable sign that the maintainers expect the reference files to grow from evidence. The renderer pins a Node.js 18 floor and no npm dependencies, which keeps the install cheap and the supply chain small. The repository is MIT-licensed, including the bundled visualization directory, and the README states that provenance and modification boundaries for the Archify-derived renderer are recorded there. MIT permits reuse and modification with the licence and copyright notice retained; it provides no warranty, and it does not resolve questions about the licence terms of anything you point the Skill at. None of this is legal advice, and if you plan to redistribute the bundled renderer inside a product, read visualization/ and the upstream Archify terms yourself rather than relying on the badge.
Editorial conclusion
Adopt it on repositories where dead state, ownerless abstractions and half-removed compatibility paths have accumulated faster than anyone can audit them, and where a reviewer will read a written proof record before approving a diff. Skip it if you need automated refactoring at scale, if your complexity lives in code no agent can inspect (generated artifacts, vendor drops, external consumers you cannot enumerate), or if the team will treat the Skill's output as a verdict rather than a proposal. Before trusting a first run, open references/boundaries-and-lifecycle.md and docs/validation.md, then run the read-only audit prompt on one subsystem and check whether the candidate list names real consumers or only plausible ones. The Skill's own README states that removing still-reachable capabilities, supported interfaces, persisted representations or compatibility paths requires explicit authorization from the user, so the gate is a human, not the tool.
Community notes