Excavate technical debt. Restore with confidence.

Code 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) and Hermes Agent (cron-based background execution).

+---------------------------------------------------------------+
| CODE ARCHAEOLOGY CAPABILITY PANEL                             |
+-------------------+-------------------------------------------+
| Default mode       | survey: reports only, zero source edits   |
| Review mode        | excavate: reports plus mock patches       |
| Restore mode       | applies approved changes with test gates  |
| Local state        | .archaeology/ runtime artifacts           |
| Runtimes           | OpenCode plugin + Hermes Agent cron       |
| Platforms          | macOS/Linux (bash) + Windows (PowerShell) |
| Expedition order   | fixed stratigraphy from survey to catalog |
+-------------------+-------------------------------------------+

What It Does

Code 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.

• Catalogs dead code, unused exports, unreachable functions, and stale artifacts.
• Removes legacy fallbacks, deprecated shims, and compatibility layers after review.
• Maps circular dependencies before extraction or type consolidation work.
• Consolidates duplicate type definitions only after dead code and legacy layers are removed.
• Hardens weak types without guessing uncertain replacements.
• Finds semantic duplication and error-handling slop while preserving I/O boundaries.
• Produces .archaeology/ reports that stay local to the working repository.
• Supports both OpenCode interactive sessions and Hermes Agent cron-based phased execution.

Installation

OpenCode

Paste this handoff into your agent:

Run `npm pack [email protected]`, extract the tarball, then open `package/INSTALL.md` from that archive and follow its instructions.

Recommended plugin install in opencode.json:

{
  "plugin": [
    "[email protected]"
  ]
}

Global npm install path:

npm install -g [email protected] && opencode-code-archaeology install && opencode-code-archaeology doctor

One-time package runner path, if your OpenCode setup supports package execution through Bun:

bunx [email protected] install
bunx [email protected] doctor

Hermes Agent

npm install -g [email protected]
cd ~/projects/Code-Archaeology
bash hooks/hermes/setup.sh

hermes cronjob create \
  --name "code-archaeology-expedition" \
  --schedule "every 15m" \
  --workdir ~/projects/Code-Archaeology \
  --prompt "Run one Code Archaeology expedition phase. Read .archaeology/session.json, execute current phase with verification, advance to next phase."

See INSTALL.md for prerequisites, verification, updating, and troubleshooting.

Quick Start

OpenCode

Run the command family from inside the repository you want to inspect:

/code-archaeology
/code-archaeology --yolo

/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:

/code-archaeology-survey
/code-archaeology-excavate
/code-archaeology-restore

--yolo uses the full restore workflow in one shot (yolo mode), applying HIGH + MEDIUM confidence findings automatically.

Hermes Agent

Each cron run executes exactly one phase. The runner reads .archaeology/session.json, runs the current phase with verification, and advances to the next phase:

bash hooks/hermes/runner.sh

Ten phases complete in ~2.5 hours minimum (15-minute intervals).

Runtime Surfaces

| Feature | OpenCode | Hermes Agent | |---------|----------|--------------| | Entry | /code-archaeology slash command | cronjob | | Phases | All in one session | One per cron run | | Verification | Between expeditions | Between every phase | | Revert | Manual or automatic | Automatic on failure | | State | .archaeology/session.json | Same file | | Background | Plugin stays active | Cron resumes automatically | | Real-time | Yes | Delayed (15-min intervals) |

Expedition Flow

flowchart TD
  A[Start] --> B[Site Survey and Baseline]
  B --> C[Dead Code Excavation]
  C --> D[Legacy Stratum Removal]
  D --> E[Circular Dependency Cartography]
  E --> F[Type Catalog Consolidation]
  F --> G[Type Restoration and Hardening]
  G --> H[DRY Stratification]
  H --> I[Error Handling Stratigraphy]
  I --> J[Artifact Cleaning and Documentation]
  J --> K[Site Preservation and Final Catalog]

Safety Model

flowchart LR
  Survey[survey mode] --> Reports[write site reports]
  Reports --> Review[human review]
  Review --> Excavate[excavate mode: mock patches]
  Review --> Restore[restore mode: approved changes]
  Restore --> Verify[verify phase]
  Verify -->|pass| Next[next expedition]
  Verify -->|fail| Revert[revert phase and stop]

• survey is the default and writes reports only.
• 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.
• .archaeology/ is local runtime state and should not be committed.
• Work is isolated to a configurable branch, refactor/archaeology by default.
• Tests and type checks gate each restore phase.
• Failed restore phases are reverted before the next expedition can proceed.
• Try/catch blocks around I/O and external input boundaries are never removed automatically.

Commands

OpenCode

