Installation and host compatibility¶

Install Mycelium Extra once, then choose which projects should use its approval gate. The same planning skills are available in Claude Code, Codex, and OpenCode. If your project already uses Mycelium, the plugin reads its decisions and conventions; in an ordinary repository, it starts with your existing documentation and code.

You can begin with a question such as:

“Plan the next analysis using this project’s sample table and previous decisions.”

Install for your host, then choose a usage tier. Planning with grill needs no gate setup; turn on the gate when you want covered execution checks.

Claude Code¶

Add the marketplace and install the plugin:

claude plugin marketplace add mdmanurung/mycelium-extra
claude plugin install mycelium-extra@mycelium-extra

This makes the plugin’s skills available as /mycelium-extra:<skill> commands. Restart Claude Code, then invoke /mycelium-extra:grill <task>. For a project-local install, run the install command in that project with --scope local. For a local checkout, pass its absolute path to claude plugin marketplace add, or try it without installing:

claude --plugin-dir /absolute/path/to/mycelium-extra

Update both the marketplace and plugin, then start a new session:

claude plugin marketplace update mycelium-extra
claude plugin update mycelium-extra@mycelium-extra

Claude caches plugins by their manifest version. Editing an installed checkout without changing its version does not refresh the cached plugin; use --plugin-dir to test local changes.

OpenCode¶

OpenCode V2 discovers skills from configured directories and loads plugins from configured plugin directories, so point both settings at this checkout. Add to ~/.config/opencode/opencode.json(c):

{
  "$schema": "https://opencode.ai/config.json",
  "plugins": ["/absolute/path/to/mycelium-extra/opencode"],
  "skills": ["/absolute/path/to/mycelium-extra/skills"]
}

Start a new session and run a skill as a command:

/mycelium-extra:grill Plan a paired treatment-response analysis. Read the sample table and existing decisions first.

The plugin registers one /mycelium-extra:<skill> command per skill folder, the same name Claude Code uses; mentioning a skill (@grill) also works. Plugin loading, the adapter’s event and payload shapes, and its tool/prompt/stop behavior were checked against OpenCode 2.0.32, and an end-to-end qualification (a denied run, approval card, approval, receipt, and a state-protection denial) is recorded in the development notes. The plugin is the gate’s host adapter: it runs the shared Python gate and is inert in repositories without .mycelium-extra/gate.json.

Keep each skill folder inside the checkout. Skills that run scripts call ../../hooks/py.sh relative to their own folder, so a copied or symlinked skill folder elsewhere cannot find the hooks. The plugin resolves the checkout from its own location the same way; if you copy the plugin directory, pass { "package": ".../opencode", "options": { "root": "/path/to/mycelium-extra" } }. For a project-local install, add the same two entries to that project’s opencode.json(c); relative paths resolve from OpenCode’s working directory.

To update, pull or replace the checkout and start a new OpenCode session; the plugins and skills entries point at the folder, so there is no cache to refresh. OpenCode needs the same Python 3.9 or later as the other hosts (see Requirements), because the plugin runs hooks/py.sh.

Skill IDs are the folder names (grill, init, and so on). A skills entry is the highest-precedence source in OpenCode, so these generic IDs shadow same-named skills from other sources; see the Skills reference.

OpenCode receipts record host: opencode and the shell tool’s exit code (exit_source: response). A result without one — a background task, or a tool error — records unknown, and verification reports that as a gap; the gate never infers success from a finished command.

Codex¶

Use Codex CLI 0.160.0 or later (codex --version, codex plugin --help):

codex plugin marketplace add mdmanurung/mycelium-extra
codex plugin add mycelium-extra@mycelium-extra

This installs the shared skills under the mycelium-extra namespace. For local development, replace the marketplace source with /absolute/path/to/mycelium-extra. Open /hooks in the Codex CLI, trust every Mycelium Extra hook (five entries on four events: prompt, pre-tool, post-tool for shell and for apply_patch, and stop), fully exit Codex, and start a new task. Then invoke $mycelium-extra:grill <task>. The same skill folders are used by all three hosts.

