LLM Plugins

A minion is a harness that wraps an LLM. The plugin system lets you choose which LLM acts as the brain (Primary) and lets the Primary delegate specialised tasks to other LLMs (Children) running in parallel child sessions.

Concepts

Concept	Role
Primary LLM	The minion’s brain. Handles all chat, workflow, and routine execution
Child LLM	Specialist session dispatched from Primary. Multiple can run in parallel
Plugin	Adapter for a specific LLM CLI. Claude / Gemini / Codex are builtin
Dispatch MCP server	Auto-registered MCP server that exposes child LLMs as tools to Primary

Quick start

1. Install and authenticate the LLM CLI

LLM	Install	Auth
Claude Code	`npm i -g @anthropic-ai/claude-code`	`claude login`
Gemini CLI	`npm i -g @google/gemini-cli`	run `gemini`, OAuth in browser
Codex CLI	`npm i -g @openai/codex`	`codex login`

2. Configure on the HQ dashboard

Open the minion detail page → LLM tab. You’ll see all detected plugins with capability badges and authentication status. Tick enabled for plugins you want to use; pick one as primary.

The selection is persisted in ~/minion/llm/config.json on the minion.

3. Dispatch MCP server is registered automatically

When you set a Primary, the minion writes a minion-llm-dispatch entry to that plugin’s MCP config (e.g. ~/.mcp.json for Claude, ~/.gemini/settings.json for Gemini). The Primary can then call dispatch_to_gemini(prompt, opts) or dispatch_to_codex(prompt, opts) to delegate to other LLMs.

Plugin characteristics

Claude Code

Streaming, vision, session resume: ✅
Image generation: ❌
Skills: ~/.claude/skills/, invoked with /skill-name

Gemini CLI

Vision, image generation (with nanobanana extension): ✅
Streaming, session resume: ❌
Skills: ~/.gemini/skills/, auto-injected via system prompt

Known limitations

Headless keychain error: export GEMINI_FORCE_FILE_STORAGE=true to bypass GNOME Keyring requirement on Docker / WSL
Image generation: Default invocation tends to write Python/Pillow code. Install the official nanobanana extension and set NANOBANANA_API_KEY for actual nano-banana usage

Codex CLI

Tool use: ✅
Streaming, session resume, vision: ❌
Skills: ~/.codex/skills/, invoked with /skill-name or $skill-name

Behaviour after switching Primary

Path	Behaviour
Chat	Streamed if the plugin implements `stream()`, otherwise full response after completion
Workflow / Routine	Prompt is written to a temp file, invoked as `<binary> < tmpfile` in tmux (avoids shell quote issues)
Dispatch	Available via MCP tools when Primary supports tool use

Child session lifetime

Child sessions are pooled by (parentSessionId, pluginName) and reused while the parent is alive.
Parallel dispatches to the same plugin allocate independent slots (e.g. generating two images in parallel).
All child sessions are disposed when the parent session ends.

Legacy LLM_COMMAND

If no Primary is set, the minion falls back to the legacy LLM_COMMAND env-var template. This path will be deprecated; new minions should use the plugin system.

Troubleshooting

Chat still uses the old LLM after switching Primary — restart the minion (minion-cli restart).

dispatch_to_* tool not visible — confirm Primary supports MCP, the entry exists in the plugin’s MCP config, and the Primary CLI was restarted to pick up the new MCP settings.

Skill not executing — currently skills must be deployed to the Primary plugin’s skill directory (e.g. ~/.claude/skills/). Cross-plugin skill deployment is on the roadmap.