oliverweissl/context-garden / skills/mycelium
mycelium
VerifiedDecide whether to spawn subagents (one, or several in parallel) to search, investigate or edit, and brief them well; passes finding notes between agents so they don't redo the same exploration. Use before delegating to an agent and after an agent reports findings.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.2 KB |
| agents/botanist.md | markdown | 927 B |
| agents/landscaper.md | markdown | 1.3 KB |
| agents/scout.md | markdown | 1.3 KB |
| bin/myceliumexecutable | script | 1.2 KB |
| references/protocol.md | markdown | 5.1 KB |
| scripts/cg_mode.py | script | 5.4 KB |
| scripts/my_budget.py | script | 4.7 KB |
| scripts/my_gate.py | script | 7.7 KB |
| scripts/my_store.py | script | 14.0 KB |
| scripts/mycelium.py | script | 10.9 KB |
| tests/fixtures/mini_repo/README.md | markdown | 39 B |
| tests/fixtures/mini_repo/src/middleware.py | script | 167 B |
| tests/fixtures/mini_repo/src/refresh.py | script | 210 B |
| tests/smoke_test.sh | script | 13.6 KB |
scripts/mycelium.py
View on GitHub#!/usr/bin/env python3
"""mycelium: delegation gate + shared finding notes for subagents.
Commands: brief, note, list, verify, drop, install-agents, budget,
hook pre-agent|budget|subagent-stop (post-agent is a no-op kept for old settings).
See references/protocol.md.
"""
from __future__ import annotations
import argparse
import json
import os
import re
import shlex
import shutil
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent))
import my_budget # noqa: E402
from my_gate import LEVELS, default_budget, evaluate, format_notes, level # noqa: E402
from my_store import Store, split_by_repo, workspace_of, workspace_stores # noqa: E402
SKILL_DIR = Path(__file__).resolve().parent.parent
# Absolute wrapper path so printed handles run as-is (mycelium is not on PATH).
# Shell-quoted: printed for the agent to run, and plugin paths may contain spaces.
BIN = shlex.quote(str(SKILL_DIR / "bin" / "mycelium"))
def cmd_brief(store: Store, args) -> int:
notes = store.search(args.query, limit=args.limit, min_overlap=1)
if not notes:
print("Known: none relevant")
return 0
print("Known:\n" + format_notes(store, notes))
return 0
def cmd_note(store: Store, args) -> int:
ws = workspace_of(Path.cwd())
if ws is not None: # workspace: one note per repo holding the paths
missing = [p for p in args.paths if not (ws / p).exists()]
by_repo = split_by_repo(args.paths, ws) if not missing else {}
if missing or not by_repo:
print(f"mycelium: no such path(s) in a repo under {ws}: "
f"{', '.join(missing or args.paths)}", file=sys.stderr)
return 2
for root, rel in by_repo.items():
note = Store(root).add_note(args.topic, args.text, rel, kind=args.kind)
print(f"{root.name}: {note['id']} {note['topic']} ({len(note['paths'])} path(s) hashed)")
return 0
missing = [p for p in args.paths if not (store.repo_root / p).exists()]
if missing:
print(f"mycelium: no such path(s) under {store.repo_root}: {', '.join(missing)}", file=sys.stderr)
return 2
note = store.add_note(args.topic, args.text, args.paths, kind=args.kind)
print(f"{note['id']} {note['topic']} ({len(note['paths'])} path(s) hashed)")
return 0
def cmd_list(store: Store, args) -> int:
notes = store.load_notes()
if args.stale:
notes = [n for n in notes if store.stale_paths(n)]
if not notes:
print("no notes")
return 0
print(format_notes(store, notes))
return 0
def cmd_verify(store: Store, args) -> int:
note = store.verify(args.note_id)
if note is None:
print(f"mycelium: no note {args.note_id}", file=sys.stderr)
return 2
print(f"{note['id']} re-hashed; now current")
return 0
def cmd_drop(store: Store, args) -> int:
if not store.drop(args.note_id):
print(f"mycelium: no note {args.note_id}", file=sys.stderr)
return 2
print(f"dropped {args.note_id}")
return 0
def cmd_install_agents(store: Store, args) -> int:
dest = store.repo_root / ".claude" / "agents"
dest.mkdir(parents=True, exist_ok=True)
for src in sorted((SKILL_DIR / "agents").glob("*.md")):
target = dest / src.name
if target.exists():
print(f"kept existing {target}")
continue
shutil.copy2(src, target)
print(f"installed {target}")
return 0
def cmd_budget(store: Store, args) -> int:
"""Show or set the budget level that scales agents' default tool budgets."""
cfg = store.config()
if args.level:
store.set_config("budget_level", args.level)
cfg["budget_level"] = args.level
lvl = level(cfg)
print(f"budget level: {lvl}"
+ ("" if args.level or lvl == cfg.get("budget_level", "medium") else " (from the plugin option or MYCELIUM_BUDGET)"))
for t in ("scout", "botanist", "landscaper", "Explore", "general-purpose", "default"):
print(f" {t}: {default_budget(t, cfg)} tool calls")
return 0
def _hook_output(event: str, *, deny: str = "", context: str = "", update: dict | None = None) -> str:
out = {"hookSpecificOutput": {"hookEventName": event}}
if deny:
out["hookSpecificOutput"]["permissionDecision"] = "deny"
out["hookSpecificOutput"]["permissionDecisionReason"] = deny
elif update is not None:
out["hookSpecificOutput"]["permissionDecision"] = "allow"
out["hookSpecificOutput"]["permissionDecisionReason"] = "mycelium: brief completed"
out["hookSpecificOutput"]["updatedInput"] = update
if context:
out["hookSpecificOutput"]["additionalContext"] = context
return json.dumps(out)
_NOTES_HEADER = re.compile(r"^\s*(?:\*\*)?notes:(?:\*\*)?\s*$", re.I)
_NOTE_LINE = re.compile(r"^\s*[-*]\s+(.+?)\s+\|\s+(.+?)\s+\|\s+(.+?)\s*$")
def parse_notes(text: str) -> list:
"""(topic, finding, [paths]) from a `Notes:` block of an agent's reply:
lines `- <topic> | <finding> | <file> [<file>...]` up to the first blank
or non-bullet line. `path:line` is reduced to the path."""
out, inside = [], False
for line in (text or "").splitlines():
if _NOTES_HEADER.match(line):
inside = True
continue
if not inside:
continue
m = _NOTE_LINE.match(line)
if not m:
if out or line.strip():
break
continue
paths = [re.sub(r":\d+(?:-\d+)?$", "", p.strip("`,")) for p in m.group(3).split()]
out.append((m.group(1).strip("`*"), m.group(2), paths))
return out
def record_agent_notes(store: Store, text: str) -> list:
"""Record each well-formed note whose files exist; the rest are skipped
(a finding without a file to hash could never be marked stale). In a
workspace each note is filed in the repo(s) holding its files."""
recorded = []
ws = workspace_of(store.repo_root)
for topic, finding, paths in parse_notes(text):
if ws is not None:
for root, rel in split_by_repo(paths, ws).items():
real = [p for p in rel if (root / p).is_file()]
if real:
recorded.append(Store(root).add_note(topic, finding, real)["id"])
continue
real = [p for p in paths if (store.repo_root / p).is_file()]
if real:
recorded.append(store.add_note(topic, finding, real)["id"])
return recorded
def cmd_hook(store: Store, args) -> int:
"""Claude Code hook entry. Prints nothing on no-op paths; an error raises
(exit 1, a non-blocking hook error the user sees) and never denies the call."""
payload = json.loads(sys.stdin.read() or "{}")
if args.event == "post-agent":
return 0 # the reminder it printed is gone: SubagentStop records Notes: itself
if payload.get("cwd"): # resolve the store from the session's dir, not the hook's
os.chdir(payload["cwd"])
store = Store()
if args.event == "subagent-stop":
# Runs in the parent's harness, under the store lock: still "only
# the parent writes notes", without the parent spending a turn on it.
my_budget.forget(payload.get("session_id", ""), payload.get("agent_id", ""))
record_agent_notes(store, payload.get("last_assistant_message") or "")
return 0
if args.event == "budget":
answer = my_budget.decide(payload, store.config())
if answer:
print(json.dumps(answer))
return 0
if payload.get("tool_name") not in ("Agent", "Task"):
return 0
session = payload.get("session_id") or "unknown"
tool_input = payload.get("tool_input") or {}
ws = workspace_of(store.repo_root)
if ws is not None:
store = workspace_stores(ws, f"{tool_input.get('description', '')}\n{tool_input.get('prompt', '')}")
mode = store.config()["gate"]
if mode == "off":
return 0
with store.lock():
result = evaluate(store, session, tool_input, BIN)
if "deny" not in result:
ran = result["input"] or tool_input
store.log_spawn(session, ran.get("description", ""), ran.get("prompt", ""))
if "deny" in result:
key = "context" if mode == "warn" else "deny"
print(_hook_output("PreToolUse", **{key: result["deny"]}))
elif mode == "warn":
# warn: say what enforce would change, change nothing.
what = "would complete the brief" if result["input"] else ""
text = "; ".join(t for t in (what, result["context"]) if t)
if text:
print(_hook_output("PreToolUse", context=f"mycelium: {text}"))
elif result["input"] or result["context"]:
print(_hook_output("PreToolUse", context=result["context"], update=result["input"]))
return 0
def main(argv=None) -> int:
p = argparse.ArgumentParser(prog="mycelium", description=__doc__)
sub = p.add_subparsers(dest="cmd", required=True)
b = sub.add_parser("brief", help="print notes relevant to a task, as a `Known:` block")
b.add_argument("query")
b.add_argument("--limit", type=int, default=5)
n = sub.add_parser("note", help="record a finding (replaces the note with the same topic)")
n.add_argument("topic")
n.add_argument("text")
n.add_argument("paths", nargs="+", help="repo-relative files the finding describes")
n.add_argument("--kind", choices=["finding", "status"], default="finding")
ls = sub.add_parser("list", help="list notes")
ls.add_argument("--stale", action="store_true", help="only notes whose files changed")
v = sub.add_parser("verify", help="mark a note current after re-checking it")
v.add_argument("note_id")
d = sub.add_parser("drop", help="delete a note")
d.add_argument("note_id")
sub.add_parser("install-agents", help="copy agent templates to <repo>/.claude/agents/ (never overwrites)")
bl = sub.add_parser("budget", help="show or set the level scaling agents' default tool budgets")
bl.add_argument("level", nargs="?", choices=sorted(LEVELS, key=LEVELS.get))
h = sub.add_parser("hook", help="Claude Code hook entry (reads the hook JSON on stdin)")
h.add_argument("event", choices=["pre-agent", "budget", "post-agent", "subagent-stop"])
args = p.parse_args(argv)
handlers = {
"brief": cmd_brief, "note": cmd_note, "list": cmd_list, "verify": cmd_verify,
"drop": cmd_drop, "install-agents": cmd_install_agents, "budget": cmd_budget,
"hook": cmd_hook,
}
store = Store()
ws = workspace_of(store.repo_root)
if ws is not None: # a folder of repos: read the repos' stores, not its own
if args.cmd in ("verify", "drop"):
print("mycelium: note ids are per repo; run this from inside the repo "
f"(cd <repo> && {BIN} {args.cmd} {args.note_id})", file=sys.stderr)
return 2
if args.cmd in ("brief", "list"):
store = workspace_stores(ws, getattr(args, "query", ""))
return handlers[args.cmd](store, args)
if __name__ == "__main__":
sys.exit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |