# Claude Tune

> Audit and tune a Claude Code installation. Scans ~/.claude and ~/.claude.json for silently broken hooks, unused skills/plugins/MCP servers, stale memory files, orphan Claude/MCP processes, bloated telemetry, dead project entries, and contradictions in global or project CLAUDE.md. Produces a severity-ranked findings report with green/orange/red verdicts, then either auto-applies provably-safe clea…

- **Type:** Skill
- **Install:** `agentstack add skill-commodore65-claude-tune-claude-tune`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [commodore65](https://agentstack.voostack.com/s/commodore65)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [commodore65](https://github.com/commodore65)
- **Source:** https://github.com/commodore65/claude-tune

## Install

```sh
agentstack add skill-commodore65-claude-tune-claude-tune
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# claude-tune — Claude Code Setup Auditor

> Install: `git clone https://github.com/commodore65/claude-tune ~/.claude/skills/claude-tune`

A staff-level auditor for your Claude Code installation. Finds silently broken hooks, unused skills and plugins, bloated MCPs, stale memory, orphan processes, and cruft in `~/.claude/`. Produces a severity-ranked findings report, gates every mutation behind explicit approval, and emits a rollback cookbook for every change.

## HARD GATES

- Do NOT delete files without explicit per-item approval, EVER — even in Autopilot mode.
- Do NOT kill any process unless its parent is gone (PPID == 1), its age is > 5 minutes, its name matches a generic orphan pattern, AND the user confirms the specific PID.
- Do NOT mutate `~/.claude/settings.json`, `~/.claude.json`, or any `CLAUDE.md` without first calling `scripts/snapshot.sh` on the target and capturing the `SNAPSHOT:` + `ROLLBACK:` lines.
- Do NOT touch anything outside `$HOME/.claude`, `$HOME/.claude.json`, or project-scoped `.claude/` / `.mcp.json` / `CLAUDE.md` files under the user's current working directory.
- Do NOT SSH, do NOT hit networks, do NOT spawn MCP servers to query them. Local-only.
- Do NOT assume the user's tech stack (Python vs. Node vs. Rust, etc.).
- Generic only: no hardcoded user paths, hostnames, or project names in any script or reference.

## When to Use

Trigger phrases: "audit claude code", "tune claude code", "claude-tune", "/claude-tune", "broken hooks", "unused skills", "orphan claude processes", "clean up claude", "claude setup audit", or after a terminal crash left zombie Claude sessions behind.

NOT for:

- **Debugging project code** — use the `health` or `investigate` skill.
- **Creating new skills** — use `skill-creator`.
- **Auditing a specific running service** — that's for a service-monitor skill, not this one.

## Three Modes

### Mode A — Safe Autopilot

Runs all 12 phases in read-only mode, produces one combined findings report, then presents ONE approval prompt listing all proposed cleanups grouped into SAFE and DESTRUCTIVE buckets. User replies with approval grammar (ALL SAFE / ALL / specific numbers / NONE / EXPLAIN). Skill executes approved items and produces a delta report with rollback cookbook.

Safe items are applied after the single approval; destructive items require per-item confirmation even in Mode A. See `references/safety.md` § "Safe vs destructive ops".

### Mode B — Guided Interactive

Runs phases one at a time. After each phase, presents findings and asks: C (continue, no action), A (act on this phase now), S (skip remaining phases and jump to report), Q (quit without delta). Acting on a phase opens a mini-approval loop scoped to that phase's items.

### Mode C — Read-only

Runs all 12 phases and produces the full findings report. Zero mutations, zero approvals, zero risk. Useful as a dry-run before committing to Mode A or B.

### Mode selection dialog

**Mandatory first step on every invocation.** Never assume a mode.

```
claude-tune — which mode?
  A) Safe Autopilot   — one combined report, one approval, one cleanup pass
  B) Guided Interactive — 12 phase gates, maximum control
  C) Read-only        — audit only, no approvals, no cleanups
```

Wait for the user's response before doing anything else.

## Phase 0 — Baseline Snapshot

Before any audit work, run `bash scripts/baseline.sh`. It writes `baseline.json` into `~/.claude/backups/claude-tune//` and echoes a compact summary on stderr. The JSON is the "before" side of every delta reported later.

In Mode B, also report that Phase 0 ran successfully before moving to Phase 1.

## The 12 Audit Phases

Each phase below has: a one-line goal, the script or Read invocation, expected output shape, and a pointer to the full playbook. **Read the phase reference file for every phase before executing that phase.**

### Phase 1 — Live processes

Orphan Claude/MCP/codex processes, stale dev servers, heavy CPU hogs. Current claude session tree is automatically excluded.

- Run: `bash scripts/audit_processes.sh`
- Output: `{orphans: [...], heavy: [...], mine: [...]}`
- Severity: orphans 🔴, heavy 🟠 (informational), mine 🟢.
- Full playbook: `references/phase-01-processes.md`

### Phase 2 — Hooks

The highest-value phase. Detects silently-broken hooks that the harness "runs" but that exit early because they rely on removed env vars (`CLAUDE_FILE_PATH` and similar from Claude Code 1.x).

- Run: `bash scripts/audit_hooks.sh`
- Live firing test is OPT-IN. Default is static-only. If the user wants to confirm UNKNOWN hooks actually fire, ask first ("This may trigger side effects in your hooks — OK?") and re-run with `--live`.
- Severity: BROKEN 🔴, NOISY 🟠, UNKNOWN 🟠, OK 🟢.
- Full playbook: `references/phase-02-hooks.md`

### Phase 3 — Skills

Count usage of every installed skill across session logs. Reports HEAVY / ACTIVE / COLD / DEAD with observation-window caveat.

- Run: `python3 scripts/audit_skills.py`
- Severity: HEAVY/ACTIVE 🟢, COLD 🟠, DEAD 🔴.
- Full playbook: `references/phase-03-skills.md`

### Phase 4 — Plugins

Read `enabledPlugins` from settings.json, count plugin-tool and plugin-skill invocations, report disk footprint. Propose disable for unused enabled plugins; flag large disabled plugins for uninstall.

- Run: `python3 scripts/audit_plugins.py`
- Severity: HEAVY/ACTIVE 🟢, COLD 🟠, DEAD 🔴, DISABLED ⚪.
- Full playbook: `references/phase-04-plugins.md`

### Phase 5 — MCP servers

Find globally-scoped MCP servers that are used rarely. Propose moving them to an on-demand stash pattern so their tool descriptions stop consuming context in every session.

- Run: `python3 scripts/audit_mcp.py`
- Severity: HEAVY 🟢, ACTIVE 🟢 (🟠 if overweight), COLD 🟠, DEAD 🔴.
- Full playbook: `references/phase-05-mcp.md`

### Phase 6 — Global CLAUDE.md

LLM-driven heuristic read. Use the Read tool on `~/.claude/CLAUDE.md` and apply the rubric to surface narrow generalizations, duplicated guidance, and reference rot.

- Read: `~/.claude/CLAUDE.md`
- Full rubric: `references/phase-06-global-claudemd.md`

### Phase 7 — Project CLAUDE.md

Same LLM-driven approach for each alive project's CLAUDE.md (from Phase 11's alive list + current cwd). Plus project-specific smells: static lists inside dynamic-discovery blocks, duplicated sections, contradictions with reality.

