debug-mycelium

name	debug-mycelium
description	Use when mycelium sync fails, items not appearing in tools, enable/disable not working, MCP not connecting, config conflicts between levels, EACCES permission errors, or any unexpected mycelium CLI behavior.

Debug Mycelium

Systematic diagnostic workflow using Mycelium's built-in SQLite trace database. Traces capture 16 dimensions per operation — filter to the exact slice that matters, never read the full DB.

When to Use

• mycelium sync fails or skips items
• Item shows as enabled but doesn't appear in tool config
• Enable/disable has no effect
• MCP server not connecting after sync
• Config conflicts between global/machine/project levels
• Permission errors (EACCES, EPERM)
• Migration imports wrong or missing items
• "It worked before but stopped" scenarios

Step 1: Gather Context

Ask the user:

• What command were you running? (sync, enable, disable, add, remove, migrate)
• What item is affected? (MCP name, skill name, plugin name)
• Which tool? (cursor, claude-code, vscode, etc.)
• What did you expect vs what happened?

Step 2: Pull Filtered Traces

Run the mycelium report command with appropriate filters. Always start narrow:

# If user mentions a specific item:
mycelium report --item <name> --since 1h --format table

# If user mentions a specific tool:
mycelium report --tool <tool> --level error,warn --since 1h --format table

# If user mentions a specific command:
mycelium report --cmd <command> --since 1h --format table

# For full context (JSONL for analysis):
mycelium report --item <name> --full --format jsonl

Important: Always use --since to limit results. Never pull the full DB.

Step 3: Check Health

mycelium doctor --json

Look for:

• Failed config checks (broken YAML/JSON/TOML)
• Broken symlinks (skills not properly linked)
• Missing directories
• MCP connectivity failures

Step 4: Check Manifest State

# Read the manifest directly
cat ~/.mycelium/global/manifest.yaml

# Or for project-level:
cat .mycelium/manifest.yaml

Look for:

• state field: is the item enabled, disabled, or deleted?
• source field: where did this item come from?
• Missing items: was the item never added?

Step 5: Check Tool Config

Read the tool's native config file to verify the sync result:

Tool	Config Path
Claude Code	~/.claude.json or .claude/settings.json
Cursor	~/.cursor/mcp.json
VS Code	~/.vscode/settings.json
Codex	~/.codex/config.toml
Gemini CLI	~/.gemini/settings.json
OpenCode	~/.opencode/config.json
OpenClaw	~/.openclaw/plugins.json

Verify the MCP entry exists and has correct structure for that tool's format.

Step 6: Analyze the Trace

Read the JSONL output from Step 2. Look for these patterns:

Common Issues

Item not syncing (state bug):

• Check trace for op: "filter" entries — was the item filtered out?
• Check state dimension — is it disabled or deleted?
• Check source — was it from a plugin that got removed?

Permission errors:

• Check trace for error containing "EACCES" or "EPERM"
• Check path dimension — which file had the permission issue?
• Fix: chmod the file or run with appropriate permissions

Config parse errors:

• Check trace for format dimension — which format failed?
• Check path — which config file is malformed?
• Validate the file manually: cat <path> | python3 -m json.tool

Adapter method fallback:

• Check method dimension — did it try "cli" then fall back to "file"?
• Check if the tool's CLI is installed and accessible

Merge conflicts:

• Check trace for configLevel — which level caused the conflict?
• Check phase: "merge" entries for warnings
• Read all 3 config levels: global, machine, project

MCP still in tool config after disable:

• mycelium disable <mcp> updates manifest but MCP remains in ~/.claude.json (or other tool configs)
• Root cause: item was registered in wrong manifest section (e.g. skills.massive instead of mcps.massive)
• Check manifest: cat ~/.mycelium/manifest.yaml — verify item is in mcps: section, not skills:
• Fix: move the entry to the correct section, then run mycelium disable <name> again
• After fix, disable now calls adapter.remove() on tool configs and enable calls adapter.add()

Item not found (typo):

