metamorph

Version 1.2.7

metamorph is a plugin for Claude Code, Cursor, and Codex that studies how you actually use your agents, skills, and CLAUDE.md files. It builds a text dashboard, scores each target, and proposes small file edits as diffs (proposed changes). Nothing is written to disk until you approve it.

Suggest-only by design: metamorph never auto-applies edits. You review every diff first.

Runtime-only repo: main contains the files users install and run. Source, tests, source maps, and build-only files are intentionally not shipped in this branch.

Quick reference

Goal	Command
Install (Claude Code)	`/plugin marketplace add K3vin-h/metamorph` then `/plugin install metamorph`
Install (Cursor)	Clone to `~/.cursor/plugins/local/metamorph/` and reload
Install (Codex)	`codex plugin marketplace add K3vin-h/metamorph` then enable in plugin directory
First-time setup	`/metamorph-setup`
View dashboard	`/metamorph-report`
Improve agents or skills	`/metamorph`
Check status	`/metamorph --status`
Undo an approved change	`/metamorph-rollback --list`

Key terms

Term	Meaning
Agent	A specialized assistant definition Claude can invoke (e.g. `architect`, `code-reviewer`)
Skill	An instruction file Claude loads for specific tasks (e.g. `tdd-workflow`)
CLAUDE.md	Project-level instructions that guide Claude's behavior
Session	One work period in Claude Code, from open to close
Hook	An automatic script that runs at session start or end — no AI involved
Token	A unit of AI usage; only the improvement step consumes tokens
Diff	A line-by-line list of what would change in a file
Flag	A short label on the dashboard (`inactive`, `underused`, `healthy`, etc.) explaining a finding
Score	A number from 0–100; lower usually means more room to improve
Warm-up	Initial sessions where metamorph collects data before marking the dashboard `ready` (default: 5)

What metamorph does

Observes your Claude Code sessions through background hooks (local parsing only — no AI).
Scores each agent and skill based on real usage patterns.
Publishes a text report (report.md) with scores, flags, and warm-up status.
Proposes targeted diffs when you run /metamorph.
Validates, backs up, and writes only after you explicitly approve.

metamorph does not run continuously in the background, serve an HTML dashboard, or modify files without consent.

How it works

Layer 1 — Background pipeline (zero tokens)

Hooks are small Node.js scripts registered in hooks/hooks.json. They fire automatically:

Hook	When	What it does
SessionStart	Session opens	Refreshes `report.md`; prints warm-up status and top flags
SessionEnd	Session closes	Parses new transcript data; updates scores when new sessions are found; refreshes the report and style profile only if new data was ingested

Hook timeouts: SessionStart 10s, SessionEnd 60s. Errors go to data/hook-errors.log and do not prevent Claude Code from closing normally.

Layer 2 — Improvement pipeline (uses tokens)

When you run /metamorph:

CLI helpers print stats and target tables without loading the full analysis file into chat.
You select targets (top 3, specific IDs, or all — capped at maxSuggestionsPerRun, default 3).
prepare-improve-batch builds a small context file (~1–3 KB) per target.
metamorph-diff subagents run in parallel (Haiku model) — each reads one context file and writes a unified diff.
You review diffs and approve with all, specific IDs, or none (or later via /metamorph-improve).
Approved changes are validated, backed up, and written atomically.

This is the only step that uses the AI model and consumes tokens.

Requirements

Requirement	Details
Claude Code	Plugin and hook support enabled
Node.js 18+	Runs metamorph's background scripts

Installation

Claude Code

/plugin marketplace add K3vin-h/metamorph
/plugin install metamorph

To update:

/plugin marketplace update
/plugin update metamorph

Your settings and data in ${CLAUDE_PLUGIN_DATA} are preserved. After updating, start a new session or run /metamorph-report to refresh the dashboard format.

Cursor

Install from GitHub (clone or download), then load locally:

git clone https://github.com/K3vin-h/metamorph.git ~/.cursor/plugins/local/metamorph

Restart Cursor (or Developer: Reload Window). Commands (/metamorph, /metamorph-setup, …), hooks, and skills load from .cursor-plugin/plugin.json.

From Claude Code, /metamorph-setup can also link the plugin into ~/.cursor/plugins/local/metamorph/ automatically.

Codex

Add the GitHub marketplace, then install from the plugin directory:

codex plugin marketplace add K3vin-h/metamorph

