Orion Butler is a Tauri 2 + Next.js 16 desktop assistant with two parallel agent runtimes, a shared normalized event layer, and a canvas-driven UI. This guide explains every layer with line citations into the live source — and documents the safety gaps honestly.
This guide assumes you know Tauri, Node, and React. If a claim names a file, you can cd /Users/sid/Desktop/orion-butler/ and grep it. Every behavioral claim is marked ✓ VERIFIED (read the file) or ? INFERRED (grep-only) per .claude/rules/workflow/claim-verification.md.

​
The shape of Orion

​
Three things to know before you read any further

Two runtimes, one event stream

Claude SDK runs as a child process. Pi runs in-process. Both normalize to the same camelCase SidecarEvent stream consumed by the frontend XState machine. They are not collapsed into a generic “agent loop.”

Canvas is two tracks, not one

The canvas panel has a mode track for file-backed surfaces (TipTap, PDF, code, spreadsheet) and a widget track for agent-generated JSON specs (@json-render with orionRegistry). Media always takes the widget track.

The trust story is asymmetric

Pi has an OS sandbox. Claude SDK has an OS sandbox. CCW external CLI spawns (Gemini, Codex, Claude CLI, Qwen) — do not. See Trust before assuming uniform isolation.

​
How to read this guide

1

Start with Two Engines

Architecture → Two Engines sets up the mental model. Everything after assumes you’ve read it.
2

Pick your depth path

From there, the architecture pages are independent. Read in any order — they cross-link.
3

Always check Trust

Trust → Known Gaps lists every documented divergence between what the marketing might imply and what the code actually does. It’s not optional reading.
4

Glossary when names confuse

sessionId vs conversationId. Spec vs Mode. internalServers vs BAKED_IN_TRUSTED_SERVERS. The Glossary disambiguates the terms the codebase uses interchangeably.

​
What’s covered

  • Two Engines — Claude SDK vs Pi, routing decision, parity matrix
  • Sessions — Claude SDK session lifecycle vs Pi AgentSession cache
  • Event Layer — SidecarEvent normalization (camelCase IPC contract)
  • Subagents — native Task/Agent vs Pi spawn_subagent (depth guard, model fallback)
  • MCP, Permissions & Sandbox — three permission layers, OAuth singleton, sandbox stack
  • Frontend Surfaces — canvas widget/mode tracks, TipTap, four file-open paths
  • Background, Cron & Multi-CLI — dual-engine cron, autopilot gate, CCW CLI dispatch
Seven known gaps with line-cited evidence and fix paths. Cross-linked from every architecture page.
Glossary of terms the codebase uses with overlapping meanings.

​
Source authority

This guide was written by auditing the live Orion source at /Users/sid/Desktop/orion-butler/ on 2026-05-17. Every claim links to a file:line you can verify. The audit briefs live at .workflow/.team/TC-orion-explainer-v3-2026-05-17/artifacts/ in the Orion repo. When the rules under .claude/rules/ disagree with what the code does, the code wins — this guide flags the drift.