Mycelium

myco reads per-repo mycelium.toml metadata across a set of repo roots, merges it with a private relationship overlay into one agent-readable graph (MAP.md + graph.json), audits that graph for rot, and serves it over HTTP. It gives a coding agent a map of an ecosystem: which repos and services exist and when each applies.

Both outputs are for agents, not humans, and serve two use cases: read MAP.md into context to orient (a lossy, skimmable Markdown digest), and query graph.json to extract (the full-fidelity graph — every field — for jq/filter/traverse). See schema/graph.md.

Status: working, pre-1.0 — the public surface (CLI flags, graph schema) can still shift. The architecture is distributed: nodes scan repo roots and push manifests to a central hub, which ingests and rebuilds the graph, then serves it over HTTP. The graph is only as rich as the mycelium.toml sidecars committed across the scanned repos.

Build

go install ./cmd/myco   # installs myco to the Go bin dir, on PATH
myco version            # or --version, -v

Or build in place — the binary lands in the repo root, so invoke it as ./myco:

go build -o myco ./cmd/myco

Use

Scan and collect metadata

myco scan --roots <dir>[,<dir>] --node <id> --out manifest.json

Walks the repo roots, reads each committed mycelium.toml sidecar, gathers git metadata (origin remote, commit at the scanned ref), and writes a manifest (JSON) to --out, or stdout without it. --node names the node the manifest comes from; --push requires it.

Node (scan where the repos live, push to a hub)

myco scan --roots <repo-store> --node <id> \
  --exclude-owners vendor --fallback-host <host> \
  --ref dev --push https://<hub> --token-file /path/to/token

Reads each repo's committed mycelium.toml (bare repos and working trees alike), skips the owners listed in --exclude-owners, and POSTs the manifest to the hub. --fallback-host is the host recorded for repos with no origin remote. --ref <branch> reads the sidecar from that branch (e.g. dev) instead of HEAD, falling back to HEAD per-repo when the branch is absent; omit it to read each repo's HEAD (a bare repo's default branch, or a working tree's checked-out branch).

To include each repo's doc-graph digest (below), the node needs docgraph v3.1.0+ on its PATH; without it, or with an older one, the scan leaves the digests out and carries on.

Hub (ingest manifests, rebuild, serve)

myco serve --manifests <dir> --overlay overlay.toml \
  --dir ./graph --ingest-token-file /path/to/token --addr :8080

Serves /MAP.md and /graph.json, GET /repos/<id>/docgraph.json (a component's full doc-graph payload, when it has one), and accepts POST /manifests (node-keyed, bearer-authenticated); each push rebuilds the served graph. Each component in graph.json carries a compact docGraph digest when the node captured one — see schema/graph.md. --ingest-token-file is optional — omit it only behind a trusted network boundary; the hub then logs a loud warning that ingest is unauthenticated.

Build and audit locally (single-node)

myco build --manifests <dir> --overlay overlay.toml --dir ./graph
myco audit --dir ./graph

audit reports graph rot:

• orphans — scanned repos with no committed mycelium.toml;
• invalid sidecars — a committed mycelium.toml that fails to parse (the scan records it and carries on);
• dangling overlay edges, and edges of an unknown type;
• duplicate names — two entries claiming one name;
• components that vanished since the last run;
• doc-rot — a component with docs nothing links to, or docs with no declared place in its doc graph;
• docgraph-version — a component whose docgraph schemaVersion is not 1, the version Mycelium reads (including none at all);
• stale-manifest — a node whose last manifest trails the freshest by more than three days: it has stopped scanning, and the freshest manifest already outranks it wherever both report a repo.

Repos that intentionally have no sidecar are suppressed via an ignore list of canonical ids in the private overlay.toml (see schema/graph.md).

Validate a sidecar

myco validate <mycelium.toml>

Lints a single mycelium.toml against the schema — run it before committing a new sidecar. Prints the parsed name and summary on success, or the schema error.

Query the graph

myco query is the first-class way to explore and discover — it answers named questions without your needing to know graph.json's structure:

myco query <name> [args] [--url <hub> | --dir <dir>] [--json]

Queries: capabilities, capability <name>, component <name>, components --kind=… --stack=… --status=… --tag=…, used-by <name>, uses <name>, search <text>. Bare myco query prints the index. It reads a local graph.json (--dir, default .) or a hub (--url, default $MYCELIUM_HUB — set that once and no flag is needed). Flags may go before or after the positional. Text by default, --json to pipe.

The hub also serves the same queries over HTTP at GET /q/* (GET /q lists them). For jq over graph.json, see schema/graph.md.

Demo

See a populated graph built from the bundled examples — no real repos needed:

./scripts/demo.sh

It materialises the bundled examples/ into throwaway git repos in a temp dir and runs the full scan → build → audit pipeline.

Reference

• schema/graph.md — the mycelium.toml sidecar and overlay.toml schema (fields, node/edge shapes, public-safe vs private split).
• schema/consult-snippet.md — the standing-instruction snippet to drop into a consuming agent's CLAUDE.md/AGENTS.md so it consults the served graph proactively.

Development

just build   # go build -o myco ./cmd/myco
just install # go install ./cmd/myco (myco onto PATH)
just test    # go test ./...
just gate    # gofmt check + vet + tests (pre-merge gate)
just release # cut a release from dev

The branch model (dev trunk, main release branch) and release flow live in CLAUDE.md.