Installing Companion AI Agents
ClaudusBridge ships a one-call installer for the most common AI clients used as execution agents: Claude Code, Codex CLI, Cursor, Windsurf, and the Gemini CLI. Each generated package contains everything the host needs to act as a Claudus-aware peer — agent profile in the host's native format, MCP config snippet, one-line bootstrap script, install README, and shared protocol reference.
The point: instead of writing custom prompts and MCP configs by hand for each AI client, you call one tool, paste the result, and the agent walks in already understanding how to claim provider action requests, run filesystem/shell/build work, mirror progress into the Claudus dashboard, and post results back as evidence.
This guide also covers the documentation pack — the same idea applied to context: a fresh agent reads one package and knows the API, the conventions, and the verification discipline without you having to re-teach it.
The two tools
| Tool | Returns |
|---|---|
claudus_get_companion_package(host) | A rendered install package for one AI client: INSTALL.md, agent profile, MCP config snippet, bootstrap script, protocol reference |
claudus_get_documentation_pack(topic?) | A curated documentation bundle the agent reads to bootstrap itself: API reference, conventions, EYES MANDATORY rule, action contract, memory + checkpoint patterns |
Both are read-only and safe to call in Limited Access.
Supported hosts
claudus_get_companion_package(host: list) enumerates the catalog. As of 0.6.3 four hosts ship as first-class companion packages:
host value | Native profile filename | Bootstrap script |
|---|---|---|
claude-code | claudus-executor.md | bootstrap-claude-code.ps1 |
cursor | claudus-rules.md | bootstrap-cursor.ps1 |
windsurf | claudus-memory.md | bootstrap-windsurf.ps1 |
gemini-cli | claudus-profile.md | bootstrap-gemini-cli.ps1 |
Aliases the tool accepts (resolved to the canonical host name above): claude / claude_code / claudecode → claude-code; gemini / gemini_cli / geminicli → gemini-cli.
Run claudus_get_companion_package with host: "claude-code" (etc.) and paste the result into chat with the user. The agent's own client takes care of installation.
Codex CLI has its own runtime package generated separately to Saved/ClaudusBridge/CodexAgentRuntime/ (see claudus_get_documentation_pack(topic: codex_agent_runtime) for details). Claude Desktop is supported through standard MCP config without a dedicated companion package — point its MCP settings at http://localhost:3000/mcp (with mcp-remote if the host needs stdio).
Install flow
Every package follows the same three-step shape so the user experience is identical regardless of which host they want to add:
1. Bootstrap script ← copies files into the host's config directory
2. One-line MCP add command ← registers ClaudusBridge as an MCP server
3. Verification step ← agent runs claudus_cognitive_state to confirm
1. Bootstrap script
A short shell or PowerShell script that:
- Creates the host's expected agent config directory if it doesn't exist
- Writes the agent profile in the host's native format
- Writes the shared protocol reference next to it
The script lives inside the package; the user (or the providing agent) runs it once.
2. MCP add command
For each host, the exact one-liner that registers ClaudusBridge as an MCP server. The plugin reads the live port from its /health endpoint so the command always points to the right URL.
3. Verification
After installation, the agent calls claudus_cognitive_state from its own client. A successful response confirms the MCP connection AND that the agent's session shows up in the Claudus dashboard. The user sees the new agent appear in the shared transcript with its session name.
What the agent profile contains
Each profile is generated from a single source so the behaviour is consistent across hosts. The profile teaches the agent:
- Identity — name, role (execution agent), session naming convention
- Mandatory first actions — subscribe to events, drain the action queue, mirror progress with
claudus_agent_note - Action contract — how to claim
[Claudus Action Request]blocks viaclaudus_get_action_requests, run the requested OS / filesystem / shell / build / browser / source-control work with its own native tools, and post evidence viaclaudus_provide_action_result - Evidence discipline — the agent must not claim success based on its own status messages; only
claudus_provide_action_resultlands as canonical evidence - EYES MANDATORY — for any work with visual implications, use the streaming captures or a watcher sub-agent; never program blind
- Memory + checkpoint patterns — when to write to memory, when to call
claudus_checkpoint_workflow, how to read the auto-observation journal - Access mode awareness — the agent must call
claudus_set_access_modebefore mutating work if the current mode requires it, with audit fields
The same content covers every host because the rules don't change — only the file location and prompt-format wrapper differ per host.
Documentation pack — the "agent reads this and is ready"
claudus_get_documentation_pack is the read-side complement to the companion package. When a fresh agent connects (whether installed from a companion package or already configured manually), it can call this tool and receive a curated, tagged set of documentation chunks ready to be consumed by an LLM context:
cb call claudus_get_documentation_pack '{"topic": "all"}'
# or call with no arguments — returns the full pack
cb call claudus_get_documentation_pack
Supported topics
The tool dispatches on the topic string. Pass any of the canonical topics below for a filtered pack, or all (the default) for the complete bundle:
| Topic | Returns |
|---|---|
all (alias: docs, documentation) | Full pack |
gallery (aliases: gallery_images, image_generation, images) | Image-gallery + native vision |
native_tools (aliases: tools, mcp, viewport, vision) | Native MCP tool execution + action contract |
multi_agent_workflow (aliases: multi_agent, maw, workflow, workflows) | Durable workflow records, templates, timeline |
project_context (aliases: project_info, engine_context, engine, plugins) | Asset registry, naming patterns, plugin list |
native_unreal_editing (aliases: blueprints, materials, widgets, hud, umg, niagara, assets) | Editing the Unreal asset graph |
agents (aliases: native_agents, claudus_agents) | The 16 native agent manifests |
codex_agent_runtime (aliases: codex_runtime, codex_agent, claude_code, cursor, windsurf, external_agents) | External execution-agent setup |
skills (aliases: skill_creator, claudus_skills) | The native skill manifests |
Plus a fuzzy substring match: any topic string that appears in a source key or title (such as ai_skill, knowledge_base, execution_agent, documentation_agent, controls, watcher, cognition_schema, memory) will resolve to the closest matching source documents.
The plugin also writes a portable agent prompt to <ProjectDir>/Saved/ClaudusBridge/claudus_documentation_agent.prompt.md — a system prompt designed to be the foundation of a dedicated documentation-specialist sub-agent. Spawn that sub-agent when you want a specialist that teaches other agents how to use ClaudusBridge correctly.
The token-efficient multi-agent workflow
Companion packages + the documentation pack + the rest of the 0.6.x machinery compose into a workflow specifically tuned for minimum token spend across multi-agent collaborations. The pieces:
- One reasoning provider, many execution agents. The active provider (typically Claude Opus 4.7 1M for planning) handles strategy. Companion-installed execution agents (Claude Code for filesystem + shell, Codex CLI for shell + browser, Cursor / Windsurf for IDE-driven edits) handle the real work without ever loading the provider's full context.
- Documentation pack instead of in-chat re-teaching. Each new agent calls
claudus_get_documentation_packonce on connect. The provider doesn't have to spend tokens re-explaining the API, the action contract, or the verification rules. - Mixed-tier delegation for sub-tasks. When the lead provider needs a routine sub-task (summarisation, classification, deterministic rewrites), it routes through
claudus_delegate_to_modelwith a tier hint (routine→ Haiku 4.5,balanced→ Sonnet 4.6,flash→ Gemini 2.5 Flash,gpt→ GPT-5.5). Typically 5-10× cheaper and 2-3× faster than reasoning on Opus. - Speculative pre-fetch. When a successful native tool returns, ClaudusBridge runs up to 3 likely follow-up tool calls inline within a 500 ms budget and attaches them to the response under
speculative_context. The provider reads the bonus data and skips entire round-trips. Zero inference cost. - Auto-continuation batching. When several action results return inside ~500 ms, ClaudusBridge fires only one provider continuation instead of one per result. Subsequent results within the debounce window append to the chat-log and the provider's already-in-flight inference picks them up via context. For a cluster of 3 results that's roughly 2 saved provider inferences (~3-6 s and several thousand tokens).
- Cost telemetry that proves the savings.
claudus_cost_summaryrolls upTotalInputTokens+TotalOutputTokensthrough a public-list rate card and returns total USD.claudus_speculation_statsandclaudus_continuation_statsreport projected saved inference ms with USD estimates.
Concretely: a multi-agent workflow that used to cost N provider inferences now spends 1 plan turn + speculative pre-fetch + batched continuations + delegated sub-tasks, and the bulk of the real work runs on the execution agents' own contexts without the provider re-reading it.
Day-1 onboarding
For new sessions, two cheap reads usually cover what the agent needs to know about the project:
cb call claudus_get_project_intelligence
cb call claudus_recall_observations '{"since_hours": 168, "limit": 50}'
That's the asset baseline + the recent activity journal. A few hundred tokens total. The next agent walks in knowing the project shape and the recent workflow history without re-scanning the asset registry call by call.
Smart-start for repeatable patterns
When the user describes intent in free text, claudus_smart_start(intent) scores it against the workflow template catalog and instantiates the right workflow in one call:
cb call claudus_smart_start '{"intent": "I want to update the holographic UI material to match the new emissive curve"}'
If the keyword match is strong, the workflow is created and you're done. If the match is weak or ambiguous, the classification escalates to Haiku 4.5 (via the mixed-tier path) and reports escalated_to_haiku: true so operators can see exactly how the router decided. Either way: one call from intent to a live multi-step workflow with role-pinned execution agents, not a back-and-forth chat negotiation.
Putting it together: a typical multi-agent run
1. User opens Unreal, connects from Claude Code (companion package installed earlier).
2. Claude Code calls claudus_get_documentation_pack on its first turn.
3. User types intent into the Claudus dashboard:
"Refactor M_Holo to use the new emissive curve, then verify visually."
4. Provider (Claude Opus 4.7 1M, active in Claudus) calls:
claudus_smart_start → instantiates material_pipeline workflow
claudus_checkpoint_workflow → snapshots /Game/Materials/Holographic/
5. Provider emits [Claudus Action Request] for filesystem-level inspection.
Claude Code claims it via claudus_get_action_requests, runs the work
with its own Read/Grep tools, posts back with claudus_provide_action_result.
6. Provider delegates "summarise the three changes Claude Code made" to
Haiku 4.5 via claudus_delegate_to_model (tier: routine).
← much cheaper than reasoning on Opus for a summary.
7. Provider runs recompile_material via the Claudus Native Tool Executor.
Speculative pre-fetch attaches open_asset_editor(M_Holo) to the result.
← provider doesn't need to call open_asset_editor itself.
8. Provider asks the visual watcher sub-agent to verify (channel:
verification.needed). Watcher returns watcher.observation with the
plain-text visual report.
9. Provider transitions the workflow to completed via
claudus_update_multi_agent_workflow.
← auto-observation fires (workflow_completed + workflow_id + lead).
10. claudus_cost_summary at the end shows: 4 provider inferences (one for
the plan, one each for the 3 batched continuations), 2 Haiku
delegations, 1 watcher verify, 1 native-vision describe.
Estimated USD: a small single-digit-cents figure for a real
multi-step UE refactor.
The provider stayed at the planning level. Execution agents did the heavy lifting in their own contexts. Telemetry tools prove the spend.
Where to go next
- Agent Bootstrap Protocol — If you'd rather skip the companion-package install and just connect manually, this is the wire-level recipe (health, initialize, handshake, provider attach, stale-runtime recovery, work loop)
- Native Editor Conversation — How the providers and companion-installed agents share the dashboard transcript
- Multi-Agent Workflows — Durable workflow records that companion agents collaborate on
- Cognition Tier overview — Where each of the telemetry + projection tools (cost summary, speculation stats, continuation stats) lives
- Memory System and Auto-Observations — The two layers of persistent context companion agents read and write