convez.ai
Skill
K3vin-h

metamorph

K3vin-h/metamorph

Ver no GitHub
InicialPluginScore · de 0 a 100

Claude Code plugin: self-improving agents & skills with utilization scoring and suggest-only rewrites

Instalação

$npx convez-ai K3vin-h/metamorph

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
v1.2.7
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

metamorph

Version 1.2.7

metamorph is a local-first AI-agent observability and improvement tool for Claude Code, Cursor, and Codex. It observes how you actually use your agents, skills, and CLAUDE.md files, builds a text dashboard that scores each target, and proposes small file edits as diffs you review. Suggest-only with one-level rollback, no telemetry, and tokens spent only when you ask for an improvement.

Local-first & private: observation, scoring, and the dashboard run entirely on your machine — no network calls, no telemetry. See docs/privacy-model.md.

Suggest-only by design: metamorph never auto-applies edits. You review every diff first, every applied change is backed up, and /metamorph-rollback undoes it.

Runtime-only repo: main contains the files users install and run, plus tests/ and CI that validate the shipped dist/ artifact. TypeScript source, source maps, and build-only files are intentionally not shipped in this branch.

Documentation:


Quick reference

GoalCommand
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

TermMeaning
AgentA specialized assistant definition Claude can invoke (e.g. architect, code-reviewer)
SkillAn instruction file Claude loads for specific tasks (e.g. tdd-workflow)
CLAUDE.mdProject-level instructions that guide Claude's behavior
SessionOne work period in Claude Code, from open to close
HookAn automatic script that runs at session start or end — no AI involved
TokenA unit of AI usage; only the improvement step consumes tokens
DiffA line-by-line list of what would change in a file
FlagA short label on the dashboard (inactive, underused, healthy, etc.) explaining a finding
ScoreA number from 0–100; lower usually means more room to improve
Warm-upInitial sessions where metamorph collects data before marking the dashboard ready (default: 5)

What metamorph does

  1. Observes your Claude Code sessions through background hooks (local parsing only — no AI).
  2. Scores each agent and skill based on real usage patterns.
  3. Publishes a text report (report.md) with scores, flags, and warm-up status.
  4. Proposes targeted diffs when you run /metamorph.
  5. 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:

HookWhenWhat it does
SessionStartSession opensRefreshes report.md; prints a compact 2-line status (session count, flagged count, top target)
SessionEndSession closesParses 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:

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

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


Requirements

RequirementDetails
Claude CodePlugin 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:

SettingWhat it controls
Read scopeWhich Claude config folders to analyze: global, project, or both
Transcript privacyHow much session data to store: full, redacted, or off
Write targetsWhether metamorph may suggest edits to agents, skills, and/or CLAUDE.md
Warm-up sessionsSessions to collect before the dashboard shows ready (default: 5)
Flag thresholdScores below this value receive the underused flag (default: 40)
Deny-read globsFile 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

  1. Install the plugin and run /metamorph-setup.
  2. Use Claude Code normally for several sessions (at least 5 by default).
  3. Run /metamorph-report to view the dashboard.
  4. Run /metamorph, select targets, review diffs, and approve what you want.
During warm-upAfter warm-up
Dashboard shows warm-up 2/5 (example)Dashboard shows ready
Session start reports sessions remainingSession start suggests /metamorph
/metamorph works if session data existsScores are generally more reliable

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


Efficient usage (token savings)

PracticeEffect
/metamorph-reportZero 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 onlyDefault interactive flow uses improve-targets-actionable (excludes inactive targets)
improve.skipNeverInvoked: trueBatch prepare skips inactive agents/skills (default in 1.2.7)
transcripts: redactedSmaller cache — default; use full only if you need mistake text
Prune unused agents/skillsBiggest 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

CommandDescription
/metamorphInteractive: actionable targets → diffs → approval
/metamorph --statusWarm-up progress, recommended target IDs, top flags
/metamorph --target <id>Improve a single target directly (preferred for token savings)
/metamorph-reportRefresh 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

