How v7ren/puppet-master works
Puppet Master coordinates real agent and shell PTY sessions through a shared local HTTP bridge. Users launch workers and orchestrate them from the desktop sidebar, mobile PWA, or an external MCP host; the bridge exposes the same panes and project-scoped coordination state to each surface. The desktop terminal session renders PTY data, while the Rust runtime manages panes and coordination. The README documents major capabilities beyond the sampled excerpts; those links are shown as documented relationships rather than claims that their source was inspected.
Main entry points: bridge.rs Local HTTP bridge · App.tsx Desktop app · tauri.ts Tauri API client · PuppetMasterSidebar.tsx Orchestrator sidebar
Components 23
User surfaces
- Desktop app
packages/app/src/App.tsx - Mobile PWA
packages/app/src/PwaApp.tsx - Terminal UI
packages/app/src/components/OrchestratorTerminal.tsx - Pane registry hook
packages/app/src/hooks/usePaneRegistry.ts
Orchestration
- Orchestrator sidebar
packages/app/src/components/PuppetMasterSidebar.tsx - LLM chat
packages/app/src/lib/llm.ts - CLI orchestrator panes
packages/app/src/lib/orchestrator-panes.ts
PTY runtime
- Terminal session
packages/app/src/terminal/terminal-session.ts - Tauri API client
packages/app/src/lib/tauri.ts - Rust app commands
packages/app/src-tauri/src/commands.rs - PTY pane registry
packages/app/src-tauri/src/pty/registry.rs - Agent adapters
packages/app/src-tauri/src/agent_adapters
Bridge and clients
- Local HTTP bridge
packages/app/src-tauri/src/bridge.rs - Stdio MCP server
packages/mcp-server/src/index.ts - CLI launcher
packages/cli/src/index.ts - Shared protocol
packages/shared/src/protocol.ts - Mobile pairing
packages/app/src-tauri/src/mobile_pairing.rs
Coordination state
- Coordination event log
packages/app/src-tauri/src/event_log.rs - Tasks, locks, context
packages/app/src-tauri/src/projections.rs
Other components
- Desktop user
- Mobile user
- External MCP host
- Agent and shell processes
Connections 24
- Desktop user → Desktop app: uses
- Mobile user → Mobile PWA: uses
- External MCP host → Stdio MCP server: invokes tools
- Desktop app → Pane registry hook: initializes
packages/app/src/App.tsx - Desktop app → Orchestrator sidebar: renders
packages/app/src/App.tsx - Orchestrator sidebar → LLM chat: calls
packages/app/src/components/PuppetMasterSidebar.tsx - Orchestrator sidebar → CLI orchestrator panes: selects backend
packages/app/src/components/PuppetMasterSidebar.tsx - CLI orchestrator panes → Tauri API client: spawns panes
packages/app/src/lib/orchestrator-panes.ts - Terminal UI → Terminal session: mounts
packages/app/src/components/OrchestratorTerminal.tsx - Terminal session → Tauri API client: resizes PTY
- Pane registry hook → Tauri API client: subscribes events
packages/app/src/hooks/usePaneRegistry.ts - Tauri API client → Rust app commands: invokes commands
- Rust app commands → PTY pane registry: manages panes
- PTY pane registry → Agent adapters: launches agents
- Agent adapters → Agent and shell processes: starts
- Desktop app → Local HTTP bridge: shares local bridge
- Mobile PWA → Local HTTP bridge: mirrors panes
- Stdio MCP server → Local HTTP bridge: forwards tool calls
- CLI launcher → Desktop app: launches
- Local HTTP bridge → Coordination event log: records events
- Local HTTP bridge → Tasks, locks, context: serves coordination
- Tasks, locks, context → Coordination event log: projects events
- Local HTTP bridge → Mobile pairing: supports pairing
- Stdio MCP server → Shared protocol: uses shared types