reclaim-code-entropy README

The project's README from github.com/Yevanchen/reclaim-code-entropy. As one markdown file: README.md.

Reclaim Code Entropy

An evidence-first Agent Skill for safely simplifying any codebase.

English | 简体中文

The Problem

Codebases accumulate more than dead symbols. They accumulate duplicate truths, abandoned extension points, compatibility paths with no remaining consumer, lifecycle flags that describe the same transition, and wrappers that only move complexity around.

Static analysis can produce candidates. It cannot prove that a string-dispatched route, public export, migration, persisted format, plugin entrypoint, or asynchronous cleanup path is safe to remove.

The Solution

reclaim-code-entropy makes simplification evidence-driven:

Stage Question
Establish the contract What is public, persisted, generated, dynamic, or compatibility-sensitive?
Survey entropy Where are the extra representations, states, APIs, layers, and policies?
Prove the cut Who consumes it, why was it added, and what capability would disappear?
Simplify one boundary Can the obsolete contract be removed end to end without replacement glue?
Verify behavior What is the smallest check that would fail if the deletion were wrong?

The skill prefers a few proved cuts over a long speculative cleanup list. Finding nothing safe to remove is a valid result.

What It Finds

Modes

Audit mode ranks candidates by confidence, risk, tradeoff, and estimated net reduction. It does not edit the repository.

Apply mode implements the safest proved cut, preserves observable behavior, and runs proportional verification.

Install

Ask Codex:

Install the reclaim-code-entropy skill from https://github.com/Yevanchen/reclaim-code-entropy/tree/main/skills/reclaim-code-entropy

Start a new Codex task after installation.

Option B: Manual install

git clone https://github.com/Yevanchen/reclaim-code-entropy.git
mkdir -p ~/.codex/skills
cp -R reclaim-code-entropy/skills/reclaim-code-entropy ~/.codex/skills/

Use

Audit a repository without changing it:

Use $reclaim-code-entropy to audit this repository and rank the safest simplification candidates.

Apply the strongest safe cut:

Use $reclaim-code-entropy to simplify this repository. Preserve public and persisted behavior, implement one high-confidence cut, and verify it.

Investigate a specific area:

Use $reclaim-code-entropy to check whether these lifecycle flags represent distinct states or duplicated ownership.

Key Insight

Deletion volume is not the goal. The goal is reducing the number of facts, contracts, states, and concepts the team must keep coherent.

A large deletion can be wrong. A small deletion can remove an entire maintenance obligation. The decisive evidence is the consumer graph, ownership model, history, compatibility surface, and verification boundary.

How to Know It Is Working

A useful result is reviewable, reduces concepts without hiding compatibility risk, and may still conclude that no safe cut exists.

Safety Boundaries

The skill does not simplify away authorization, trust-boundary validation, accessibility basics, data-loss prevention, durable-data compatibility, or cleanup required for resource quiescence.

It is not a performance audit unless simplification is the stated goal.

Inspiration

The initial idea came from studying DeepSeek Harness and its emphasis on simplification during agent-driven development. This project generalizes that lesson for repositories in any language or stack. It is independent and not affiliated with DeepSeek.

License

MIT

reclaim-code-entropy (Yevanchen/reclaim-code-entropy)

Searching Database…

205 ·GitHub
Reclaim-code-entropy
What is this?This is an Agent Skill that guides an AI coding agent through safely simplifying a codebase by hunting down dead code, duplicate logic, and unnecessary abstractions using proof instead of guesswork.
Is this a static analyzer I run myself, or something an AI agent uses?It is not a standalone analyzer you run directly; it is a skill definition that an AI coding agent (like Codex) follows. The agent does the investigation, proving each cut is safe before removing anything.
How do I install this skill?The recommended way is to ask Codex to install it via the Codex skill installer and then start a new Codex task; there is also a manual install option described in the README.
Do I need a specific coding agent to use it?The install flow is built around Codex (you ask Codex to install the skill and run tasks with it), since it is packaged as a Codex-compatible Agent Skill.
Does it always find something to delete?No — the skill explicitly treats finding nothing safe to remove as a valid outcome, and Audit mode only ranks candidates without touching the repo; Apply mode implements just the single safest proved cut per run.
What is the difference between Audit mode and Apply mode?Audit mode ranks removal candidates by confidence, risk, tradeoff, and net code reduction without changing anything. Apply mode implements only the single safest proved cut, preserves observable behavior, and runs proportional verification.
What kinds of problems does it look for?It targets things like unconsumed APIs and exports, duplicate state representations, speculative abstractions, forwarding-only wrappers, duplicated lifecycle/cleanup logic, and hand-rolled code that duplicates platform features.
What won't it touch for safety?It avoids simplifying away authorization, trust-boundary validation, accessibility basics, data-loss prevention, durable-data compatibility, or cleanup needed for resource quiescence.
Why was this built, and where did the idea come from?The author took inspiration from studying DeepSeek Harness and its emphasis on simplification during agent-driven development, then generalized that idea into a skill usable on any codebase in any language.
What are similar projects?cyclomatic-complexity-skill, simplify-codebase, operator-memory, repowise, improve, pstack-claude, Coding-Agent-Skills, serenity-skill
Which topics is it in?refactoring, codex-skill, code-quality, code-review, static-analysis, agent-skill, harness, deepseek-harness, skill, agentic-ai, markdown, agent-skills
Creator
Yevanchen
Size
<0.1 MB
Stars
205
Updated
CommitAug 21
Age
2mo
Commits · 90 Days