| Command | Purpose | File changes | | --- | --- | --- | | /code-archaeology | Run the full 10-phase survey chain without per-phase prompts. | None outside .archaeology/. | | /code-archaeology --yolo | Run the full 10-phase chain in unattended restore mode. | Yes, test-gated. | | /code-archaeology-survey | Generate site reports for review. | None outside .archaeology/. | | /code-archaeology-excavate | Generate reports and mock patches. | None outside .archaeology/patches/. | | /code-archaeology-restore | Apply approved high-confidence changes. | Yes, test-gated. |

Hermes Agent

| OpenCode Equivalent | Hermes Mechanism | File changes | | --- | --- | --- | | /code-archaeology | cronjob runs expedition loop | Depends on mode | | /code-archaeology-survey | mode = "survey" in session.json | None outside .archaeology/ | | /code-archaeology-excavate | mode = "excavate" in session.json | None outside .archaeology/patches/ | | /code-archaeology-restore | mode = "restore" in session.json | Yes, test-gated |

Parameters

| Parameter | Default | Description | Hermes Notes | | --- | --- | --- | --- | | repo_path | . | Target repository to excavate. | Set in session.json before first cron run. | | language | typescript | Primary language for tooling selection. | Same | | mode | survey | survey, excavate, restore, or yolo. | Change in session.json to switch modes. | | yolo | false | Force unattended restore + strict_mode behavior in one-shot mode. | Not implemented for Hermes by default. | | strict_mode | false | When true, restore may also apply medium-confidence findings. | Same | | 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 | | 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 | | branch_name | refactor/archaeology | Branch used for isolated restore work. | Same |

Expedition Order

The expedition order is fixed because each layer depends on the previous excavation:

1. Site Survey & Baseline
2. Dead Code Excavation
3. Legacy Stratum Removal
4. Circular Dependency Cartography
5. Type Catalog Consolidation
6. Type Restoration & Hardening
7. DRY Stratification
8. Error Handling Stratigraphy
9. Artifact Cleaning & Documentation
10. Site Preservation & Final Catalog

Do not consolidate types before dead code and legacy removal. Do not DRY code before dependency cycles are mapped.

Language Tooling

| Language | Dead Code | Dependencies | Types | DRY | | --- | --- | --- | --- | --- | | TypeScript | knip | madge | tsc | jscpd | | JavaScript | knip | madge | N/A | jscpd | | Python | vulture | pydeps | mypy | pylint | | Go | deadcode | godepgraph | go vet | golangci-lint | | Rust | cargo-udeps | cargo-deps | rustc | clippy |

If a preferred tool is missing, Code Archaeology falls back to AST-based manual analysis and flags uncertain findings for human review.

Architecture

Code-Archaeology/
|-- assets/             # README and repository visual assets
|-- commands/           # OpenCode slash command definitions
|-- dist/               # Built package output for GitHub-based installs
|-- docs/               # Public docs and release notes
|-- hooks/opencode/     # Init, verification, revert, and status hooks
|-- hooks/hermes/       # Setup and runner hooks for Hermes Agent
|-- plugins/            # Repo-local legacy plugin shim
|-- prompts/            # Expedition prompts by phase
|-- schema/             # JSON schemas for reports
|-- skills/             # Code Archaeology skill definitions
|   |-- code-archaeology/   # OpenCode skill
|   `-- hermes/             # Hermes Agent skill and integration docs
|-- src/                # TypeScript source
|-- INSTALL.md          # Multi-runtime install handoff
|-- README.md           # Public project overview
`-- AGENTS.md           # Agent runtime guide

Runtime Artifacts

All expedition state is written to .archaeology/ inside the target repository:

| Artifact | Purpose | | --- | --- | | session.json | Current expedition progress and configuration. | | site_survey.md | Baseline inventory and stratum graph. | | expedition1-report.md through expedition8-report.md | Per-expedition findings. | | FINAL_CATALOG.md | Final excavation summary and recommendations. | | excavation_log.txt | git diff --stat for applied restoration work. | | patches/ | Mock patches generated by excavate mode. | | hermes-runtime.json | Hermes runtime configuration (Hermes only). |

Local Testing

For plugin development:

npm install
npm run build
npm run typecheck
npm pack --json --dry-run
bash -n hooks/opencode/*.sh
bash -n hooks/hermes/*.sh

For a restore expedition, run the configured test and type-check commands between phases. The bundled verification hooks are:

# OpenCode
bash hooks/opencode/verify-phase.sh final_verify

# Hermes
bash hooks/hermes/runner.sh

Release Docs

• docs/README.md is the documentation landing page.
• docs/RELEASE.md covers release preparation and publishing.
• INSTALL.md is the raw handoff for multi-runtime installation.
• GitHub Releases lists published versions.

License

MIT. See LICENSE.