# 🧹 codemap **A code janitor for AI coding agents.** Point it at any repo and it draws an **interactive architecture map**, scores **every module 0–100** for technical debt, and helps you **pay down the cruft** β€” incrementally, one commit at a time. ![Claude Code skill](https://img.shields.io/badge/Claude%20Code-skill-f59e0b) ![works with Codex](https://img.shields.io/badge/works%20with-Codex%20%2F%20any%20agent-7c8794) ![Python 3 Β· stdlib only](https://img.shields.io/badge/python-3%20Β·%20stdlib%20only-3776ab) ![language agnostic](https://img.shields.io/badge/langs-Py%20Β·%20TS%20Β·%20Rust%20Β·%20C%23%20Β·%20C%2B%2B-555) ![license MIT](https://img.shields.io/badge/license-MIT-blue) > Every codebase accumulates cruft over time β€” monkeypatches, silent fallbacks, dead > "legacy" paths, half-finished stubs, copy-pasted duplication, god-files, and valueless > glue. **codemap surfaces that rot, ranks it, and hands an AI agent a clear punch-list to > fix it** β€” with a regression-gated fix loop so the cleanup never breaks your build. ![architecture map](examples/01-map.png) --- ## Why codemap Most "architecture diagram" tools draw *files and imports*. codemap is different: - **Functional modules, not files.** It groups code into the capabilities that actually matter (a store, a handler group, a feature, a plugin) and lays them out along the real data-flow. - **It grades the rot.** Every module gets a health **score (0–100) and grade (A–F)** plus concrete `file:line` findings, hunting specifically for the smells that make code unmaintainable: `monkeypatch`, `fallback`, `silent-except`, `legacy`/dead code, `stub`, `fake-output`, `dual-format`, `bloat`, `duplication`, `glue`, `god-component`, … - **Independent, honest scoring.** Each module is audited by a **separate AI subagent** against a fixed rubric β€” no single pass rubber-stamping the whole repo. - **Incremental + git-aware.** A per-module content hash + the last-run commit mean re-runs only re-audit what changed, and `update` shows you the **commits since last time** and which modules they touched. - **Cleanup that can't regress.** `fix` runs a four-role loop β€” lock a test baseline β†’ fix β†’ an **independent acceptance check** proves the pre-fix tests still pass β†’ re-score. It's the maintenance pass you never have time to do, turned into something an agent can run on a schedule. ## Screenshots **Click any module** to highlight what it calls (downstream) and what depends on it (upstream), with its score, smell tags, and `file:line` findings: ![Select a module β€” dependencies + audit](examples/02-module.png) The **Audit report** β€” averages, grade spread, worst offenders, smell-tag frequency, and cross-cutting themes: Audit report panel - **Health vs coupling** color modes β€” problems pop amber/red, healthy modules recede to a muted green (colorblind-friendly; the cue is saturation, not just hue). - **Filter** by grade (≀ B/C/D/F) or by issue tag; jump straight to the worst offenders. - **Editable Standard page** β€” change descriptions, **add your own issue tags** to capture *your* definition of a problem, and Export to `standard.json`; future audits use it. - **i18n** β€” English or Chinese UI (`meta.lang`); module names are never translated. - **Copy-fix button** on each module β€” copies `/codemap fix ` to paste into your agent. ## Languages Language-agnostic. LoC and hashing work on **any** text source and `paths` are plain globs, so it covers **Python, TypeScript/JS, Rust, C#/.NET, C/C++, Go, Java, Swift**, and more. Build/test/generated trees are excluded out of the box (`target/`, `bin/`, `obj/`, `node_modules/`, `cmake-build*`, `__pycache__/`, `dist/`, `*.d.ts`, `*.Designer.cs`, …). The rubric names *behaviors*, not syntax β€” `reference/STANDARDS.md` maps each smell to its per-language form (e.g. `any-escape` = `as any` / `dynamic` / `void*` / `reinterpret_cast` / `unsafe`). ## Requirements - **Python 3** β€” standard library only. No `pip install`, no external packages. - **An AI coding agent** to drive the audit/fix/test steps β€” **Claude Code**, **Codex**, **Cursor**, or any agent that reads instructions and spawns sub-tasks (see Install). - A browser to open the generated HTML. That's it. ## Install codemap is one self-contained folder. Clone it once, then wire it into whichever agent you use β€” the engine (Python scripts + the `SKILL.md` / `AGENTS.md` / `reference/STANDARDS.md` workflow) is identical for all of them. **Claude Code** β€” skills live under `~/.claude/skills/`, so clone it straight there: ```bash git clone https://github.com/Asixa/codemap-skill ~/.claude/skills/codemap ``` Restart Claude Code; it shows up as **`/codemap`**. **OpenAI Codex** β€” Codex auto-reads `AGENTS.md`. Clone the repo, then add one line to your project's `AGENTS.md` (or `~/.codex/AGENTS.md`): ```bash git clone https://github.com/Asixa/codemap-skill ~/.codemap ``` > For architecture maps / code audits, use the codemap tool at `~/.codemap` β€” follow its `AGENTS.md`. **Cursor** β€” clone it, then add a project rule at `.cursor/rules/codemap.mdc`: ```bash git clone https://github.com/Asixa/codemap-skill ~/.codemap ``` > Use the codemap tool at `~/.codemap` for architecture maps / code audits β€” follow its `AGENTS.md`. **Any other agent** (Windsurf, Aider, Cline, …) or **by hand** β€” clone it anywhere and tell the agent: *"Use the codemap tool at `~/.codemap`; follow its `SKILL.md`, and score each module with a separate sub-task per `reference/STANDARDS.md`."* The deterministic scripts (`scan` / `query` / `render` / `apply_audit`) also run standalone with no agent at all. > Windows PowerShell: replace `~` with `$env:USERPROFILE` (e.g. `$env:USERPROFILE\.claude\skills\codemap`). ## Usage Talk to your agent in plain language, or use the subcommands (shown as Claude Code slash commands β€” say the same verb to any other agent). On the first run, codemap asks your preferences (UI language, output location, project title) and saves them to `/.codemap/config.json`. Everything it produces lives in `/.codemap/`. | Command | Does | |---|---| | `/codemap init` | first build: ask prefs β†’ decompose into modules β†’ scan β†’ audit every module β†’ render | | `/codemap check` | read-only: is the map stale? shows commits since last run + drifted / new / deleted modules | | `/codemap update` | incremental + git-aware: re-audit only changed modules, re-render | | `/codemap test ` | generate a regression-net of tests for a module | | `/codemap fix ` | regression-gated cleanup: lock baseline β†’ fix β†’ independent acceptance β†’ re-score | The deterministic scripts (no AI needed) can also be run by hand: ```bash S=~/.claude/skills/codemap # what changed since last run β€” a `git` block lists commits + affected modules python3 $S/scripts/scan.py --root . --state .codemap/modules.json # cache the current HEAD as the new baseline (end of an update) python3 $S/scripts/scan.py --root . --state .codemap/modules.json --stamp-rev # pick targets cheaply, without reading the whole state (for agents) python3 $S/scripts/query.py --state .codemap/modules.json --max-grade C --format ids python3 $S/scripts/query.py --state .codemap/modules.json --tag dual-format # regenerate the HTML + report from the state python3 $S/scripts/render.py --state .codemap/modules.json --template $S/assets/template.html \ --out-html .codemap/codemap.html --out-md .codemap/codemap.md ``` > On Windows use `python` instead of `python3`. ## How it works ``` modules.json ──scan.py──▢ + LoC, content hash & git diff (stale = hash != auditedHash) β”‚ (decomposition + module descriptions: authored by the agent) │◀─apply_audit.py── one INDEPENDENT subagent's score per module (fixed rubric) │◀─query.py────────── token-cheap targeting (by grade / tag / severity / staleness) └──render.py────────▢ codemap.html + codemap.md ``` `modules.json` is the source of truth (commit it for an audit history); the HTML/MD are pure projections, regenerated by `render.py`. **Four separate subagent roles, never merged:** *auditor* (scores), *test-author* (writes tests), *fixer* (changes code), *acceptance/verifier* (proves no regression). Tests are the regression net and are kept out of a module's own audit scope. ## Customizing the standard (define your own code smells) The scoring standard is **data, not code** (`reference/standard.json`: rubric, severities, coupling, and issue tags with descriptions). Open the **Standard** page in the map β†’ **Edit** β†’ tweak descriptions, **add your own tags**, then **Export** to `/.codemap/standard.json`. Custom tags flow through the whole map and are used by future audits. The prose version + the exact subagent prompt live in `reference/STANDARDS.md`. ## Repository layout ``` codemap/ SKILL.md # the orchestration the agent reads AGENTS.md # entry point for Codex / other agents README.md LICENSE # MIT reference/ STANDARDS.md # scoring rubric, smell taxonomy, severities, subagent prompts DATA_MODEL.md # modules.json schema standard.json # the machine-readable default standard (overridable per project) scripts/ # deterministic, stdlib-only Python scan.py # LoC + content hash + git diff + staleness query.py # filter modules (grade/tag/severity/…) β†’ ids/paths/findings apply_audit.py # merge one subagent's audit into the state render.py # modules.json β†’ HTML + report assets/ template.html # the interactive map shell (data injected at render time) examples/ # the screenshots above ``` ## License [MIT](LICENSE) Β© 2026 Xingyu Chen. --- Keywords: code quality Β· technical debt Β· refactoring Β· code janitor Β· legacy code cleanup Β· architecture visualization Β· dependency graph Β· static analysis Β· code audit Β· Claude Code skill Β· Codex Β· AI agents Β· code rot Β· cruft Β· code smells.