• Check item dimension — does the name have a typo? (e.g., postgress-mcp vs postgres-mcp)
• Query with LIKE: mycelium report --item postgres to find all variants
• Compare against manifest to find the correct name

Step 7: Generate Report

Once you've identified the issue, create a structured report:

## Problem
[1-2 sentence summary of what's broken]

## Root Cause
[What the trace analysis revealed]

## Relevant Trace
\`\`\`
[Paste the key 5-10 trace entries that show the problem]
\`\`\`

## Doctor Output
[Any relevant failed/warning checks]

## Manifest State
[Item state and source from manifest]

## Environment
- OS: [from mycelium report --full]
- Node: [version]
- Mycelium: [version]
- Tool: [affected tool and version]

## Fix
[Suggested fix — either a command to run or a code change to make]

Step 8: Apply Fix or File Issue

If the fix is a user action (config change, permission fix):

• Guide the user through the fix
• Run mycelium sync to verify
• Run mycelium report --item <name> --since 5m to confirm no more errors

If the fix requires a code change:

• Save the report to a file: mycelium report --item <name> --full --output /tmp/mycelium-report.jsonl
• The user can paste the report into a GitHub issue
• Or create a PR directly with the fix

Plugin Takeover Debugging

When plugin takeover isn't working (skills/agents/commands from Claude Code plugins not appearing or disappearing):

Quick diagnosis

# All plugin operations
mycelium report --scope plugin --since 1h --format table

# Specific operation type (takeover, release, symlink-create, symlink-remove, health-check)
mycelium report --op takeover --since 1d --format table

# Symlink operations only
mycelium report --op symlink-create,symlink-remove --since 1h --format table

# Plugin health check results
mycelium report --op health-check --scope plugin --since 1h --format table

# All operations on a specific plugin
mycelium report --item superpowers@skillsmp --since 1d --format table

Common plugin issues

Component missing after disable/enable cycle:

1. Check symlink operations: mycelium report --op symlink-create,symlink-remove --since 1h
2. Check if the component type is correct: look for itemType in trace entries (skill, agent, command)
3. Run doctor: mycelium doctor — check "Plugin Takeover" section for invariant violations
4. Fix: mycelium sync re-runs syncPluginSymlinks() to reconcile state

Plugin shows as taken over but components aren't working:

1. Check health: mycelium doctor — invariant checks verify symlinks, settings.json, cache
2. Check sync: mycelium report --cmd plugin-sync --level error,warn
3. Verify cache: ls ~/.claude/plugins/cache/<marketplace>/<plugin>/

Release didn't re-enable plugin:

1. Check settings.json: cat ~/.claude/settings.json | grep enabledPlugins
2. Check traces: mycelium report --op release --since 1h
3. Check if all components were re-enabled: mycelium report --scope manifest --item <plugin-component>

Dashboard Debug Logging

For UI issues (sidebar flicker, toggle state, graph reloads), enable browser-side debug logging. Run in the browser console on localhost:3378:

localStorage.setItem("mycelium:debug:panel", "1")  // [panel] animation lifecycle
localStorage.setItem("mycelium:debug:store", "1")  // [store] state operations

Refresh, reproduce the issue, then read [panel]/[store] logs in the console. Remove keys and refresh to disable.

Dimension Reference

These are the filterable dimensions in mycelium report:

Flag	Description	Values
--cmd	CLI command	sync, enable, disable, add, remove, migrate, doctor, plugin-sync, mcp
--scope	What type	mcp, skill, config, memory, hook, plugin, manifest
--op	Operation	takeover, release, symlink-create, symlink-remove, health-check, inject, sync, disable, enable
--tool	Which tool	claude-code, cursor, vscode, codex, gemini, opencode, openclaw, antigravity
--item	Item name	any MCP/skill/hook/plugin name
--level	Severity	debug, info, warn, error
--state	Manifest state	enabled, disabled, deleted
--source	Item source	plugin name or "manual"
--trace	Trace ID	sync-abc123 (from trace output)
--project	Project name	directory name
--since	Time range	1h, 30m, 7d, 2026-02-10