Codex reads .claude-plugin/marketplace.json (legacy-compatible) and requires .codex-plugin/plugin.json at the plugin root.

For a local checkout during development:

codex plugin marketplace add /absolute/path/to/metamorph

Or run /metamorph-setup from Claude Code to link the plugin into ~/.agents/plugins/metamorph/ and register a personal marketplace entry.

Restart Codex and enable metamorph from the plugin picker. Use /metamorph to run improvements; SessionStart/SessionEnd hooks run automatically.

First-time setup

/metamorph-setup

The wizard configures:

Setting	What it controls
Read scope	Which Claude config folders to analyze: global, project, or both
Transcript privacy	How much session data to store: `full`, `redacted`, or `off`
Write targets	Whether metamorph may suggest edits to agents, skills, and/or CLAUDE.md
Warm-up sessions	Sessions to collect before the dashboard shows `ready` (default: 5)
Flag threshold	Scores below this value receive the `underused` flag (default: 40)
Deny-read globs	File path patterns metamorph must never read (e.g. `*/.env*`)

Shipped defaults (config.jsonc):

Transcripts: redacted (metadata only — not full chat text)
Agent and skill suggestions: enabled
CLAUDE.md suggestions: disabled
Read scope: both

Settings save to ${CLAUDE_PLUGIN_DATA}/config.jsonc. Run setup again anytime; use --reset to restore defaults first.

Typical workflow

Install the plugin and run /metamorph-setup.
Use Claude Code normally for several sessions (at least 5 by default).
Run /metamorph-report to view the dashboard.
Run /metamorph, select targets, review diffs, and approve what you want.

During warm-up	After warm-up
Dashboard shows `warm-up 2/5` (example)	Dashboard shows `ready`
Session start reports sessions remaining	Session start suggests `/metamorph`
`/metamorph` works if session data exists	Scores are generally more reliable

Warm-up improves data quality; it is not a hard lock on commands.

Efficient usage (token savings)

Practice	Effect
`/metamorph-report`	Zero LLM — dashboard only; prints a clickable `report.md` link
`/metamorph --target <id>`	Skip stats tables + multi-target prep when you know the target
Actionable targets only	Default interactive flow uses `improve-targets-actionable` (excludes inactive targets)
`improve.skipNeverInvoked: true`	Batch prepare skips inactive agents/skills (default in 1.2.7)
`transcripts: redacted`	Smaller cache — default; use `full` only if you need mistake text
Prune unused agents/skills	Biggest routing win — remove from `~/.claude/agents/` or `~/.cursor/skills-cursor/`

Config migration (if your runtime config still has transcripts: full):

node "${CLAUDE_PLUGIN_ROOT}/dist/index.js" config-set read.transcripts redacted

After upgrading to 1.2.7, run one session-end to re-parse transcripts with improved Cursor Task / Read skill tracking:

node "${CLAUDE_PLUGIN_ROOT}/dist/index.js" session-end

Recommended improve targets (when you have usage data): agents/skills with score ≥ 30 and non-inactive flags — e.g. code-reviewer, security-reviewer, graphify. Skip architect-class agents until you actually invoke them.

Commands

Core

Command	Description
`/metamorph`	Interactive: actionable targets → diffs → approval
`/metamorph --status`	Warm-up progress, recommended target IDs, top flags
`/metamorph --target <id>`	Improve a single target directly (preferred for token savings)
`/metamorph-report`	Refresh and display `report.md` (zero LLM)

Target IDs: agent/skill names (architect, backend-patterns), or global / local for CLAUDE.md.

Selection in /metamorph: top N, all, or space-separated IDs. Lowest-scoring targets are kept when the selection exceeds maxSuggestionsPerRun.

Configuration

Command	Description
`/metamorph-setup`	Setup wizard
`/metamorph-setup --reset`	Reset defaults, then wizard
`/metamorph-config show`	Display current settings
`/metamorph-config set key=value`	Update one setting (dot notation for nested keys)

Examples:

/metamorph-config set warmupSessions=3
/metamorph-config set flagThreshold=50
/metamorph-config set read.transcripts=full
/metamorph-config set read.mistakeTracking=false
/metamorph-config set write.targets.claudeMd=both

Approval and rollback

