{"id":50706157,"url":"https://github.com/fraction12/deepclean","last_synced_at":"2026-06-09T12:01:36.998Z","repository":{"id":360568627,"uuid":"1250600803","full_name":"fraction12/deepclean","owner":"fraction12","description":"Local cleanup reports and agent-ready plans for codebases that need structural cleanup.","archived":false,"fork":false,"pushed_at":"2026-06-03T06:01:05.000Z","size":5511,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-03T06:06:34.578Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://fraction12.github.io/deepclean/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fraction12.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-26T19:45:44.000Z","updated_at":"2026-06-03T06:00:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fraction12/deepclean","commit_stats":null,"previous_names":["fraction12/deepclean"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/fraction12/deepclean","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fraction12%2Fdeepclean","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fraction12%2Fdeepclean/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fraction12%2Fdeepclean/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fraction12%2Fdeepclean/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fraction12","download_url":"https://codeload.github.com/fraction12/deepclean/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fraction12%2Fdeepclean/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34105565,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-09T12:01:36.125Z","updated_at":"2026-06-09T12:01:36.987Z","avatar_url":"https://github.com/fraction12.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"site/assets/cleeby-logo.png\" alt=\"Cleeby, the Deepclean mascot\" width=\"156\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003edeepclean\u003c/h1\u003e\n\nLocal repo structure reports for fast-moving codebases.\n\n\u003cp align=\"center\"\u003e\u003cem\u003eMeet Cleeby, Deepclean's little code-cleaning buddy.\u003c/em\u003e\u003c/p\u003e\n\n`deepclean` scans a repository, gathers local evidence, and writes reports and agent-ready plans under `.deepclean/`. It is built for the point where a project is already working and the next step is clearer boundaries, less duplication, safer refactors, stronger tests, and better sequencing.\n\nDeepclean is report-first. Source edits are only available through the explicit guarded fix lane.\n\nDocs: https://deepclean.mintlify.app\n\n## Status\n\nStable CLI with source-safe machine contracts. TypeScript, JavaScript, and Python evidence are supported.\n\n## Install\n\n```bash\nnpm install -g @fraction12/deepclean\ndeepclean --version\n```\n\nUpdate with:\n\n```bash\nnpm install -g @fraction12/deepclean\ndeepclean --version\ndeepclean doctor\n```\n\n`deepclean doctor` checks the installed package against the npm `latest` channel and warns when a newer version is available. Use `deepclean doctor --no-update-check`, `--offline`, or `--local-only` when the command must avoid network access.\n\n## Quick Start\n\n```bash\ndeepclean init\ndeepclean doctor\ndeepclean scan\ndeepclean report\ndeepclean status\ndeepclean next\ndeepclean show candidate-001\ndeepclean plan candidate-001\ndeepclean handoff candidate-001 --format codex\n```\n\n`deepclean scan` collects local evidence first, then runs Codex synthesis by default. Use evidence-only mode when you only want deterministic local analysis:\n\n```bash\ndeepclean scan --evidence-only --json\ndeepclean report\n```\n\nGlobal flags work before or after the command:\n\n```bash\ndeepclean --root ./some-repo scan\ndeepclean scan --root ./some-repo --evidence-only\n```\n\nOlder examples may include `deepclean scan --synthesize`; that flag still works, but it is no longer required. Plain `deepclean scan` is the normal synthesized path. Use `--evidence-only`, `--offline`, or `--local-only` when a run must avoid provider execution.\n\nFor the full source-safe flow from install through support artifacts, see [Beta Onboarding](docs/beta-onboarding.md).\n\n## Agent Skill\n\nDeepClean includes a project skill agents can load directly:\n\n- [skills/deepclean/SKILL.md](skills/deepclean/SKILL.md)\n\nCodex-style agents can find it through `AGENTS.md`. Claude Code can find it through `CLAUDE.md`. The skill is also included in the npm package so agents can copy or reference it from an installed DeepClean distribution.\n\n## Workflow\n\n```bash\ndeepclean init\ndeepclean map\ndeepclean scan\ndeepclean report\ndeepclean status\ndeepclean cluster\ndeepclean plan theme-001 --format codex\ndeepclean next\ndeepclean show \u003ccandidate-id\u003e\ndeepclean explain \u003ccandidate-or-finding-id\u003e\ndeepclean triage \u003ccandidate-id\u003e --status ignored --note \"intentional boundary\"\ndeepclean handoff \u003ccandidate-id\u003e --format codex\n```\n\n## What It Produces\n\nDeepclean writes durable local artifacts under `.deepclean/`:\n\n- `runs/` - scan metadata\n- `features/` - semantic feature/work-unit maps\n- `evidence/` - raw local evidence records\n- `synthesis/` - provider attempt ledgers, prompt manifests, and candidate validation results\n- `candidates/` - cleanup candidates\n- `clusters/` - related cleanup themes\n- `reports/` - Markdown and JSON reports\n- `plans/` - focused implementation plans\n- `handoffs/` - agent-ready task packets\n- `triage/` - local triage notes\n- `lifecycle/` and `revalidations/` - finding history and freshness checks\n- `fixes/` - local fix attempt ledgers and verification evidence\n\nAdd `.deepclean/` to `.gitignore` unless the repo deliberately wants to share generated reports.\n\n## JSON And Agent Use\n\nCore commands support `--json` for automation:\n\n```bash\ndeepclean scan --json\ndeepclean map --json\ndeepclean scan --evidence-only --json\ndeepclean status --json\ndeepclean review-pr --base origin/main --head HEAD --json --state-dir .octocheck/deepclean\ndeepclean report --json\ndeepclean cluster --json\ndeepclean plan theme-001 --json\ndeepclean next --json\ndeepclean show candidate-001 --json\ndeepclean explain candidate-001 --json\ndeepclean handoff candidate-001 --json\ndeepclean schemas --json\n```\n\nUseful global flags:\n\n- `--root \u003cpath\u003e`\n- `--state-dir \u003cpath\u003e`\n- `--config \u003cpath\u003e`\n- `--no-input`\n- `--quiet`\n- `--debug`\n\n`deepclean status --json` is the safest first command for a returning agent. It is read-only and reports the latest run/report, active queue, blocked items, stale artifacts, recent progress events, pending revalidation, latest artifact paths, locks, and a recommended next command.\n\n`deepclean review-pr --json` is the stable review-agent entrypoint. It runs source-safe local evidence for a PR diff and emits changed files, related findings, architecture neighborhoods, a risk summary, suggested verification commands, and prompt context. OctoCheck should own GitHub publishing; Deepclean supplies the context.\n\n`deepclean schemas --json` emits the GA-candidate JSON contracts for `review-pr` and the guarded autofix lane.\n\n## Guarded Fix Workflow\n\nDeepclean recommendations are not automatic fixes. The safe implementation loop is:\n\n1. Inspect one candidate with `deepclean show \u003ccandidate-id\u003e`.\n2. Generate a bounded plan with `deepclean plan \u003ccandidate-id\u003e`.\n3. Generate an agent handoff with `deepclean handoff \u003ccandidate-id\u003e --format codex`.\n4. Apply one local patch only through an explicit guarded fix path.\n5. Run verification and `deepclean revalidate \u003ccandidate-id\u003e` before treating the work as resolved.\n\n`deepclean fix --mode guarded` and `deepclean work --mode guarded` are intentionally gated. They require one target, explicit source mutation, current proof inputs, and verification. They do not publish packages, push branches, or open PRs unless an explicit PR workflow is requested and local proof passes.\n\nFor the GA autofix lane:\n\n```bash\ndeepclean fix \u003ccandidate-id\u003e --mode guarded --apply --verification \"npm test\"\ndeepclean fix \u003ccandidate-id\u003e --mode guarded --apply --branch chore/deepclean-fix --pr --verification \"npm test\"\n```\n\nOnly guarded mode is supported. Broad architecture redesign, ambiguous ownership changes, and fix classes Deepclean cannot prove remain outside the GA autofix contract.\n\nUse repeated `--verification` or `--verification-command` flags when one proof command is not enough. Deepclean runs every explicit verification command in order before recording the fix/work attempt as passing.\n\n## Local Evidence\n\nDeepclean runs local evidence first and model synthesis second unless evidence-only or local-only mode is selected. The built-in evidence layer includes:\n\n- semantic feature mapping for package scripts, TS/JS modules/routes/components, Python modules, test suites, and config files\n- file metrics\n- normalized line-window duplication\n- source/import graph summaries\n- TypeScript and JavaScript function structure\n- Python import graph support\n- git churn signals\n- nearby test discovery\n- SARIF ingestion from Semgrep or similar tools\n- optional Semgrep SARIF orchestration\n- optional `jscpd` duplicate ingestion\n\nFor TS/JS projects using NodeNext-style source imports, Deepclean resolves emitted `.js` specifiers back to local `.ts`, `.tsx`, `.mts`, and `.cts` files so the graph maps source boundaries instead of emitted-path noise.\n\n## Codex Synthesis\n\n`deepclean scan` runs the local `codex` CLI in read-only mode over the collected evidence bundle by default. The model is asked to return strict JSON, and candidates are validated before they are persisted: cited evidence IDs must exist, file paths must be anchored by cited evidence, line ranges must be sane, and optional quotes must match source. Rejected drafts stay in the synthesis attempt ledger as diagnostics rather than becoming open findings.\n\nUse `deepclean explain \u003ccandidate-or-finding-id\u003e` to inspect why a candidate exists, which evidence supports it, which validation checks passed, and what fix-readiness guidance was attached.\n\nSynthesis uses a built-in reviewer pack so runs do not depend on arbitrary local agent skills. The current pack looks for architecture boundaries, conceptual duplication, dependency graph risk, testability gaps, domain language drift, agent-sized cleanup slices, and weak findings that should be rejected.\n\nReviewer packs can be configured in `.deepclean/config.json`:\n\n```json\n{\n  \"reviewers\": {\n    \"enabled\": [\"architecture-deepening\", \"testability\", \"critic-pass\"],\n    \"customPaths\": [\"./deepclean-reviewers/security.md\"]\n  }\n}\n```\n\nSource samples are redacted from the synthesis prompt by default. Use `--allow-source-in-model` only when the target repository and provider configuration make that acceptable. Use `--evidence-only`, `--offline`, or `--local-only` when no provider should run.\n\nSee [Beta Onboarding](docs/beta-onboarding.md), [Privacy And Trust](docs/privacy-and-trust.md), [Reviewer References](docs/reviewer-references.md), and [Troubleshooting](docs/troubleshooting.md) before using synthesis on private repos.\n\n## Themes And Plans\n\n`deepclean cluster` groups related candidates into cleanup themes using shared files, shared evidence, module areas, title language, and the local import graph. Themes use stable `theme-001` style IDs. Individual cleanup candidates use `candidate-001` style IDs.\n\n`deepclean plan \u003ccandidate-or-theme-id\u003e` writes a focused cleanup plan under `.deepclean/plans/`. Use theme plans for larger cleanup areas and candidate plans for narrow local work.\n\nBroad themes are marked `too-broad` when they should not be handed to an agent as one task.\n\nPlans and handoffs are shaped as proof-backed PR slices, not smell lists. They call out the symptom, risk, evidence, minimal fix, tests to pin first, verification commands, expected no-op behavior, and non-goals so a future agent has a stop line instead of an invitation to over-refactor.\n\n## External Analyzer Evidence\n\nDeepclean can ingest SARIF and duplicate-detection output:\n\n```json\n{\n  \"enabledAdapters\": [\"file-metrics\", \"sarif-ingest\", \"jscpd\", \"code-graph\"],\n  \"externalAnalyzers\": {\n    \"semgrep\": {\n      \"enabled\": true,\n      \"command\": \"semgrep\",\n      \"config\": \"auto\",\n      \"timeoutMs\": 120000,\n      \"maxFindings\": 80\n    },\n    \"jscpd\": {\n      \"enabled\": true,\n      \"command\": \"jscpd\",\n      \"minTokens\": 80,\n      \"maxFindings\": 20\n    },\n    \"sarifPaths\": [\"semgrep.sarif\", \".semgrep/semgrep.sarif\"]\n  }\n}\n```\n\n## Release Checks\n\n```bash\nnpm run ci\nnpm run spec:validate\nnpm run release:check\n```\n\nThe release check builds the package, runs tests, validates OpenSpec locally when available, packs the tarball, and rejects private/local artifacts such as `.deepclean/`, `.codex/`, `node_modules/`, source files, and local reports.\n\nPublishing is handled by GitHub Actions trusted publishing. See [Release](docs/release.md).\n\n## Inspiration\n\nDeepclean's local artifact workflow was inspired by ClawPatch, but Deepclean is a separate maintainability reporting CLI.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffraction12%2Fdeepclean","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffraction12%2Fdeepclean","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffraction12%2Fdeepclean/lists"}