simplify-code

A portable Agent Skill that simplifies a codebase safely and incrementally from any agent runtime — Claude Code, GitHub Copilot (CLI / VS Code), pi, Codex CLI, Gemini CLI, Cursor.

It reduces complexity, nesting, duplication, magic numbers, dead code, and long functions while preserving behavior — detecting opportunities mechanically with a bundled ast-grep engine, ranking the biggest wins, and applying fixes one at a time with build/test verification.

Why it stays fast and cheap

• Codebase out of context. ast-grep finds + ranks candidates mechanically; the model reads only the flagged spans, from a small JSON ledger on disk.
• Two-track apply. Mechanical fixes are applied by deterministic ast-grep autofix rules (zero model tokens, zero hallucination); only genuinely semantic refactors go to the model.
• Resumable. Progress is a status field in simplify/findings.json; reruns skip finished work.

Design constraints (deliberate)

• No Python, no .sh/.ps1/make. The engine is one cross-platform binary (identical CLI on Win/macOS/Linux); the command sequence lives in SKILL.md and the agent issues OS-appropriate invocations. Detection rules are declarative YAML.
• Self-contained. ast-grep is bundled per platform under bin/ (see bin/README.md); no install step, works offline.
• JSON end-to-end for the ledger (matches ast-grep --json); the only YAML is ast-grep's own mandated rule/config format.
• Framework-agnostic. Build/test/lint commands are inferred by the model once and cached in the ledger — never hardcoded.

Layout

SKILL.md            entry point (read this first)
sgconfig.yml        ast-grep project config → rules/
bin/                bundled ast-grep binary per platform
rules/<lang>/       ast-grep rule packs (detect + autofix)
references/         PATTERNS · DETECTION · OPTIMIZATION · PORTABILITY
assets/             ledger.schema.json
fixtures/           messy sample code for validating the skill

Install

Copy or symlink this directory into your runtime's skills location — see references/PORTABILITY.md for per-OS, per-runtime instructions. Then ask your agent to "simplify this codebase" (preview) or "simplify and apply".

Languages

JS/TS, Python, Go, Rust, Java today (ast-grep supports 20+; add a rule pack to extend). Svelte/SvelteKit is supported specially (no built-in grammar): detection leans on the project's own Svelte tooling + model-driven refactors with SvelteKit guardrails, with an opt-in ast-grep grammar path — see references/SVELTE.md.

License: MIT.