Debug Mycelium

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  --since 1h --format table

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

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

# For full context (JSONL for analysis):
mycelium report --item  --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 | 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 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 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 --since 5m to confirm no more errors

If the fix requires a code change:

• Save the report to a file: mycelium report --item --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///

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

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 |

Source & license

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

• Author: bytemines
• Source: bytemines/mycelium
• License: MIT
• Homepage: https://mycelium.to

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