Installation

Step 1 — install the binary

```bash

2. Install the UserPromptSubmit plugin

From inside Claude Code, add the muninn marketplace once, then install the plugin:

/plugin marketplace add colliery-io/muninn
/plugin install muninn-cc

Claude Code clones the repo to its plugin cache and loads the hook from there. To pull plugin updates later, run /plugin marketplace update muninn inside CC.

Hacking on the plugin source? If you're developing against a local checkout rather than the GitHub copy, load it directly with --plugin-dir at session start:

claude --plugin-dir /absolute/path/to/muninn/plugins/muninn-cc

/reload-plugins picks up plugin file edits without a full restart.

The plugin's UserPromptSubmit hook fires once per user turn: a cheap router model decides whether the prompt needs exploration; if it does, muninn drives its recursive exploration loop on the configured local/cheap backend and injects the result as additionalContext, framed as the answer for Claude to deliver. Failure mode is always silent passthrough — the hook never blocks the user's turn. See plugins/muninn-cc/README.md.

.muninn/config.toml

[ollama] api_key = "..." ```

You can also export OLLAMA_API_KEY in your shell — but be aware: when Claude Code launches muninn's hook + MCP subprocesses, they may not inherit your interactive shell's environment (especially if you started CC from a desktop launcher rather than a terminal). Putting the key in .muninn/config.toml is the most reliable path. The same applies to GROQ_API_KEY / ANTHROPIC_API_KEY.

For Groq, Anthropic direct, or a local Ollama daemon, see Configuration.

That's the binary side done. Now wire it into your agent.

Optional — index the code graph

query_graph returns empty results against a fresh .muninn/graph.db. To populate it for this repo:

muninn index

The search_code MCP tool works without the graph (it walks the filesystem directly). Indexing only unlocks query_graph.

Configuration

Muninn stores data in .muninn/ within your project:

.muninn/
├── config.toml         # tiered config (provider/model)
├── graph.db            # code graph
├── docs.db             # indexed library docs
└── sessions/           # per-session logs and traces

Tiered config

[default] is the baseline. [router] and [rlm] each accept optional provider / model overrides; unset fields inherit from [default]. The minimal config is empty — defaults handle the rest.

Worked example — tier a cheap router with a stronger but still cheap RLM, both within the same provider:

```toml [default] provider = "ollama" model = "gemma4:31b"

[router]

Optional: bound network retries. Default 3 × 500ms backoff. Set to 0