/hooks is a CLI command. The desktop app does not provide this trust step.

Refresh the marketplace and reinstall the plugin, then start a new session:

codex plugin marketplace upgrade mycelium-extra
codex plugin add mycelium-extra@mycelium-extra

Revisit /hooks after an upgrade: the installed plugin path and its trust record can change. Trust the current hooks and restart before relying on them.

Your first analysis¶

Follow Tier 2: Run with approval: initialize the gate, plan, approve the displayed hash, and run. For reportable work, add Tier 3: Verify reportable work.

Only planning? Start with Tier 1; no init needed.

Requirements¶

The approval gate and helper scripts need Python 3.9 or later, on every host. They run through hooks/py.sh. Skill commands use python3 if it is new enough, else the newest python3.N on PATH; hooks try the newest python3.N first and fall back to python3. On RHEL 8, python3 is 3.6 but python3.11 or python3.12 usually exist. Set MYCELIUM_EXTRA_PYTHON to choose one yourself. A hook registration from before 0.9.76 that still runs python3 directly on an old Python hands the event to py.sh once. With only an older Python left, a repository with gate.json gets the error on every hook and follows on_error; a repository without it stays silent.
Scientific checks need the tools for the files you use: R and R scilintr, Python scilintr, or h5py for H5AD inspection. A missing tool is reported as a gap rather than a successful check. On a cluster, scilintr and an Rscript whose R has scilintr are usually not on PATH; record where they are with gate_init.py --tools (see Verification).
Independent plan review needs a Codex CLI and a connected Biomni MCP in the Claude Code or OpenCode session; from Codex it gives the engineering critique only. Missing reviewers are reported unavailable. Review packets leave the machine only after the user agrees.

Host compatibility¶

Feature	Claude Code	Codex CLI 0.160.0+	OpenCode V2
All skills: planning, data contracts, decision status, scaffolding, handoff, harden, ideas and triage, verify	Supported	Supported	Supported
Independent plan review	Leads Codex + Biomni synthesis	Engineering critique only	Leads Codex + Biomni when both are available
Init, approval gate, pinned inputs, exploration	Supported	Supported with enabled/trusted hooks	Supported (qualified on 2.0.32)
Run receipts and verification	Success/failure hook events provide status	Records receipts; absent exit metadata is a verification gap	Records receipts; exit status from the shell result’s exit code
Gate state protection	Shell commands and file-edit tools	Shell commands and `apply_patch`, including move destinations	`shell`, `edit`, `write`, and `patch` tools

OpenCode V2 runs the planning skills through the skills setting and the approval gate through the plugins setting, both above. The adapter is qualified against OpenCode 2.0.32 (see the development notes for the record). Its receipts and exit-code handling are described in the OpenCode section.

Codex 0.160.0’s post hook supplies the command’s output without an exit code. The gate records unknown; it never infers success from that event or parses command output as an exit status. Missing receipts remain missing. Upgrading does not reconstruct older runs. Standalone skill copies provide no hooks.

The Codex payload contract was checked against its 0.160.0 shell hook implementation and post-tool response implementation.

Troubleshooting¶

If skills are missing, confirm that the plugin is enabled and restart the host. If a hook names a missing versioned cache path, refresh the installation and restart. Do not repair the error by embedding another cache path in a project.

If analysis runs are unexpectedly blocked, inspect the pending plan and approve its displayed hash. If pinned inputs changed, check them and present a revised plan. See Approval gate for exploration and gate settings.

For verification gaps, read the report’s missing evidence or tool rather than re-running the analysis immediately. See Skills.

References¶

The Claude Code manifest reference describes plugin paths and validation. Codex install commands above were checked against codex-cli 0.160.0’s local command help. The OpenCode section follows the OpenCode V2 skills guide, checked on OpenCode 2.0.32.