| name | mycelium |
| description | Hidden layer of structured git notes for agent collaboration. When working in any git repo, check for notes on objects you touch before acting, and leave notes after meaningful work. Uses git notes directly — helper script and workflow scripts included.
|
Mycelium
Structured notes attached to git objects via refs/notes/mycelium.
Before working on a file, check for its note. After meaningful work, leave a note.
That’s the whole contract. Mycelium is the storage layer. Richer arrival / history workflows can live in skill scripts.
On arrival
Start every session with:
mycelium.sh find constraint
mycelium.sh find warning
scripts/context-workflow.sh <file>
If you only have the runtime file and not this repo checkout, do the same workflow manually:
mycelium.sh read <file>
mycelium.sh read HEAD
Before leaving:
mycelium.sh note HEAD -k context -m "What I did and why."
mycelium.sh note <changed-file> -k <kind> -m "What future agents should know."
If you made a decision, use kind decision and add a tested-by edge to the test that validates it. If you found something fragile, use kind warning.
Core commands
Use these as the protocol-ish primitives:
mycelium.sh note [target] -k <kind> -m <body>
mycelium.sh read [target]
mycelium.sh follow [target]
mycelium.sh refs [target]
mycelium.sh find <kind>
mycelium.sh kinds
mycelium.sh list
mycelium.sh branch [use|merge] [name]
mycelium.sh doctor
mycelium.sh dump
Workflow scripts in this repo
These are recommended workflows, not part of the core CLI:
scripts/context-workflow.sh <path> [ref]
scripts/path-history.sh <path> [ref]
scripts/note-history.sh <target>
scripts/compost-workflow.sh [path|oid] [--compost|--renew]
Use them when you want richer context, but keep in mind they are recipes built on top of git + mycelium primitives.
Rule of thumb:
context-workflow.sh = default arrival workflow for a pathpath-history.sh = explicit historical notes for a filenote-history.sh = overwrite history for one note targetcompost-workflow.sh = opt-in stale/renew lifecycle for repos that still want it
If a repo still wants an explicit stale/renew lifecycle, use scripts/compost-workflow.sh. The simpler default is to use git-native history first and write a fresh current note when older context still matters.
Patterns
Three patterns cover most usage.
Pattern 1: One ref accumulates many notes
A file can collect notes from different agents over time.
mycelium.sh note src/auth.ts -k summary -m "Handles OAuth2 refresh flow."
mycelium.sh note src/auth.ts -k warning -m "Token refresh has a race condition."
mycelium.sh refs src/auth.ts
When you need older notes on that file, use git history rather than a special core lifecycle command:
scripts/path-history.sh src/auth.ts
Pattern 2: One note connects many refs
A single note can link to multiple objects via edges.
mycelium.sh note SKILL.md -k decision -t "Packaged as an agent skill" \
-e "depends-on blob:$(git rev-parse HEAD:README.md)" \
-m "The skill teaches agents the convention on-demand."
mycelium.sh follow SKILL.md
Use this whenever a note’s meaning involves more than one object.
Pattern 3: Planning graph
Use depends-on edges to structure planned work.
mycelium.sh note src/auth.ts -k context -t "Planned: fix race condition" \
-m "Need mutex around token refresh. See warning note."
mycelium.sh note src/http.ts -k context -t "Planned: retry after refresh" \
-m "HTTP client should retry once after auth refresh."
mycelium.sh note HEAD -k context -t "Plan: auth hardening" \
-e "depends-on blob:$(git rev-parse HEAD:src/auth.ts)" \
-e "depends-on blob:$(git rev-parse HEAD:src/http.ts)" \
-m "Two files need coordinated changes."
Check for notes
mycelium.sh read path/to/file.ts
mycelium.sh follow HEAD
mycelium.sh refs path/to/file.ts
mycelium.sh find decision
mycelium.sh find constraint
git log --notes=mycelium --oneline -20
Or with raw git:
git notes --ref=mycelium show $(git rev-parse HEAD:path/to/file.ts) 2>/dev/null
git notes --ref=mycelium show HEAD 2>/dev/null
Leave notes
mycelium.sh note -k context -m "Why I did this."
mycelium.sh note path/to/file.ts -k summary -m "What this does."
mycelium.sh note src/auth/ -k constraint -m "Must be retryable."
mycelium.sh note . -k value -m "Project-level principle."
mycelium.sh note -k decision -t "Use YAML" -m "Needs comments."
Target stability
Every target has different stability.
| Target | Stable? | Use when |
|---|
path/to/file | ✓ findable by path even if file changes | Note is about the file |
$(git rev-parse HEAD:file) | pinned to this exact blob OID | Note is about this specific version |
. | ✓ project-level, always findable | Note applies to the whole repo |
HEAD | pinned to commit OID (jj: survives via change_id) | Note is about this change |
src/dir/ | ✓ findable by path | Note is about the module |
Default: use paths. Most notes are about files, not specific versions. The path edge keeps them findable. Use raw OIDs only when you mean “this exact content.”
Note format
kind decision
title Short label
edge explains commit:abc123...
edge targets-path path:src/auth/retry.ts
Free-form body. Markdown encouraged.
Headers: kind (required), edge, title, status
Kinds: decision · context · summary · warning · constraint · observation · value · todo — or invent your own.
Edge types: explains · applies-to · depends-on · warns-about · targets-path · targets-treepath — or invent your own.
Targets: commit:<oid> · blob:<oid> · tree:<oid> · path:<filepath> · note:<oid>
Note history
There is no special supersedes chain in the note body. Overwrite history lives in git itself on the notes ref.
scripts/note-history.sh path/to/file.ts
Or raw git:
OID=$(git rev-parse HEAD:path/to/file.ts)
FANOUT="${OID:0:2}/${OID:2}"
git log -p refs/notes/mycelium -- "$FANOUT"
Historical notes for a file
If you want older notes on a file path, use git history:
scripts/path-history.sh src/auth.ts
If an older note still matters, write a fresh current note that carries forward the relevant insight.
Slots
Multiple tools or agents can write notes on the same object without obliteration. Each slot is a named lane backed by its own notes ref.
mycelium.sh note src/auth.ts --slot skeleton -k observation -m "Structure."
mycelium.sh note src/auth.ts --slot enricher -k summary -m "Context."
mycelium.sh read src/auth.ts --slot skeleton
Rules:
read / follow use the default slot unless --slot is givenfind / kinds / doctor / prime aggregate all slots- Reserved names:
main, default
Setup (once per clone)
mycelium.sh activate
mycelium.sh sync-init
mycelium.sh repo-id init
mycelium.sh zone init
mycelium.sh export f -a internal
mycelium.sh export --all --audience internal
mycelium.sh export --all --kind decision -a public
mycelium.sh import remote --as lib
mycelium.sh list-imports
jj+git colocated repos
If .jj/ is detected, mycelium adapts automatically — no flags needed. Commit notes get a targets-change edge (stable across jj rewrites). read falls back to change_id lookup when the commit OID changes. Prefer notes on files over commits — blob OIDs survive rewrites, commit OIDs don’t.
When jj rewrites commits (amend, rebase, squash), notes on old OIDs become orphaned. Use migrate to bulk-reattach them:
mycelium.sh migrate --dry-run
mycelium.sh migrate
mycelium.sh migrate --map mapping.txt
Run mycelium.sh help for jj-specific guidance.