CommandDescription
/metamorph-setupSetup wizard
/metamorph-setup --resetReset defaults, then wizard
/metamorph-config showDisplay current settings
/metamorph-config set key=valueUpdate 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

CommandDescription
/metamorph-improve --listList pending suggestions by run ID
/metamorph-improve --approve <runId>-<targetId>Apply one approved diff
/metamorph-improve --approve allApply all pending from the latest run
/metamorph-improve --reject <id>Discard a suggestion
/metamorph-improve --reject allDiscard all pending suggestions
/metamorph-rollback --listList 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:

FactorWeightWhat it measures
Invocation frequency40%How often you use it vs total agent runs or skill loads
Tool utilization30%Declared tools vs tools actually observed in sessions
Section coverage20%Whether documented sections align with your workflow
Skill apply rate10%Skills only: times loaded vs times actually applied

Flags

FlagMeaning
—No primary issue
inactiveNo observed use, or a skill loaded but was never applied
underusedUsed at least once, but score is below flagThreshold (default: below 40)
healthyScore is 80 or higher and the target appears active
tool-gapA declared tool was not seen in your sessions
stale-docA 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)
correctionRepeated correction patterns detected

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


Privacy

ModeWhat is stored
redacted (default)Metadata only: tool names, file extensions, hashed path fragments, timestamps — not full prompts or file contents
fullComplete transcript bodies and tool inputs
offAggregate 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.

CountsDoes not count
Tool completes successfully, then you send a fix messageDeclined tool calls
You reject a suggestion with /metamorph-improve --rejectFailed 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

  1. The diff is applied to a temporary copy of the target file.
  2. The copy is validated (required frontmatter keys, balanced code fences).
  3. If validation passes: the original file is backed up, then replaced.
  4. 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

SettingValuesDefault
modesuggest onlyCannot auto-apply
warmupSessions1–505
flagThreshold0–10040
maxSuggestionsPerRun1–203
read.scopeglobal, project, bothboth
read.transcriptsfull, redacted, offredacted
read.mistakeTrackingtrue, falsetrue
read.trackCursortrue, falsetrue
read.trackCodextrue, falsetrue
improve.skipNeverInvokedtrue, falsetrue
improve.minScore0–10030
improve.minInvocations0–1001
write.targets.agentstrue, falsetrue
write.targets.skillstrue, falsetrue
write.targets.claudeMdfalse, global, local, bothfalse
write.allowpath globsagents/*, skills/*/SKILL.md
write.denypath 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/
PathPurpose
config.jsoncSettings
report.mdText dashboard
data/analysis.jsonScores and flags
data/profile.jsonSession cache (up to 500 sessions)
data/feedback.logUser feedback entries
data/hook-errors.logHook error log
data/style-profile.jsonStyle patterns for suggested edits
data/mistake-feedback.jsonlMistake 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

IssueSolution
Outdated dashboard format/metamorph-report or start a new session
No data availableComplete at least one full Claude Code session
Hook errorsCheck data/hook-errors.log
Validation failed on approveOriginal file unchanged; review the error message
Rollback restored wrong fileUse full path: /metamorph-rollback --file agents/architect.md
Unreliable scoresAllow 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>

CommandPurpose
session-start / session-endRun hooks manually
report-refresh / report-printRegenerate report.md; report-print also prints a clickable report.md link and dashboard
improve-stats / improve-targets / improve-statusImprove-flow output
prepare-improve-batch <ids…>Build context files (shared run ID)
prepare-improve <id> [runId]Prepare one target
improve-approve / improve-reject / improve-listSuggestion lifecycle
config-set / config-writeConfig updates (write max 64KB)
feedback-add / feedback-list / feedback-clearFeedback log
rollback-list / rollback-file / rollback-runBackup restore

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


License

MIT — see the GitHub repository.

Ver o original no GitHub

Bom para

Relacionados