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

# 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

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:

~/.claude.json

.claude/settings.json

~/.cursor/mcp.json

~/.vscode/settings.json

~/.codex/config.toml

~/.gemini/settings.json

~/.opencode/config.json

~/.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]

Dimension Reference

These are the filterable dimensions in

mycelium report

--cmd

--scope

--op

--tool

--item

--level

--state

--source

--trace

--project

--since