- Read: each project's `CLAUDE.md`
- Full rubric: `references/phase-07-project-claudemd.md`

### Phase 8 — Memory files

Discover memory files under `~/.claude/projects/*/memory/` (or `~/.claude/memory/`). Flag stale dates in content, filename/content number mismatches, and dead path references.

- Run: `python3 scripts/audit_memory.py`
- Severity: FRESH 🟢, AGING 🟠, STALE 🟠, SUSPECT 🔴.
- Full playbook: `references/phase-08-memory.md`

### Phase 9 — Agents

Same usage-count pattern as skills, but for `~/.claude/agents/*.md`. Flags unused subagents.

- Run: `python3 scripts/audit_agents.py`
- Severity: HEAVY/ACTIVE 🟢, COLD 🟠, DEAD 🔴.
- Full playbook: `references/phase-09-agents.md`

### Phase 10 — Disk hygiene

Top 10 subdirs under `~/.claude/` by size. Telemetry failed-batch count (the only "safe auto-delete" class). Old claude-tune backup runs for pruning.

- Run: `bash scripts/audit_disk.sh`
- Severity: informational 🟠 for top dirs, 🟢 for failed telemetry (safe to delete).
- Full playbook: `references/phase-10-disk.md`

### Phase 11 — `~/.claude.json` projects section