Command	Description
`/metamorph-improve --list`	List pending suggestions by run ID
`/metamorph-improve --approve <runId>-<targetId>`	Apply one approved diff
`/metamorph-improve --approve all`	Apply all pending from the latest run
`/metamorph-improve --reject <id>`	Discard a suggestion
`/metamorph-improve --reject all`	Discard all pending suggestions
`/metamorph-rollback --list`	List restorable backups
`/metamorph-rollback --file <path>`	Restore a file to its pre-edit backup
`/metamorph-rollback --run <runId>`	Restore all restorable files from one run

Suggestion ID example: run-1717000000000-abc123def456-architect

Feedback

/metamorph-feedback "prefer shorter agent descriptions"
/metamorph-feedback --list
/metamorph-feedback --clear

Up to 500 characters per entry via the slash command. Feedback is sanitized and marked as untrusted before it influences suggestions.

Dashboard and scoring

Reading the report

Run /metamorph-report or open ${CLAUDE_PLUGIN_DATA}/report.md.

# metamorph · ready
124 sessions · 44 tools · 0 agent runs · 0 skill loads · redacted
ts 42% · py 28%

_Score: 0–30 needs attention · 31–70 moderate · 71–100 healthy_
_Flags: inactive=unused · underused=low score · healthy=active · tool-gap=declared tool unused · stale-doc=inactive section · correction=repeated fixes_

## Agents (25)

┌──────────────────────────────┬──────────────┬──────────────┐
│              id              │    score     │     flag     │
├──────────────────────────────┼──────────────┼──────────────┤
│  architect                   │    10/100    │  inactive   │
│  researcher                  │    40/100    │  underused  │
└──────────────────────────────┴──────────────┴──────────────┘

There is no HTML dashboard — only this plain-text report with ASCII tables.

Score composition

Each agent or skill receives a weighted score from 0 to 100:

Factor	Weight	What it measures
Invocation frequency	40%	How often you use it vs total agent runs or skill loads
Tool utilization	30%	Declared tools vs tools actually observed in sessions
Section coverage	20%	Whether documented sections align with your workflow
Skill apply rate	10%	Skills only: times loaded vs times actually applied

Flags

Flag	Meaning
`—`	No primary issue
`inactive`	No observed use, or a skill loaded but was never applied
`underused`	Used at least once, but score is below `flagThreshold` (default: below 40)
`healthy`	Score is 80 or higher and the target appears active
`tool-gap`	A declared tool was not seen in your sessions
`stale-doc`	A documentation section may not match your workflow (high confidence in `full` privacy mode)
`stale-doc?`	Same as `stale-doc`, but lower confidence (`redacted` or `off` mode)
`correction`	Repeated correction patterns detected

Note: stale-doc and stale-doc? flags appear only after at least 5 invocations, to limit false positives.

Privacy

Mode	What is stored
`redacted` (default)	Metadata only: tool names, file extensions, hashed path fragments, timestamps — not full prompts or file contents
`full`	Complete transcript bodies and tool inputs
`off`	Aggregate counts with minimal per-event detail

metamorph applies best-effort secret scrubbing before storage. Use deny-read globs for sensitive files. Scrubbing is not a guarantee.

Session data included in improvement context is wrapped in [UNTRUSTED DATA] blocks. Subagents are instructed to treat that content as reference data, not as commands to follow.

Mistake tracking

Enabled by default (read.mistakeTracking: true). Helps metamorph suggest guardrails when you repeatedly correct similar issues.

Counts	Does not count
Tool completes successfully, then you send a fix message	Declined tool calls
You reject a suggestion with `/metamorph-improve --reject`	Failed commands
	Fix messages with no successful tool step immediately before

Disable: /metamorph-config set read.mistakeTracking=false

Only a compact slice (max 3 patterns, 2 examples, 80 characters each) is passed to the improvement step to limit token use.

What happens when you approve

The diff is applied to a temporary copy of the target file.
The copy is validated (required frontmatter keys, balanced code fences).
If validation passes: the original file is backed up, then replaced.
If validation fails: the original file is unchanged.

