Mycelium

Static analysis CLI that maps the connections in a source code repository. Produces a single JSON file containing file structure, symbols, imports, call graph, community clusters, and execution flows.

Powered by a Rust engine with tree-sitter parsing, exposed to Python via PyO3.

What it produces

Mycelium runs a six-phase pipeline over your source code and outputs a single JSON file:

Install

uvx mycelium-map analyze .

Version 0.4.2 and newer include the compiled Rust engine in wheels for standard CPython 3.12+ on Linux with glibc (x86_64, aarch64), macOS (x86_64, aarch64), and Windows (x86_64). These installations need no Rust toolchain. The same wheel is tested on Python 3.12, 3.13, and 3.14 for each platform. uvx runs the CLI in a temporary tool environment; add --no-build to require prebuilt packages:

uvx --no-build mycelium-map export map.json -o diagram.md

For a persistent CLI and the Python API, install into an activated virtual environment:

python -m pip install --upgrade --only-binary=mycelium-map mycelium-map

Building from source requires Rust. Platforms without wheels, PyPy, and free-threaded Python are outside the prebuilt support above; the binary-only commands fail instead of compiling locally.

Agent skills

Two skills use the PyPI package through uvx and work in any repository:

• mycelium-mermaid generates a Mermaid class diagram as Markdown.
• mycelium-architecture uses that generator to write docs/assets/mycelium_class_diagram.md and add an AGENTS.md instruction to read it before code changes or architectural work.

Install both with the Skills CLI:

npx skills add ScottRBK/mycelium --skill mycelium-mermaid mycelium-architecture

For diagram generation alone:

npx skills add ScottRBK/mycelium --skill mycelium-mermaid

Add --global to make the skills available across projects. Bundled references travel with the generator skill; neither skill requires a Mycelium checkout. Ask your agent to use mycelium-mermaid for a diagram, or mycelium-architecture to generate it and update AGENTS.md.

Usage

mycelium-map analyze <path>                          # Analyse a repo
mycelium-map analyze <path> -o output.json           # Custom output path
mycelium-map analyze <path> --verbose                # Show phase timing breakdown
mycelium-map analyze <path> --quiet                  # No terminal output
mycelium-map analyze <path> -l cs,ts                 # Only analyse C# and TypeScript
mycelium-map analyze <path> --exclude vendor,legacy  # Skip directories
mycelium-map analyze <path> --resolution 1.5         # Louvain resolution (higher = more communities)
mycelium-map analyze <path> --max-processes 50       # Limit execution flows
mycelium-map analyze <path> --max-depth 8            # Limit BFS trace depth

Default output file: <repo-name>.mycelium.json

Python API

from mycelium import analyze

result = analyze("path/to/repo")
print(result["stats"])

Mermaid class diagrams

mycelium-map analyze ./my-project -o map.json --quiet
mycelium-map export map.json -o diagrams.md
mycelium-map export map.json -o services.md --path src/services --max-classes 6

Exports typed fields, parameter/return signatures, declared type relationships, and labelled calls as deterministic Mermaid Markdown. Large views split into bounded diagrams with a complete list of resolved relationships. Both CLIs and mycelium.export_mermaid(result) share the Rust exporter. Exports hide recognised Rust/Go tests and supported Python, .NET, Java and JS/TS framework declarations by default. Use --test-path tests for explicit test folders (including C/C++), --keep-path for exceptions, and --tests include for the full view. Reanalyse older maps for new framework rules. See coverage, limitations, and pinned repository checkpoints.

Supported Languages

Output Schema

The JSON output contains these top-level sections:

metadata

{
  "repo_name": "my-project",
  "repo_path": "/absolute/path",
  "analysed_at": "2026-02-05T18:33:12Z",
  "mycelium_version": "1.0.0",
  "commit_hash": "a1b2c3d4e5f6",
  "analysis_duration_ms": 42.3,
  "phase_timings": { "structure": 0.004, "parsing": 0.001, ... }
}

stats

Summary counts: files, folders, symbols, calls, imports, communities, processes, and a languages breakdown by file count.

structure

File tree with language, size, and line counts.

{
  "files": [{ "path": "src/main.cs", "language": "cs", "size": 1024, "lines": 45 }],
  "folders": [{ "path": "src/", "file_count": 3 }]
}

symbols

Every extracted symbol: classes, methods, interfaces, functions, structs, enums, etc.

{
  "id": "sym_0001",
  "name": "UserController",
  "type": "Class",
  "file": "Controllers/UserController.cs",
  "line": 8,
  "visibility": "public",
  "exported": true,
  "parent": "MyApp.Controllers",
  "language": "cs"
}

Symbol types: Class, Function, Method, Interface, Struct, Enum, Namespace, Property, Constructor, Module, Record, Delegate, TypeAlias, Constant, Trait, Impl, Macro, Typedef, Annotation.

Visibility: public, private, internal, protected.

imports

Three categories of dependency edges:

{
  "file_imports": [{ "from": "Controller.cs", "to": "Service.cs", "statement": "using MyApp.Services" }],
  "project_references": [{ "from_project": "Web.csproj", "to_project": "Core.csproj", "ref_type": "ProjectReference" }],
  "package_references": [{ "project": "Web.csproj", "package": "Newtonsoft.Json", "version": "13.0.1" }]
}

Project and package references are extracted from .csproj/.vbproj files.

calls

Call graph edges with three-tier confidence scoring:

{
  "from": "sym_0004",
  "to": "sym_0015",
  "confidence": 0.9,
  "tier": "A",
  "reason": "import-resolved",
  "line": 17
}

communities

Clusters of symbols that frequently call each other, detected via Louvain algorithm.

{
  "id": "community_0",
  "label": "Absence",
  "members": ["sym_0004", "sym_0015", "sym_0016"],
  "cohesion": 0.8,
  "primary_language": "cs"
}

processes

Execution flows traced from entry points (controllers, handlers, main functions) via BFS through the call graph.

{
  "id": "process_0",
  "entry": "sym_0004",
  "terminal": "sym_0016",
  "steps": ["sym_0004", "sym_0015", "sym_0016"],
  "type": "intra_community",
  "total_confidence": 0.765
}

type is intra_community when all steps are in the same community, or cross_community when the flow spans multiple.

total_confidence is the product of all edge confidences along the path.

Development

# Rust tests
cargo test --workspace

# Build Python bindings locally
pip install maturin
maturin develop --release

# Run binding tests
pytest tests/test_bindings.py -v

# Rust CLI (alternative to Python CLI)
cargo run -p mycelium-cli -- analyze <path>

Releasing

Releases are automated via GitHub Actions. Push a semver tag to trigger a release:

git tag v1.0.0
git push origin v1.0.0

This will:

1. Build binary wheels for Linux, macOS, and Windows
2. Build a source distribution
3. Publish all to PyPI