Classify each entry as dead (path gone), home (Desktop/Downloads/$HOME), or alive. Propose bulk removal of dead entries.

- Run: `python3 scripts/audit_projects_json.py`
- Severity: DEAD 🔴, HOME 🟠, ALIVE 🟢.
- Full playbook: `references/phase-11-projects-json.md`

### Phase 12 — Settings sanity

Low-risk cruft: permissions allow-list entries the harness already auto-allows, env vars with stale paths, deprecated top-level keys.

- Run: `python3 scripts/audit_settings.py`
- Severity: 🟠 for each category, all informational until approval.
- Full playbook: `references/phase-12-settings.md`

## Safety Model (summary)

Every mutation goes through a 5-step pattern:

1. **Snapshot.** Call `bash scripts/snapshot.sh `. Capture the `SNAPSHOT:` and `ROLLBACK:` lines.
2. **Prove safety.** Classify the action as safe or destructive (see `references/safety.md`). Destructive actions always require per-item approval.
3. **Apply.** Run the mutation. In dry-run mode (`CLAUDE_TUNE_DRY_RUN=1`), echo instead.
4. **Verify.** For JSON mutations, re-parse the file and confirm it's valid. On parse failure, restore from snapshot and halt the phase.
5. **Record.** Append the ROLLBACK line to the rollback cookbook for the delta report.

Full details, approval grammar, and destructive-op classification: `references/safety.md`.

## Reporting Model (summary)

Three reports per run:

1. **Baseline** — after Phase 0. Inventory counts, top disk usage, snapshot dir path.
2. **Findings** — after all phases (Mode A/C) or after each phase (Mode B). Severity-tagged tables.
3. **Delta** — after any cleanups applied. Before/after counts, total bytes reclaimed, rollback cookbook, outstanding items.

Emoji legend (never add new symbols):

- 🟢 OK — no action
- 🟠 Attention — informational or proposed review
- 🔴 Broken / dead — proposed cleanup
- ⚪ Disabled / inactive — present but dormant

Exact markdown shells for every report type: `references/report-templates.md`.

## Rules

1. **Read-only first.** Produce the full findings report before any mutation.
2. **Snapshot before every write.** No exceptions.
3. **Mode selection is mandatory.** Never assume; always ask.
4. **Ambiguous → prompt.** The user is always the final gate on destructive actions.
5. **Generic only.** If a phase needs stack-specific or user-specific knowledge, skip it with a clear reason.
6. **No network, no SSH, no process spawning beyond shell scripts in this skill's own scripts/ dir.**
7. **Skipped phases are listed as SKIPPED, not FAILED.** A skipped phase must include the reason.
8. **Every mutation emits a rollback line.** Before executing.
9. **Numerical before/after in every delta.** No vague "cleaned up" statements.
10. **On script failure, phase is SKIPPED** with the error. Does not block other phases.
11. **If the user is running another Claude session** (detected in Phase 1 as another live `claude --dangerously` process), warn before any mutation to `settings.json` or `~/.claude.json` — those files are read at session start, and concurrent sessions may see inconsistent state.
12. **When in doubt, ask.** The approval gate is cheap; a wrong mutation is expensive.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [commodore65](https://github.com/commodore65)
- **Source:** [commodore65/claude-tune](https://github.com/commodore65/claude-tune)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-commodore65-claude-tune-claude-tune
- Seller: https://agentstack.voostack.com/s/commodore65
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.