![\"Code](\"assets/code-archaeology-banner.svg\")
\n\n \n
\n ![\"GitHub](\"https://img.shields.io/github/stars/Maleick/Code-Archaeology?style=flat-square\")
![\"Last](\"https://img.shields.io/github/last-commit/Maleick/Code-Archaeology?style=flat-square\")
![\"GitHub](\"https://img.shields.io/github/v/release/Maleick/Code-Archaeology?style=flat-square\")
![\"npm](\"https://img.shields.io/npm/v/opencode-code-archaeology?style=flat-square\")
![\"License\"](\"https://img.shields.io/github/license/Maleick/Code-Archaeology?style=flat-square\")
![\"Docs\"](\"https://img.shields.io/badge/docs-open-blue?style=flat-square\"){kind=icon}
![\"Sponsor\"](\"https://img.shields.io/badge/sponsor-Maleick-fafbfc?style=flat-square&logo=github-sponsors\"){kind=icon}
\n Install |\n Docs |\n Wiki |\n Commands |\n Safety |\n Release\n
\n\nExcavate technical debt. Restore with confidence.\n\nCode Archaeology is a multi-runtime plugin that surveys, catalogs, and safely restores codebases by removing accumulated technical sediment in a fixed, test-gated expedition order. It runs on **OpenCode** (interactive slash commands), **Codex** (native skill), and **Hermes Agent** (cron-based background execution).\n\n```text\n+---------------------------------------------------------------+\n| CODE ARCHAEOLOGY CAPABILITY PANEL |\n+-------------------+-------------------------------------------+\n| Default mode | survey: reports only, zero source edits |\n| Review mode | excavate: reports plus mock patches |\n| Restore mode | applies approved changes with test gates |\n| Local state | .archaeology/ runtime artifacts |\n| Runtimes | OpenCode plugin + Codex skill + Hermes cron |\n| Platforms | macOS/Linux (bash) + Windows (PowerShell) |\n| Expedition order | fixed stratigraphy from survey to catalog |\n+-------------------+-------------------------------------------+\n```\n\n## What It Does\n\nCode Archaeology runs a systematic excavation of a repository before it changes code. It inventories the site, identifies technical debt strata, writes reviewable reports, and only applies approved changes in `restore` mode.\n\n- Catalogs dead code, unused exports, unreachable functions, and stale artifacts.\n- Removes legacy fallbacks, deprecated shims, and compatibility layers after review.\n- Maps circular dependencies before extraction or type consolidation work.\n- Consolidates duplicate type definitions only after dead code and legacy layers are removed.\n- Hardens weak types without guessing uncertain replacements.\n- Finds semantic duplication and error-handling slop while preserving I/O boundaries.\n- Produces `.archaeology/` reports that stay local to the working repository.\n- Supports **OpenCode** interactive sessions, **Codex** skill sessions, and **Hermes Agent** cron-based phased execution.\n\n## Installation\n\n### Claude Code\n\nCopy the commands and skill into your project's `.claude/` directory:\n\n```bash\n# From the Code-Archaeology repo root\ncp commands/code-archaeology*.md /path/to/your-project/.claude/commands/\nmkdir -p /path/to/your-project/.claude/plugins/code-archaeology/skills/code-archaeology\ncp skills/claude-code/SKILL.md \\\n /path/to/your-project/.claude/plugins/code-archaeology/skills/code-archaeology/SKILL.md\n```\n\nRestart Claude Code, then run `/code-archaeology` from inside your target repository.\n\nSee [`skills/claude-code/INTEGRATION.md`](skills/claude-code/INTEGRATION.md) for global install, session flow, and troubleshooting.\n\n### OpenCode\n\nPaste this handoff into your agent:\n\n```text\nRun `npm pack opencode-code-archaeology@2.8.1`, extract the tarball, then open `package/INSTALL.md` from that archive and follow its instructions.\n```\n\nRecommended plugin install in `opencode.json`:\n\n```json\n{\n \"plugin\": [\n \"opencode-code-archaeology@2.8.1\"\n ]\n}\n```\n\nGlobal npm install path:\n\n```bash\nnpm install -g opencode-code-archaeology@2.8.1 && opencode-code-archaeology install && opencode-code-archaeology doctor\n```\n\nOne-time package runner path, if your OpenCode setup supports package execution through Bun:\n\n```bash\nbunx opencode-code-archaeology@2.8.1 install\nbunx opencode-code-archaeology@2.8.1 doctor\n```\n\n### Hermes Agent\n\n```bash\nnpm install -g opencode-code-archaeology@2.8.1\ncd ~/projects/Code-Archaeology\nbash hooks/hermes/setup.sh\nopencode-code-archaeology doctor --native # optional C/C++/Ethernal audit readiness\n\nhermes cronjob create \\\n --name \"code-archaeology-expedition\" \\\n --schedule \"every 15m\" \\\n --workdir ~/projects/Code-Archaeology \\\n --prompt \"Run one Code Archaeology expedition phase. Read .archaeology/session.json, execute current phase with verification, advance to next phase.\"\n```\n\nSee [`INSTALL.md`](INSTALL.md) for prerequisites, verification, updating, and troubleshooting.\n\n### Codex\n\nInstall the Codex skill into `$CODEX_HOME/skills`:\n\n```bash\nnpm install -g opencode-code-archaeology@2.8.1\nopencode-code-archaeology install-codex\n```\n\nRestart Codex or start a new Codex session, then ask Codex to use `code-archaeology` in the target repository. The Codex skill follows the same report-first expedition order and writes local `.archaeology/` artifacts.\n\n## Quick Start\n\n### Claude Code\n\nRun the command family from inside the repository you want to inspect:\n\n```text\n/code-archaeology\n/code-archaeology --yolo\n```\n\n### OpenCode\n\nRun the command family from inside the repository you want to inspect:\n\n```text\n/code-archaeology\n/code-archaeology --yolo\n```\n\n`/code-archaeology` runs the full 10-phase survey chain without per-phase prompts. It writes reports under `.archaeology/` and makes no source-code changes. Review the reports, then choose whether to generate mock patches or apply approved changes:\n\n```text\n/code-archaeology-survey\n/code-archaeology-excavate\n/code-archaeology-restore\n```\n\n`--yolo` uses the full restore workflow in one shot (`yolo` mode), applying `HIGH` + `MEDIUM` confidence findings automatically.\n\n### Codex\n\nAsk Codex to use the `code-archaeology` skill from inside the repository you want to inspect:\n\n```text\nUse code-archaeology in survey mode.\nUse code-archaeology in excavate mode.\nUse code-archaeology in restore mode after reviewing the reports.\n```\n\n### Hermes Agent\n\nEach cron run executes exactly **one** phase. The runner reads `.archaeology/session.json`, runs the current phase with verification, and advances to the next phase:\n\n```bash\nbash hooks/hermes/runner.sh\n```\n\nTen phases complete in ~2.5 hours minimum (15-minute intervals).\n\n## Runtime Surfaces\n\n| Feature | OpenCode | Codex | Hermes Agent |\n|---------|----------|-------|--------------|\n| Entry | `/code-archaeology` slash command | `code-archaeology` skill | `cronjob` |\n| Phases | All in one session | All in one session | One per cron run |\n| Verification | Between expeditions | Before/after editing phases | Between every phase |\n| Revert | Manual or automatic | Manual or automatic per Codex workflow | Automatic on failure |\n| State | `.archaeology/session.json` | Same file | Same file |\n| Background | Plugin stays active | Interactive session | Cron resumes automatically |\n| Real-time | Yes | Yes | Delayed (15-min intervals) |\n\n## Expedition Flow\n\n```mermaid\nflowchart TD\n A[Start] --> B[Site Survey and Baseline]\n B --> C[Dead Code Excavation]\n C --> D[Legacy Stratum Removal]\n D --> E[Circular Dependency Cartography]\n E --> F[Type Catalog Consolidation]\n F --> G[Type Restoration and Hardening]\n G --> H[DRY Stratification]\n H --> I[Error Handling Stratigraphy]\n I --> J[Artifact Cleaning and Documentation]\n J --> K[Site Preservation and Final Catalog]\n```\n\n## Safety Model\n\n```mermaid\nflowchart LR\n Survey[survey mode] --> Reports[write site reports]\n Reports --> Review[human review]\n Review --> Excavate[excavate mode: mock patches]\n Review --> Restore[restore mode: approved changes]\n Restore --> Verify[verify phase]\n Verify -->|pass| Next[next expedition]\n Verify -->|fail| Revert[revert phase and stop]\n```\n\n- `survey` is the default and writes reports only.\n- `restore` and `yolo` modify code and should run only after reports are reviewed; `yolo` applies `MEDIUM` confidence fixes with no review handoff in one pass.\n- `.archaeology/` is local runtime state and should not be committed.\n- Work is isolated to a configurable branch, `refactor/archaeology` by default.\n- Tests and type checks gate each restore phase.\n- Failed restore phases are reverted before the next expedition can proceed.\n- Try/catch blocks around I/O and external input boundaries are never removed automatically.\n\n## Commands\n\n### Claude Code and OpenCode\n\n| Command | Purpose | File changes |\n| --- | --- | --- |\n| `/code-archaeology` | Run the full 10-phase survey chain without per-phase prompts. | None outside `.archaeology/`. |\n| `/code-archaeology --yolo` | Run the full 10-phase chain in unattended restore mode. | Yes, test-gated. |\n| `/code-archaeology-survey` | Generate site reports for review. | None outside `.archaeology/`. |\n| `/code-archaeology-excavate` | Generate reports and mock patches. | None outside `.archaeology/patches/`. |\n| `/code-archaeology-restore` | Apply approved high-confidence changes. | Yes, test-gated. |\n\n### Codex\n\n| Intent | Codex request | File changes |\n| --- | --- | --- |\n| Survey | `Use code-archaeology in survey mode` | None outside `.archaeology/` |\n| Excavate | `Use code-archaeology in excavate mode` | None outside `.archaeology/patches/` |\n| Restore | `Use code-archaeology in restore mode` | Yes, test-gated |\n| YOLO | `Use code-archaeology in yolo mode` | Yes, strict and test-gated |\n\n### Hermes Agent\n\n| OpenCode Equivalent | Hermes Mechanism | File changes |\n| --- | --- | --- |\n| `/code-archaeology` | `cronjob` runs expedition loop | Depends on mode |\n| `/code-archaeology-survey` | `mode = \"survey\"` in `session.json` | None outside `.archaeology/` |\n| `/code-archaeology-excavate` | `mode = \"excavate\"` in `session.json` | None outside `.archaeology/patches/` |\n| `/code-archaeology-restore` | `mode = \"restore\"` in `session.json` | Yes, test-gated |\n\n## Parameters\n\n| Parameter | Default | Description | Hermes Notes |\n| --- | --- | --- | --- |\n| `repo_path` | `.` | Target repository to excavate. | Set in `session.json` before first cron run. |\n| `language` | `typescript` | Primary language for tooling selection. | Same |\n| `mode` | `survey` | `survey`, `excavate`, `restore`, or `yolo`. | Change in `session.json` to switch modes. |\n| `yolo` | `false` | Force unattended `restore` + `strict_mode` behavior in one-shot mode. | Not implemented for Hermes by default. |\n| `strict_mode` | `false` | When true, restore may also apply medium-confidence findings. | Same |\n| `test_command` | `npm test` | Recorded session default only; verification hooks do not execute repository-local command values. Use `CODE_ARCHAEOLOGY_TEST_COMMAND` to approve an override for the current process. | Same |\n| `typecheck_command` | `npx tsc --noEmit` | Recorded session default only; verification hooks do not execute repository-local command values. Use `CODE_ARCHAEOLOGY_TYPECHECK_COMMAND` to approve an override for the current process. | Same |\n| `branch_name` | `refactor/archaeology` | Branch used for isolated restore work. | Same |\n\n## Expedition Order\n\nThe expedition order is fixed because each layer depends on the previous excavation:\n\n1. Site Survey & Baseline\n2. Dead Code Excavation\n3. Legacy Stratum Removal\n4. Circular Dependency Cartography\n5. Type Catalog Consolidation\n6. Type Restoration & Hardening\n7. DRY Stratification\n8. Error Handling Stratigraphy\n9. Artifact Cleaning & Documentation\n10. Site Preservation & Final Catalog\n\nDo not consolidate types before dead code and legacy removal. Do not DRY code before dependency cycles are mapped.\n\n## Language Tooling\n\n| Language | Dead Code | Dependencies | Types | DRY |\n| --- | --- | --- | --- | --- |\n| TypeScript | `knip` | `madge` | `tsc` | `jscpd` |\n| JavaScript | `knip` | `madge` | N/A | `jscpd` |\n| Python | `vulture` | `pydeps` | `mypy` | `pylint` |\n| Go | `deadcode` | `godepgraph` | `go vet` | `golangci-lint` |\n| Rust | `cargo-udeps` | `cargo-deps` | `rustc` | `clippy` |\n\nIf a preferred tool is missing, Code Archaeology falls back to AST-based manual analysis and flags uncertain findings for human review.\n\n## Architecture\n\n```text\nCode-Archaeology/\n|-- assets/ # README and repository visual assets\n|-- commands/ # Slash command definitions (Claude Code + OpenCode)\n|-- dist/ # Built package output for GitHub-based installs\n|-- docs/ # Public docs and release notes\n|-- hooks/opencode/ # Init, verification, revert, and status hooks\n|-- hooks/hermes/ # Setup and runner hooks for Hermes Agent\n|-- plugins/ # Repo-local legacy plugin shim\n|-- prompts/ # Expedition prompts by phase\n|-- schema/ # JSON schemas for reports\n|-- skills/ # Code Archaeology skill definitions\n| |-- code-archaeology/ # OpenCode skill\n| |-- codex/ # Codex skill\n| `-- hermes/ # Hermes Agent skill and integration docs\n|-- src/ # TypeScript source\n|-- INSTALL.md # Multi-runtime install handoff\n|-- README.md # Public project overview\n`-- AGENTS.md # Agent runtime guide\n```\n\n## Runtime Artifacts\n\nAll expedition state is written to `.archaeology/` inside the target repository:\n\n| Artifact | Purpose |\n| --- | --- |\n| `session.json` | Current expedition progress and configuration. |\n| `site_survey.md` | Baseline inventory and stratum graph. |\n| `expedition1-report.md` through `expedition8-report.md` | Per-expedition findings. |\n| `FINAL_CATALOG.md` | Final excavation summary and recommendations. |\n| `excavation_log.txt` | `git diff --stat` for applied restoration work. |\n| `patches/` | Mock patches generated by `excavate` mode. |\n| `hermes-runtime.json` | Hermes runtime configuration (Hermes only). |\n\n## Local Testing\n\nFor plugin development:\n\n```bash\nnpm install\nnpm run build\nnpm test\nnpm run typecheck\nnpm pack --json --dry-run\nbash -n hooks/opencode/*.sh\nbash -n hooks/hermes/*.sh\n```\n\nFor a restore expedition, run the configured test and type-check commands between phases. The bundled verification hooks are:\n\n```bash\n# OpenCode\nbash hooks/opencode/verify-phase.sh final_verify\n\n# Hermes\nbash hooks/hermes/runner.sh\n```\n\n## License\n\nMIT. See [`LICENSE`](LICENSE).\n","readmeFilename":"README.md"}