Rollback: one backup per file (the version from immediately before metamorph's last edit). If filenames collide, use the full path (e.g. agents/architect.md).

Configuration reference

Setting	Values	Default
`mode`	`suggest` only	Cannot auto-apply
`warmupSessions`	1–50	5
`flagThreshold`	0–100	40
`maxSuggestionsPerRun`	1–20	3
`read.scope`	`global`, `project`, `both`	`both`
`read.transcripts`	`full`, `redacted`, `off`	`redacted`
`read.mistakeTracking`	`true`, `false`	`true`
`read.trackCursor`	`true`, `false`	`true`
`read.trackCodex`	`true`, `false`	`true`
`improve.skipNeverInvoked`	`true`, `false`	`true`
`improve.minScore`	0–100	30
`improve.minInvocations`	0–100	1
`write.targets.agents`	`true`, `false`	`true`
`write.targets.skills`	`true`, `false`	`true`
`write.targets.claudeMd`	`false`, `global`, `local`, `both`	`false`
`write.allow`	path globs	`agents/`, `skills//SKILL.md`
`write.deny`	path globs	`[]`

Changes take effect on the next hook run. The config file supports comments (JSONC format).

Data storage

Plugin data lives under ${CLAUDE_PLUGIN_DATA}, typically:

~/.claude/plugins/data/metamorph-metamorph/

Path	Purpose
`config.jsonc`	Settings
`report.md`	Text dashboard
`data/analysis.json`	Scores and flags
`data/profile.json`	Session cache (up to 500 sessions)
`data/feedback.log`	User feedback entries
`data/hook-errors.log`	Hook error log
`data/style-profile.json`	Style patterns for suggested edits
`data/mistake-feedback.jsonl`	Mistake and rejection events
`suggestions/`	Pending diffs awaiting approval
`backups/`	Pre-edit file copies

Reads from: ~/.claude/agents/, ~/.claude/skills/, ~/.claude/projects/ (transcripts).

Writes to: agent, skill, and CLAUDE.md paths only after approval, and only where settings permit.

Security

Suggest-only — no autonomous file writes.
Path confinement — writes restricted to allowed directories; symlink escapes blocked.
Input sanitization — feedback and mistake data scrubbed and marked untrusted before LLM context.
Validation — frontmatter and structure checks before replacing files.
Checksums — rollback can detect manual edits since metamorph's last write.

Troubleshooting

Issue	Solution
Outdated dashboard format	`/metamorph-report` or start a new session
No data available	Complete at least one full Claude Code session
Hook errors	Check `data/hook-errors.log`
Validation failed on approve	Original file unchanged; review the error message
Rollback restored wrong file	Use full path: `/metamorph-rollback --file agents/architect.md`
Unreliable scores	Allow more sessions; default warm-up is 5

Runtime reference

Source: github.com/K3vin-h/metamorph

This branch is the installable plugin. It ships compiled runtime JavaScript in dist/ and omits source, tests, and build-only files.

CLI: node "${CLAUDE_PLUGIN_ROOT}/dist/index.js" <command>

Command	Purpose
`session-start` / `session-end`	Run hooks manually
`report-refresh` / `report-print`	Regenerate `report.md`; `report-print` also prints a clickable `report.md` link and dashboard
`improve-stats` / `improve-targets` / `improve-status`	Improve-flow output
`prepare-improve-batch <ids…>`	Build context files (shared run ID)
`prepare-improve <id> [runId]`	Prepare one target
`improve-approve` / `improve-reject` / `improve-list`	Suggestion lifecycle
`config-set` / `config-write`	Config updates (write max 64KB)
`feedback-add` / `feedback-list` / `feedback-clear`	Feedback log
`rollback-list` / `rollback-file` / `rollback-run`	Backup restore

Bundled subagent: agents/metamorph-diff.md (parallel diff generation for /metamorph).

License

MIT — see the GitHub repository.

Name		Name	Last commit message	Last commit date
Latest commit History 45 Commits
.claude-plugin		.claude-plugin
.codex-plugin		.codex-plugin
.cursor-plugin		.cursor-plugin
agents		agents
backups		backups
codex-skills/metamorph		codex-skills/metamorph
commands		commands
dist		dist
hooks		hooks
.gitignore		.gitignore
README.md		README.md
config.jsonc		config.jsonc
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

metamorph

Quick reference

Key terms

What metamorph does

How it works

Layer 1 — Background pipeline (zero tokens)

Layer 2 — Improvement pipeline (uses tokens)

Requirements

Installation

Claude Code

Cursor

Codex

First-time setup

Typical workflow

Efficient usage (token savings)

Commands

Core

Configuration

Approval and rollback

Feedback

Dashboard and scoring

Reading the report

Score composition

Flags

Privacy

Mistake tracking

What happens when you approve

Configuration reference

Data storage

Security

Troubleshooting

Runtime reference

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 16

Packages 0

Uh oh!

Contributors

Uh oh!

Packages