# potato-dev-inc/puppet-master architecture

> Architecture diagram of the GitHub repository potato-dev-inc/puppet-master, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/potato-dev-inc/puppet-master
- Repository: https://github.com/potato-dev-inc/puppet-master
- Video tour (about a minute): https://gitdiagram.com/potato-dev-inc/puppet-master/video

## Overview

Puppet Master is a control room for delegating work to real coding-agent terminal sessions, not an agent that implements changes itself. An orchestrator submits work through the desktop or MCP surface; the bridge coordinates durable operations and worker panes, and run handling reports completion separately from acceptance-check results. Worktrees isolate parallel changes, while checkpoints support review and undo. The repository also contains distinct issue-intake, CI-fix, mission, and handoff workflows. Edges are limited to README-documented relationships and sampled calls; several feature modules are represented from the source index and tree, not inspected implementation.

Main entry points: [`packages/app/src-tauri/src/agent_runs.rs`](https://github.com/potato-dev-inc/puppet-master/blob/main/packages/app/src-tauri/src/agent_runs.rs) (Agent runs), [`packages/app/src-tauri/src/bridge/router.rs`](https://github.com/potato-dev-inc/puppet-master/blob/main/packages/app/src-tauri/src/bridge/router.rs) (HTTP bridge), [`packages/app/src`](https://github.com/potato-dev-inc/puppet-master/tree/main/packages/app/src) (Desktop app), [`packages/app/src-tauri/src/operations.rs`](https://github.com/potato-dev-inc/puppet-master/blob/main/packages/app/src-tauri/src/operations.rs) (Durable operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surfaces["User surfaces"]
  node_desktop["Desktop app"]
  node_sidebar["Sidebar session"]
  node_mcp["MCP shim<br/>[tool-router.ts]"]
  node_cli["CLI watcher<br/>[launch-worker.ts]"]
  node_mobile["Mobile PWA"]
end

subgraph group_coordination["Bridge and coordination"]
  node_bridge["HTTP bridge<br/>[router.rs]"]
  node_operations[("Durable operations<br/>[operations.rs]")]
  node_questions["Human questions<br/>[mod.rs]"]
  node_audit[("Audit log<br/>[mod.rs]")]
end

subgraph group_workers["Worker execution"]
  node_agent_runs["Agent runs<br/>[agent_runs.rs]"]
  node_adapters["Agent adapters"]
  node_panes["Terminal panes"]
end

subgraph group_workspace["Workspace safety"]
  node_worktrees["Worktree isolation<br/>[mod.rs]"]
  node_checkpoints[("Checkpoints and undo<br/>[engine.rs]")]
  node_acceptance["Acceptance checks<br/>[checks.rs]"]
end

subgraph group_features["Product workflows"]
  node_issue_intake["Issue intake<br/>[engine.rs]"]
  node_ci_fix["CI fixes<br/>[engine.rs]"]
  node_missions["Missions<br/>[engine.rs]"]
  node_keep_going["Keep going<br/>[brief.rs]"]
  node_coord_kernel["Coordination kernel"]
end

node_orchestrator(("Orchestrator"))
node_external_agent["Coding-agent TUI"]

node_orchestrator -->|"submits tools"| node_mcp
node_orchestrator -->|"delegates work"| node_desktop
node_mcp -->|"calls HTTP API"| node_bridge
node_mobile -->|"proxies requests"| node_bridge
node_cli -->|"watches turns"| node_bridge
node_desktop -->|"hosts API"| node_bridge
node_sidebar -->|"runs orchestration"| node_agent_runs
node_sidebar -->|"creates executor"| node_bridge
node_bridge -.->|"routes operations"| node_operations
node_operations -.->|"dispatches worker"| node_agent_runs
node_agent_runs -.->|"selects backend"| node_adapters
node_agent_runs -.->|"drives sessions"| node_panes
node_agent_runs -.->|"isolates work"| node_worktrees
node_agent_runs -.->|"checks outcome"| node_acceptance
node_agent_runs -->|"persists turns"| node_operations
node_agent_runs -.->|"requests input"| node_questions
node_operations -->|"returns result"| node_orchestrator
node_worktrees -.->|"supports undo"| node_checkpoints
node_desktop -.->|"offers workflow"| node_issue_intake
node_desktop -.->|"offers workflow"| node_ci_fix
node_desktop -.->|"offers workflow"| node_missions
node_desktop -.->|"offers handoff"| node_keep_going
node_bridge -->|"exposes coordination"| node_coord_kernel
node_external_agent -->|"edits code"| node_panes

click node_desktop "https://github.com/potato-dev-inc/puppet-master/tree/main/packages/app/src"
click node_sidebar "https://github.com/potato-dev-inc/puppet-master/blob/main/packages/app/src/components/sidebar/useOrchestratorSession.ts"
click node_mcp "https://github.com/potato-dev-inc/puppet-master/blob/main/packages/mcp-server/src/tool-router.ts"
click node_cli "https://github.com/potato-dev-inc/puppet-master/blob/main/packages/cli/src/launch-worker.ts"
click node_bridge "https://github.com/potato-dev-inc/puppet-master/blob/main/packages/app/src-tauri/src/bridge/router.rs"
click node_operations "https://github.com/potato-dev-inc/puppet-master/blob/main/packages/app/src-tauri/src/operations.rs"
click node_questions "https://github.com/potato-dev-inc/puppet-master/blob/main/packages/app/src-tauri/src/questions/mod.rs"
click node_audit "https://github.com/potato-dev-inc/puppet-master/blob/main/packages/app/src-tauri/src/audit/mod.rs"
click node_agent_runs "https://github.com/potato-dev-inc/puppet-master/blob/main/packages/app/src-tauri/src/agent_runs.rs"
click node_adapters "https://github.com/potato-dev-inc/puppet-master/tree/main/packages/app/src-tauri/src/agent_adapters"
click node_panes "https://github.com/potato-dev-inc/puppet-master/tree/main/packages/app/src-tauri/src/pty"
click node_worktrees "https://github.com/potato-dev-inc/puppet-master/blob/main/packages/app/src-tauri/src/worktrees/mod.rs"
click node_checkpoints "https://github.com/potato-dev-inc/puppet-master/blob/main/packages/app/src-tauri/src/checkpoints/engine.rs"
click node_acceptance "https://github.com/potato-dev-inc/puppet-master/blob/main/packages/app/src-tauri/src/agent_runs/checks.rs"
click node_issue_intake "https://github.com/potato-dev-inc/puppet-master/blob/main/packages/app/src-tauri/src/issue_intake/engine.rs"
click node_ci_fix "https://github.com/potato-dev-inc/puppet-master/blob/main/packages/app/src-tauri/src/ci_fix/engine.rs"
click node_missions "https://github.com/potato-dev-inc/puppet-master/blob/main/packages/app/src-tauri/src/missions/engine.rs"
click node_keep_going "https://github.com/potato-dev-inc/puppet-master/blob/main/packages/app/src-tauri/src/handoff/keep_going/brief.rs"
click node_coord_kernel "https://github.com/potato-dev-inc/puppet-master/tree/main/packages/app/src-tauri/src"
click node_mobile "https://github.com/potato-dev-inc/puppet-master/tree/main/packages/app/src"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_desktop,node_sidebar,node_mcp,node_cli,node_mobile,node_external_agent toneBlue
class node_bridge,node_operations,node_questions,node_audit toneAmber
class node_agent_runs,node_adapters,node_panes toneMint
class node_worktrees,node_checkpoints,node_acceptance toneRose
class node_issue_intake,node_ci_fix,node_missions,node_keep_going,node_coord_kernel,node_orchestrator toneIndigo
```

## Components

### User surfaces

- [Desktop app](https://github.com/potato-dev-inc/puppet-master/tree/main/packages/app/src): `packages/app/src`
- [Sidebar session](https://github.com/potato-dev-inc/puppet-master/blob/main/packages/app/src/components/sidebar/useOrchestratorSession.ts): `packages/app/src/components/sidebar/useOrchestratorSession.ts`
- [MCP shim](https://github.com/potato-dev-inc/puppet-master/blob/main/packages/mcp-server/src/tool-router.ts): `packages/mcp-server/src/tool-router.ts`
- [CLI watcher](https://github.com/potato-dev-inc/puppet-master/blob/main/packages/cli/src/launch-worker.ts): `packages/cli/src/launch-worker.ts`
- [Mobile PWA](https://github.com/potato-dev-inc/puppet-master/tree/main/packages/app/src): `packages/app/src`

### Bridge and coordination

- [HTTP bridge](https://github.com/potato-dev-inc/puppet-master/blob/main/packages/app/src-tauri/src/bridge/router.rs): `packages/app/src-tauri/src/bridge/router.rs`
- [Durable operations](https://github.com/potato-dev-inc/puppet-master/blob/main/packages/app/src-tauri/src/operations.rs): `packages/app/src-tauri/src/operations.rs`
- [Human questions](https://github.com/potato-dev-inc/puppet-master/blob/main/packages/app/src-tauri/src/questions/mod.rs): `packages/app/src-tauri/src/questions/mod.rs`
- [Audit log](https://github.com/potato-dev-inc/puppet-master/blob/main/packages/app/src-tauri/src/audit/mod.rs): `packages/app/src-tauri/src/audit/mod.rs`

### Worker execution

- [Agent runs](https://github.com/potato-dev-inc/puppet-master/blob/main/packages/app/src-tauri/src/agent_runs.rs): `packages/app/src-tauri/src/agent_runs.rs`
- [Agent adapters](https://github.com/potato-dev-inc/puppet-master/tree/main/packages/app/src-tauri/src/agent_adapters): `packages/app/src-tauri/src/agent_adapters`
- [Terminal panes](https://github.com/potato-dev-inc/puppet-master/tree/main/packages/app/src-tauri/src/pty): `packages/app/src-tauri/src/pty`

### Workspace safety

- [Worktree isolation](https://github.com/potato-dev-inc/puppet-master/blob/main/packages/app/src-tauri/src/worktrees/mod.rs): `packages/app/src-tauri/src/worktrees/mod.rs`
- [Checkpoints and undo](https://github.com/potato-dev-inc/puppet-master/blob/main/packages/app/src-tauri/src/checkpoints/engine.rs): `packages/app/src-tauri/src/checkpoints/engine.rs`
- [Acceptance checks](https://github.com/potato-dev-inc/puppet-master/blob/main/packages/app/src-tauri/src/agent_runs/checks.rs): `packages/app/src-tauri/src/agent_runs/checks.rs`

### Product workflows

- [Issue intake](https://github.com/potato-dev-inc/puppet-master/blob/main/packages/app/src-tauri/src/issue_intake/engine.rs): `packages/app/src-tauri/src/issue_intake/engine.rs`
- [CI fixes](https://github.com/potato-dev-inc/puppet-master/blob/main/packages/app/src-tauri/src/ci_fix/engine.rs): `packages/app/src-tauri/src/ci_fix/engine.rs`
- [Missions](https://github.com/potato-dev-inc/puppet-master/blob/main/packages/app/src-tauri/src/missions/engine.rs): `packages/app/src-tauri/src/missions/engine.rs`
- [Keep going](https://github.com/potato-dev-inc/puppet-master/blob/main/packages/app/src-tauri/src/handoff/keep_going/brief.rs): `packages/app/src-tauri/src/handoff/keep_going/brief.rs`
- [Coordination kernel](https://github.com/potato-dev-inc/puppet-master/tree/main/packages/app/src-tauri/src): `packages/app/src-tauri/src`

### Other components

- **Orchestrator**
- **Coding-agent TUI**

## Connections

- Orchestrator → MCP shim: submits tools (evidence: `README.md`)
- Orchestrator → Desktop app: delegates work (evidence: `README.md`)
- MCP shim → HTTP bridge: calls HTTP API (evidence: `README.md`)
- Mobile PWA → HTTP bridge: proxies requests (evidence: `README.md`)
- CLI watcher → HTTP bridge: watches turns (evidence: `README.md`)
- Desktop app → HTTP bridge: hosts API (evidence: `README.md`)
- Sidebar session → Agent runs: runs orchestration (evidence: `packages/app/src/components/sidebar/useOrchestratorSession.ts`)
- Sidebar session → HTTP bridge: creates executor (evidence: `packages/app/src/components/sidebar/useOrchestratorSession.ts`)
- HTTP bridge → Durable operations: routes operations
- Durable operations → Agent runs: dispatches worker (evidence: `packages/app/src-tauri/src/agent_runs.rs`)
- Agent runs → Agent adapters: selects backend
- Agent runs → Terminal panes: drives sessions
- Agent runs → Worktree isolation: isolates work
- Agent runs → Acceptance checks: checks outcome (evidence: `packages/app/src-tauri/src/agent_runs.rs`)
- Agent runs → Durable operations: persists turns (evidence: `README.md`)
- Agent runs → Human questions: requests input
- Durable operations → Orchestrator: returns result (evidence: `README.md`)
- Worktree isolation → Checkpoints and undo: supports undo
- Desktop app → Issue intake: offers workflow
- Desktop app → CI fixes: offers workflow
- Desktop app → Missions: offers workflow
- Desktop app → Keep going: offers handoff
- HTTP bridge → Coordination kernel: exposes coordination (evidence: `README.md`)
- Coding-agent TUI → Terminal panes: edits code (evidence: `README.md`)
