tt-a1i/simplify-codebase

Simplify Codebase – an AI‑agent skill for safe code‑base cleanup

What it is

• A Skill (plugin) for AI coding agents (e.g., Codex, OpenAI‑based bots) that helps them audit an existing repository, prove that a piece of code can be removed safely, and then apply the removal while keeping a full evidence record.
• It is not a generic linter or dead‑code remover; it focuses on accidental complexity such as stale APIs, orphaned state, duplicated abstractions, or compatibility shims, and only deletes when the benefit outweighs the maintenance cost.

How it works

Mode	Scope	What it does
Survey (read‑only)	Focused – a single subsystem, or Broad – the whole repo	Scans files, runtime registrations, data formats, and external consumers to produce a ranked list of “simplification candidates” with proof records.
Change (authorised edit)	Same scopes	After a candidate is proven safe, the skill performs the deletion, runs the minimal verification suite, and emits a rollback plan.

Each candidate is accompanied by a proof record that lists:

• Ownership boundary, file and line numbers
• Maintenance burden it introduces
• Who (tests, runtime, external services) consumes it
• Exact deletion boundary (including shared file members)
• Compatibility or observable behavior that will be lost
• Minimal test that would catch an incorrect removal
• Net complexity reduction vs. migration cost

Key safeguards

• Never touches public APIs, plugin registration, data‑migration paths, concurrency primitives, or any artifact that still has verified consumers.
• If the real consumer cannot be identified, the skill recommends keeping the code instead of guessing.

Installation

# Recommended for Codex‑compatible agents
git clone https://github.com/tt-a1i/simplify-codebase.git ~/.codex/skills/simplify-codebase

• The skill can also be loaded by any agent platform that respects the SKILL.md metadata.
• It bundles a lightweight HTML renderer (Node ≥ 18, no extra npm packages) for optional visual reports.

Typical usage patterns

# 1️⃣ Audit the whole repo, no changes
$simplify-codebase audit --scope broad --dry-run

# 2️⃣ Investigate a specific flag or state
$simplify-codebase survey --focus readiness-flags

# 3️⃣ Apply a proven simplification
$simplify-codebase change --candidate 42 --apply

# 4️⃣ Merge findings from a PR
$simplify-codebase integrate --pr 123

# 5️⃣ Generate an interactive Cleanup Map (HTML)
$simplify-codebase report --visual

• Commands return a textual proof report by default; adding --visual produces a self‑contained HTML map that shows confirmed components and their relationships.

Outputs

• Survey report – coverage description, ranked proof records, counter‑examples, open questions, and next evidence needed.
• Change report – actual file diffs, layered verification results, residual risk assessment, operation receipt, and a reversible “undo” script.
• Optional visual report – an interactive desktop‑friendly HTML page built with the bundled Archify renderer; it only displays verified findings, never speculative runtime impact.

Maturity

• Validated on a 973‑file mixed Python/TypeScript project covering Change, Broad, Integration, and Decision‑record scenarios.
• Test suites and contract files live under visualization/test/ and docs/validation.md.

Contributing

• Issues and PRs are welcome, especially those that expose missed consumers, false‑positive deletions, or gaps in the verification flow.

License

• MIT (see LICENSE).

---

Simplify Codebase is a specialized AI‑agent extension that brings formal, evidence‑based pruning to large, legacy codebases, helping teams reduce long‑term maintenance load without risking hidden breakages.