Audit-first recovery for troubled, inherited, legacy, or AI-built software repositories.
Codebase Rescue establishes a reproducible baseline, maps the system, checks whether the tests can be trusted, and recommends the safest next move:
- stabilization
- staged refactoring
- clean-room rebuilding
- bounded discovery when the evidence is not strong enough yet
It works across languages and frameworks, with additional guidance for JavaScript/web and Swift/iOS projects.
Install this folder as a skill, then ask your coding agent to audit the repository.
| Agent | Install path |
|---|---|
| Codex | .agents/skills/codebase-rescue/ |
| Claude Code | .claude/skills/codebase-rescue/ |
Plain language is enough to trigger it:
Audit this repository, establish an evidence-backed baseline, and propose a safe recovery plan before changing product code.
Codex also accepts the explicit form:
Use $codebase-rescue to audit this repository.
Audit outputs are kept in .codebase-rescue/:
- inventory.json
- SYSTEM_MAP.md
- RISK_REGISTER.md
- RECOVERY_PLAN.md
The skill never changes product code during the audit. It waits for explicit approval before starting checkpointed recovery work.
The audit does create .codebase-rescue/, which shows up as untracked in git status. Run the inventory with --output - for a zero-footprint pass, or add the directory to .git/info/exclude.
Standard-library Python 3.9+ on Unix-like systems. Neither script executes project code.
python3 scripts/inventory_repository.py [REPOSITORY] [--output -] [--allow-dir NAME] [--git-timeout SECONDS]
python3 scripts/init_reports.py [REPOSITORY] [--dry-run]
inventory.json reports what it could not see — warnings, excluded, submodules, and sensitive_files — so a partial scan is never mistaken for a complete one.
Run the tests with:
python3 -m unittest discover -s tests
Use assets/codebase-rescue-og.png as the 1200×630 OpenGraph or repository social-preview image. The skill metadata uses dedicated 256×256 and 512×512 icon exports so list and detail views do not load or crop the full cover.
The original codebase-rescue.png remains the source artwork:
