import{c as a,Q as e,j as n,m as i}from"./chunks/framework.BPKcPtvA.js";const k=JSON.parse('{"title":"Reference Architecture: Production Multi-Agent Stack","description":"","frontmatter":{},"headers":[],"relativePath":"modules/reference-stack.md","filePath":"modules/reference-stack.md","lastUpdated":1780488246000}'),t={name:"modules/reference-stack.md"};function l(o,s,p,r,d,h){return e(),n("div",null,[...s[0]||(s[0]=[i(`<h1 id="reference-architecture-production-multi-agent-stack" tabindex="-1">Reference Architecture: Production Multi-Agent Stack <a class="header-anchor" href="#reference-architecture-production-multi-agent-stack" aria-label="Permalink to &quot;Reference Architecture: Production Multi-Agent Stack&quot;">​</a></h1><p>This document documents a real production multi-agent deployment. Use it as a reference for Module 5 (Production Patterns) and Module 4 (Multi-Agent Orchestration).</p><h2 id="architecture-overview" tabindex="-1">Architecture Overview <a class="header-anchor" href="#architecture-overview" aria-label="Permalink to &quot;Architecture Overview&quot;">​</a></h2><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>┌──────────────────────────────────────────────────────────────────┐</span></span>
<span class="line"><span>│                    agent-mux (Tauri UI)                           │</span></span>
<span class="line"><span>│              Meta-agent control plane + dashboard                 │</span></span>
<span class="line"><span>│         Spawns, monitors, kills agents. Human interface.          │</span></span>
<span class="line"><span>└─────────────────────────┬────────────────────────────────────────┘</span></span>
<span class="line"><span>                          │ orchestrates via sidecar</span></span>
<span class="line"><span>                          ▼</span></span>
<span class="line"><span>┌──────────────────────────────────────────────────────────────────┐</span></span>
<span class="line"><span>│                    mprocs (process monitor)                       │</span></span>
<span class="line"><span>│                    mprocs -c ~/mprocs-teams.yaml                  │</span></span>
<span class="line"><span>│          Launches and supervises all agent processes              │</span></span>
<span class="line"><span>├──────────────┬──────────────┬──────────────┬─────────────────────┤</span></span>
<span class="line"><span>│ claude-lead  │   gemini     │   opencode   │  sidecar            │</span></span>
<span class="line"><span>│ (primary)    │  (backup)    │  (OSS alt)   │  (agent-mux proxy)  │</span></span>
<span class="line"><span>└──────────────┴──────────────┴──────────────┴─────────────────────┘</span></span>
<span class="line"><span>                          │ each agent runs inside</span></span>
<span class="line"><span>                          ▼</span></span>
<span class="line"><span>┌──────────────────────────────────────────────────────────────────┐</span></span>
<span class="line"><span>│                    psmux (tmux session manager)                   │</span></span>
<span class="line"><span>│              tmux.exe at ~/.cargo/bin/tmux                        │</span></span>
<span class="line"><span>│          Claude Code --teammate-mode tmux                         │</span></span>
<span class="line"><span>├─────────┬─────────┬─────────┬─────────┬─────────┬───────────────┤</span></span>
<span class="line"><span>│  pane 1 │  pane 2 │  pane 3 │  pane 4 │  pane 5 │  ...          │</span></span>
<span class="line"><span>│  (lead) │ (worker)│(review) │(verify) │ (sidecar)│               │</span></span>
<span class="line"><span>└─────────┴─────────┴─────────┴─────────┴─────────┴───────────────┘</span></span>
<span class="line"><span>                          │ each task isolated by</span></span>
<span class="line"><span>                          ▼</span></span>
<span class="line"><span>┌──────────────────────────────────────────────────────────────────┐</span></span>
<span class="line"><span>│                    dmux (git worktree isolation)                  │</span></span>
<span class="line"><span>│           Each agent task gets its own isolated worktree          │</span></span>
<span class="line"><span>│         dmux runs inside a tmux session with agent-teams          │</span></span>
<span class="line"><span>└──────────────────────────────────────────────────────────────────┘</span></span></code></pre></div><h2 id="layer-by-layer-breakdown" tabindex="-1">Layer-by-Layer Breakdown <a class="header-anchor" href="#layer-by-layer-breakdown" aria-label="Permalink to &quot;Layer-by-Layer Breakdown&quot;">​</a></h2><h3 id="layer-1-meta-control-plane-agent-mux" tabindex="-1">Layer 1: Meta-Control Plane (agent-mux) <a class="header-anchor" href="#layer-1-meta-control-plane-agent-mux" aria-label="Permalink to &quot;Layer 1: Meta-Control Plane (agent-mux)&quot;">​</a></h3><ul><li><strong>What</strong>: Tauri desktop application</li><li><strong>Function</strong>: UI for spawning, monitoring, and killing agents</li><li><strong>Communication</strong>: Sidecar process (RPC over IPC)</li><li><strong>Key features</strong>: <ul><li>Start/stop individual agents</li><li>View live output from all agents</li><li>Cost tracking per session</li><li>Session history and replay</li></ul></li></ul><h3 id="layer-2-process-orchestrator-mprocs" tabindex="-1">Layer 2: Process Orchestrator (mprocs) <a class="header-anchor" href="#layer-2-process-orchestrator-mprocs" aria-label="Permalink to &quot;Layer 2: Process Orchestrator (mprocs)&quot;">​</a></h3><ul><li><strong>Config</strong>: <code>~/mprocs-teams.yaml</code></li><li><strong>Function</strong>: Launches all agent processes, supervises them</li><li><strong>Processes</strong>: <ul><li><code>claude-lead</code>: Claude Code (primary agent)</li><li><code>gemini</code>: Gemini CLI (backup/alternative model)</li><li><code>opencode</code>: OpenCode CLI (open-source alternative)</li><li><code>qwen</code>: Qwen model (specialist/fast tasks)</li><li><code>sidecar</code>: agent-mux IPC proxy</li><li><code>agent-mux</code>: Tauri UI process</li></ul></li></ul><h3 id="layer-3-session-management-psmux" tabindex="-1">Layer 3: Session Management (psmux) <a class="header-anchor" href="#layer-3-session-management-psmux" aria-label="Permalink to &quot;Layer 3: Session Management (psmux)&quot;">​</a></h3><ul><li><strong>Binary</strong>: <code>tmux.exe</code> at <code>~/.cargo/bin/tmux</code></li><li><strong>Function</strong>: Terminal multiplexer for agent sessions</li><li><strong>Key feature</strong>: <code>Claude Code --teammate-mode tmux</code> — Claude&#39;s native multi-agent split-pane mode</li><li><strong>Team spawns</strong>: Each <code>--teammate-mode</code> invocation creates split panes, each running a separate Claude session</li></ul><h3 id="layer-4-work-isolation-dmux" tabindex="-1">Layer 4: Work Isolation (dmux) <a class="header-anchor" href="#layer-4-work-isolation-dmux" aria-label="Permalink to &quot;Layer 4: Work Isolation (dmux)&quot;">​</a></h3><ul><li><strong>Function</strong>: Git worktree isolation per task</li><li><strong>Requirement</strong>: Must run inside a tmux session (start agent-teams first, then dmux)</li><li><strong>Benefit</strong>: Each task gets an isolated filesystem. No cross-task contamination. Easy rollback (delete worktree).</li></ul><h2 id="tool-specific-configurations" tabindex="-1">Tool-Specific Configurations <a class="header-anchor" href="#tool-specific-configurations" aria-label="Permalink to &quot;Tool-Specific Configurations&quot;">​</a></h2><h3 id="claude-code" tabindex="-1">Claude Code <a class="header-anchor" href="#claude-code" aria-label="Permalink to &quot;Claude Code&quot;">​</a></h3><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Launch with teammate mode (multi-agent)</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">claude</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --teammate-mode</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> tmux</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Headless mode (for CI/CD)</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">claude</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -p</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;prompt&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --allowedTools</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;Read Write Edit Bash&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --print</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># With custom hooks</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">claude</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --hooks</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .claude/hooks/</span></span></code></pre></div><h3 id="pi-coding-agent" tabindex="-1">Pi Coding Agent <a class="header-anchor" href="#pi-coding-agent" aria-label="Permalink to &quot;Pi Coding Agent&quot;">​</a></h3><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Launch with extensions</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pi</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -e</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> extensions/damage-control.ts</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">   -e</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> extensions/tilldone.ts</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">   -e</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> extensions/minimal.ts</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># RPC mode (programmatic control)</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pi</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --mode</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> rpc</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># With custom skills</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pi</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --skills-dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .pi/skills/</span></span></code></pre></div><h3 id="opencode" tabindex="-1">OpenCode <a class="header-anchor" href="#opencode" aria-label="Permalink to &quot;OpenCode&quot;">​</a></h3><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Using Go model (via proxy)</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">opencode</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --model</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> opencode-go/deepseek-v4-flash</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Headless execution</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">opencode</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;prompt&quot;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># With config from shared ~/.grok/config.toml</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">opencode</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --config</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ~/.grok/config.toml</span></span></code></pre></div><h3 id="openclaw" tabindex="-1">OpenClaw <a class="header-anchor" href="#openclaw" aria-label="Permalink to &quot;OpenClaw&quot;">​</a></h3><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Always-on employee mode</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">claw</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> start</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --daemon</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># One-shot task execution</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">claw</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> do</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;task description&quot;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Heartbeat schedule</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">claw</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> schedule</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --cron</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;0 */6 * * *&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --task</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;daily-report&quot;</span></span></code></pre></div><h2 id="cost-analysis" tabindex="-1">Cost Analysis <a class="header-anchor" href="#cost-analysis" aria-label="Permalink to &quot;Cost Analysis&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Tool</th><th>Best For</th><th>Est. Cost/Task</th><th>Autonomy Level</th></tr></thead><tbody><tr><td>Claude Code</td><td>Complex multi-step tasks</td><td>$0.05-$0.30</td><td>High (with hooks)</td></tr><tr><td>Pi Agent</td><td>Custom workflows, safety-critical</td><td>$0.02-$0.15</td><td>Very high (extensible)</td></tr><tr><td>OpenCode</td><td>OSS-compatible, budget tasks</td><td>$0.01-$0.05</td><td>Medium</td></tr><tr><td>Gemini</td><td>High-volume, simple tasks</td><td>$0.002-$0.01</td><td>Low</td></tr><tr><td>OpenClaw</td><td>Scheduled, always-on tasks</td><td>$0.01-$0.10</td><td>Autonomous</td></tr></tbody></table><h2 id="key-production-patterns" tabindex="-1">Key Production Patterns <a class="header-anchor" href="#key-production-patterns" aria-label="Permalink to &quot;Key Production Patterns&quot;">​</a></h2><ol><li><p><strong>Model heterogeneity</strong>: Different models for different roles. Claude for complex reasoning, Gemini for fast/cheap tasks, Qwen as specialist.</p></li><li><p><strong>Tool heterogeneity</strong>: Not one agent CLI, but five. Each has different strengths. The stack uses each where it excels.</p></li><li><p><strong>Defense in depth</strong>: psmux isolates sessions. dmux isolates files. damage-control restricts commands. mprocs restarts failed processes.</p></li><li><p><strong>Observability</strong>: agent-mux shows live status. mprocs logs output. Session history enables replay debugging.</p></li><li><p><strong>No single point of failure</strong>: If Claude Code fails, Pi or OpenCode can take over. The mprocs supervisor restarts crashed processes.</p></li></ol><h2 id="what-this-stack-proves" tabindex="-1">What This Stack Proves <a class="header-anchor" href="#what-this-stack-proves" aria-label="Permalink to &quot;What This Stack Proves&quot;">​</a></h2><p>This architecture demonstrates every concept taught in Modules 1-7:</p><table tabindex="0"><thead><tr><th>Concept</th><th>Where It Appears</th></tr></thead><tbody><tr><td>Agent loop</td><td>Every tool follows think→act→observe→repeat</td></tr><tr><td>Tool design</td><td>Each tool provides different tools (read, write, bash, search)</td></tr><tr><td>Security</td><td>damage-control, psmux isolation, dmux isolation</td></tr><tr><td>Multi-agent</td><td>teammate-mode, mprocs launching 5 agents</td></tr><tr><td>Production</td><td>mprocs supervision, cost tracking, worktree isolation</td></tr><tr><td>Economics</td><td>Cascade routing across 5 tools by task type</td></tr><tr><td>Advanced</td><td>agent-mux as meta-agent controlling other agents</td></tr></tbody></table>`,29)])])}const u=a(t,[["render",l]]);export{k as __pageData,u as default};
