# Audit Install State

> Read-only audit of `~/.claude` and `~/.claude.json`: the deep inventory of unmanaged files. Use when: 'what is in my ~/.claude', 'why is my Claude Code install so big', 'does Claude Code clean up after itself', 'check cleanupPeriodDays', 'is this lock file dead', 'tidy my Claude Code install'. Deleting: /disk-hygiene:clean.

- Skill: `melodic-software/audit-install-state-2` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx get-skill add melodic-software/audit-install-state-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/melodic-software/audit-install-state-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: melodic-software (https://skillmd.com/u/melodic-software)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/melodic-software/audit-install-state-2

---


**Arguments.** `[--unattended] [root]`. `root` is the tree to audit and reaches the engine as `--root`; it defaults to `$CLAUDE_CONFIG_DIR`, else `~/.claude`. Always pass `--csv` to the engine. `--unattended`, anywhere in the arguments, is the caller declaring that nobody is present: the skill takes it out before reading `root`, never passes it to the engine script (whose parser does not accept it) and never reads it as a root path; under it the suggestion is recorded in the report instead of asked. The bare word `unattended` is neither this flag nor a root: stop and name `--unattended`.

## Purpose

Answers four questions about a Claude Code installation, and refuses to answer a fifth.

- **What is actually here?** Every entry labeled as an authored surface or a bulk tree, so a
  ~100k-file tree does not drown a ~150-file answer. Per-file rows live in the CSV.
- **What does the product already manage?** Recommending a manual prune of a path the retention
  sweep owns generates churn, not space.
- **For each number in a filename, what IS that number?** A liveness lookup against a TCP port or
  a shell `$$` returns a clean, confident, wrong "dead."
- **Is this tree in a deliberate or experimental state?** If it is, "looks like decay" is the wrong
  reading of almost everything.

The fifth question, *so what should I delete?*, is deliberately not answered. This skill is
report-only and never writes to the target tree. Deletion belongs to `/disk-hygiene:clean`, and
shedding project state belongs to `claude purge`.

## Scope boundary

| Question | Owner |
|---|---|
| Is this machine's Claude Code install directory healthy? | **this skill** |
| Are a repo's project-scope config FILES correct? | `/harness-config:audit` |
| Are permission grants portable and durable? | `/harness-config:audit-permission-grants` |
| Is the plugin fleet current, and at what scope? | `/harness-ops:plugins-audit` |
| Delete a genuinely unmanaged leftover | `/disk-hygiene:clean` |

Rationale and handoffs: [reference/scope-and-handoffs.md](reference/scope-and-handoffs.md).

## Boundary, the bundled `doctor` skill

One native Claude Code surface asks a question that sounds like this skill's, and the two are
routinely conflated:

- **`doctor` (bundled skill)**: health-checks an installation and **offers to fix** what it
  finds.
  - **Pointer**: when stating what `doctor` checks, its aliases, or what hides or removes it,
    fetch the `/doctor` row of
    [commands: all commands](https://code.claude.com/docs/en/commands#all-commands) and
    [skills: check your setup with /doctor](https://code.claude.com/docs/en/skills#check-your-setup-with-%2Fdoctor)
    live.
  - **As of**: 2026-11-10
  - **Recheck trigger**: either section drops `/doctor` or stops describing it as fixing what it
    finds, or a release note names bundled-skill gating or the `doctor` surface.
- **This skill (marketplace plugin)**, the deep read-only inventory of the install tree: every
  file classified, product-managed retention separated from genuinely unmanaged state, filename
  schemes resolved before any liveness check, and a deliberate-or-experimental state detected
  before anything is called stale.

**Routing.** Person-invoked `/doctor` is offered at session end (Phase 6); this section records surface facts only. Its sibling `/harness-ops:audit-performance` owns the timed slowness-capture lane against the same native surface.

**Mutation gate.** `doctor` mutates: fixing is its point. This skill's contract is report-only, so
never chain into a `doctor` fix on this skill's behalf. Surface the finding, and let the user
invoke the fix themselves.

**Availability is never assumed.** Bundled surfaces are gated on settings and environment, plan,
platform, and host surface, so a session where `doctor` does not resolve is an ordinary session,
not a broken one. Nothing here depends on it being present: the read-only inventory is complete on
its own.

## Never read

`.credentials.json`, `daemon/control.key`, `daemon/pipe.key`, `ide/*.lock`, and the values inside
`~/.claude.json`. These are inventory line-items: name, size, mtime, and nothing more. What the
product writes to disk unencrypted is read live from
[claude directory: plaintext storage](https://code.claude.com/docs/en/claude-directory#plaintext-storage)
(as of 2026-11-03; recheck when that section changes which files hold credentials or tokens). **Every subagent this skill dispatches inherits this rule; say so
explicitly in any prompt you fan out.** The engine enforces it in its reader, and its whole
content-read allowlist is `settings.json`, `.last-cleanup`, `plugins/.last_inuse_sweep`,
`plugins/installed_plugins.json` and the `plugins/cache/*/*/*/.orphaned_at` markers; each entry
it read by content carries `content_read: true` with the paths opened. Everything else is stat-only.

## Run it

```bash
python3 "${CLAUDE_PLUGIN_ROOT}/skills/audit-install-state/scripts/install_state.py" \
  --samples 3 --csv ./claude-install-listing.csv --versions-out ./claude-install-versions.json \
  > ./claude-install-report.json
```

Add `--root PATH` only when a `root` argument was given; without it the engine audits
`$CLAUDE_CONFIG_DIR`, else `~/.claude`.

Write both artifacts **outside** the target root (`${CLAUDE_PLUGIN_DATA}` resolves *inside* it and
would be counted by the run that wrote it; in a cloud session use the session scratchpad). If a
destination inside the root is unavoidable, pass it as `--csv` and the engine excludes it under
`self_excluded`. **Always pass `--csv`**: it is the only artifact carrying per-file rows, and
without it `csv.path` is `null` and the run must not be described as covering every file.
`--authored-threshold` only decides which entries the JSON *labels* `per-file` versus `rolled-up`.
`--versions-out <path>` writes the complete `unreferenced_versions` list (Phase 3) and is excluded
the same way. Other flags: `--root <path>` (else `$CLAUDE_CONFIG_DIR`, else `~/.claude`), `--samples N` (default
2; use 3+ on a busy machine). Python 3.11+ is the only requirement. The header records
`engine_version` and the exact `invocation`, so a report reproduces from itself.

## Phase 0. Whose tree is this?

Read `environment` first. `tree_verdict` is `remote`, `local`, or `indeterminate`, and it is a
label: no staleness verdict depends on it. A `remote` tree belongs to a cloud-session container,
not the operator's workstation, so open the report with that sentence; a three-minute-old container
reads as healthy and would otherwise be reported as someone's machine. The verdict rests on tree
signals, each with its own evidence tag; the process-level `CLAUDE_CODE_REMOTE` variable sits under
`session_context` and never decides the tree alone, because `--root` can point anywhere. Report
`indeterminate` as such, never as `remote`.

## Phase 1. Deliberate state, before any staleness reading

Then read `deliberate_state` and `deny_roots`. A non-empty `deliberate_state` means a revert
ledger (`RESTORE.md`, `PLAYBOOK.md`, `restore*.py`, or a `manifest.json` / baseline shallow under
`plugins/data/`) was found; its subtree reports `deny-listed` instead of a verdict. Treat it as the
possible **sole copy** of somebody's revert path: propose nothing for it, check `age_days`, and
**diff against the stored baseline rather than believing the ledger's own summary**.

## Phase 2. Retention, before any staleness claim

Read `retention`. Report `effective_days` with its `effective_evidence`: `measured` when a file
supplied it, `documented-default` when upstream's default applies. The highest-severity finding
lives here: if
`settings-unparsable-pauses-sweep` appears in `retention.findings`, lead with it and treat every
staleness reading below as suspect. If `managed-settings-unparsable-refuses-start` appears, report
a refused start naming the managed source; that is not a paused sweep. The pointer records for the
default, the pause causes and the managed-source refusal are in
[reference/surfaces.md](reference/surfaces.md#the-retention-sweep).

`.last-cleanup` is read by the engine and its timestamp is observed to advance when the sweep runs,
but no upstream page names the file, so `sentinels` carries it as `observed-undocumented` with an
unknown cadence. Report an advance as an observation, not a documented watermark; if it advanced
*during* your scan, say so, the tree was not quiesced.

## Phase 3. Entries and size

Each entry carries `surface`, a `reading` with its own `evidence`, and `file_count_sampled` as
`{min, max, n}`.

| Reading | What it means |
|---|---|
| `product-managed-healthy` | Every file is inside the retention window. Do not hand-prune |
| `age-exceeds-window` | `evidence: inferred`. Some mtimes exceed the window, a measurement, not proof the sweep is failing; the `why` names the sweep's documented unit |
| `keep` | Documented as retained, authored by you, session-scoped, or secret-bearing |
| `unclassified-report-only` | `evidence: no-upstream-row`. No documentation covers it either way |
| `deny-listed` | A revert ledger is in this subtree. Nothing here is a candidate |

`age-exceeds-window` is the reading most likely to be misread; several swept paths retain by a
unit other than the file. Per-path rules: [reference/surfaces.md](reference/surfaces.md). For "why
is my install so big", read `largest_subtrees` (top directories by measured bytes) and
`node_modules` (bytes the product installed into the cache's version directories, upstream basis in
its `why`; `node_modules` elsewhere under `plugins/` is measured apart and attributed to nobody).

`unreferenced_versions` lists each `plugins/cache/<marketplace>/<plugin>/<version>/` directory that
no `installPath` in `plugins/installed_plugins.json` references, largest first, with `bytes`, the
`.orphaned_at` marker's `orphaned_at` and `marker_age_days`, and `past_sweep_window` (true once
the marker is `ORPHAN_SWEEP_DAYS` old). A directory with no marker has `orphaned_at: null` and is
never past the window, so it has no removal date (sweep condition: pointer below). The report keeps only
the 25 largest, so the field stops growing with the version count (each row repeats its path, so
very long directory names still make rows large).
`unreferenced_versions_total` is the full count and `unreferenced_versions_truncated` is true when
the list was cut; never report the list length as the total. `--versions-out` writes the complete
list as a JSON file, and `unreferenced_versions_file` then records its `path` and `count`. When the
registry is missing, unparsable, or belongs to another root, the list is empty and
`unreferenced_versions_note` says why; an empty list then means "not checked", not "none". The list
is a report, not a deletion list, and removing anything stays with `/disk-hygiene:clean`. That
skill treats the cache as managed state and leaves version directories to the product's own sweep;
do not remove them by hand.

Hook, guard, and denial messages that name the previous version's path after an update are
expected, not a defect (running-session behavior: pointer below). Restart the session to pick up
the new version.

`ORPHAN_SWEEP_DAYS` in `lib/plugin_cache_versions.py` (and its byte-identical copy in
`disk-hygiene`) is our runtime copy of the window, used without a live fetch.

- **Pointer**: when stating the window, the marker name, or the running-session behavior, fetch
  [plugins loading: cleanup of previous versions](https://code.claude.com/docs/en/plugins/loading#cleanup-of-previous-versions)
  live.
- **As of**: 2026-11-10
- **Recheck trigger**: that section changes the window, the marker name, or the sweep condition,
  or a release note names plugin cache cleanup; then update `ORPHAN_SWEEP_DAYS` and its copy.

## Phase 4. Numeric names and liveness

`numeric_names` carries counts by `(meaning, liveness)`, every PID-typed group, and the unknown
sample grouped by name shape with a per-directory histogram. Everything that is not `pid` reads
`not_applicable` **by construction**, not because a lookup missed: `ide/<n>.lock` is a TCP port,
`rate-limit-guard/*.tmp.<n>` a shell `$$`, snapshot and backup numbers are epoch milliseconds, and
an unrecognized scheme fails closed as `unknown`. A `pid_typed` group marked `self_held` belongs to
the session running the audit: evidence about the auditor, not the tree; `self_pids_walk:
parent-only` means that ancestry could not be walked, so an `alive` group may still be this session.
`alive` measures *a* process with that id; "therefore in use" is an inference. A probe that could
not run reports `unverified`, **never** `dead`. Schemes: [reference/name-schemes.md](reference/name-schemes.md).

## Phase 5. Home-root state

`~/.claude.json` lives in the home directory. Report its size and mtime, never its values; route
its growth to `claude purge <path>`. What the command removes, how it confirms, and what the
retention sweep leaves alone are read live from
[claude directory: clear local data](https://code.claude.com/docs/en/claude-directory#clear-local-data)
and the purge pointer in [reference/surfaces.md](reference/surfaces.md#home-root-state-outside-the-swept-tree)
(as of 2026-11-03; recheck when that section renames the command or changes what it deletes).
`.claude.json.tmp.<n>.<hash>` siblings are failed atomic-write remnants whose number is unverified,
so the engine marks it `unknown` and attempts no lookup.

## Phase 6. Report

Reproduce every claim with the `evidence` tag the engine attached; an untagged paraphrase turns an
inference into an apparent observation. Ranges, never a central tendency, for anything
time-varying: `411–413 files, n=3`, never `~412`, and carry any `unanimous_small_n_on_volatile_path`
flag into the report. Check `csv.rows` against `totals.files` before claiming completeness, cite the
CSV path and row count, and state that the tree was live (`quiesced: false`). Fan-out cross-review
and the upstream-claim rule (raw markdown only; absence from a summary is not evidence of absence):
[reference/evidence-discipline.md](reference/evidence-discipline.md).

Before that cross-review, run
`bash "${CLAUDE_PLUGIN_ROOT}/lib/read-verification.sh" --plugin harness-ops --skill audit-install-state`
and copy its line into the report
([levels](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/verification-level/README.md)).
`standard` follows evidence-discipline.md section 5. `strict` dispatches the fresh-context reviewer
even for a single-agent run. Under `light`, and `off`, which acts as `light` here, dispatch none and
never review the findings yourself in its place: write `verification: skipped (<level>)` and say
the findings were not cross-reviewed.

### Person-invoked `/doctor` suggestion

Relay the sentence below to the user and do not run `/doctor` yourself: it is reserved for the person to run.

If /doctor is available in your session (gate basis: **Boundary, the bundled `doctor` skill** above), run it for the quick health-and-fix pass this read-only inventory does not perform.

**`--unattended`:** record this suggestion in the report's final section; do not ask.

## Next

/disk-hygiene:clean
Consumes a genuinely unmanaged leftover this report surfaced; the audit itself never deletes.

## Gotchas

- **A number in a filename is not a PID until proven otherwise.** The most expensive error in this
  problem space, and the reason the liveness gate is code rather than advice.
- **`enabledPlugins: false` does not mean disabled.** Enablement spans several scopes and is read at
  session start; `recent_writers` is behavioral evidence, `/harness-ops:plugins-audit` the verdict.
- **An empty directory may be deliberate**, and **a cloud-session tree is the common experimental
  state.** Phases 0 and 1 exist so neither is graded as decay.
- **A directory the retention sweep owns being absent is not decay.** Never grade its absence as a
  finding. Which directories the sweep removes, and whether it deletes the emptied directory, are
  read live from
  [claude directory: cleaned up automatically](https://code.claude.com/docs/en/claude-directory#cleaned-up-automatically)
  (as of 2026-11-03; recheck when that section changes its path list).
- **The "safe, no judgment required" tier most needs an independent check.** A case-insensitive
  comparer collapses deny rules that differ only by case; this skill's deny matching is
  case-sensitive and tested, and it encodes no dedupe or subsumption logic at all.

