# o8 — full documentation > The complete o8 documentation corpus, concatenated for agent context. o8 is a macOS control room for autonomous engineering: one orchestrator dispatches a fleet of coding agents, a governance layer reviews every diff, and nothing risky merges without the operator's sign-off. --- # What is o8? > o8 is a control room for autonomous engineering — one orchestrator dispatches a fleet of coding agents, a governance layer reviews every diff, and nothing risky merges without your sign-off. _stable · updated 2026-06-25_ o8 is a macOS app for **running a team of coding agents** the way a staff engineer runs a team of people: you delegate the work, a governance layer reviews it, and you approve what ships. It's the layer **underneath** the agent IDEs — not another place to type code, but the room you run them from. ## The shape of it Most tools put one agent in your editor. o8 puts an **orchestrator** in charge of many: - The **orchestrator** plans the work and dispatches it to a fleet of coding agents — Claude, Codex, Gemini, and others — each in its own isolated git worktree. - A **governance layer** reviews every diff before it can land: risk is classified by what the change touches, and the dangerous changes get a second, independent review. - **Nothing merges unreviewed — and nothing risky merges without your sign-off.** Autonomy stays comfortable because the gate is the product, not an afterthought. Every diff is reviewed before it can merge; a standard diff clears on a passing review, while high-risk work is escalated to a second, independent reviewer and held for you. ## The surfaces o8 is one governed surface seen from several angles: | Surface | What it's for | |---|---| | **Control Room** | The IDE side — sessions, the orchestrator chat, and your `o8.md` workspace. | | **Agents & Dispatch** | Hand real work to the fleet: missions, isolated worktrees, review, approval. | | **The Brain** | A queryable map of how your project actually works — organizational memory. | | **Canvas** | A spatial workspace for arranging work and media. | | **Symon** | The voice operator — talk to o8, dictate, and drive it hands-free. | ## What it costs The whole app is **free with your own keys** — bring Claude or Codex and run it. There's no crippled tier and no trial. A paid **Founding Operator** edition funds the build and switches on a managed layer (we run the fast inference for you) for those who want it instant and hands-off — but every capability is in the free app. > o8 is the orchestration layer that handles the boring production work end to end, so you can step back from the tools and run the room. --- # Getting started > Install o8, sign in, bring your keys, and run your first dispatch. _stable · updated 2026-06-25_ Five minutes from download to your first reviewed change. o8 is macOS 14+; the current build is Intel and runs on Apple Silicon via Rosetta. ## 1. Download Grab o8 from [o8.run/download](/download). You'll create a free account (GitHub or Google) on the way — that account is what your setup, memory, and any founder perks bind to, so they follow you across machines. ## 2. Install Open the `.dmg`, drag o8 to Applications, then **right-click → Open** the first time so macOS lets it run. After that it auto-updates. ## 3. Sign in Launch o8 and sign in with the same account you used to download. That's it — there's no license key to paste; your account carries everything. ## 4. Bring your keys o8 runs on **your** model access. Add your Claude or Codex credentials in Settings, and the orchestrator and its fleet run on them. (Founding Operators can skip this — the managed layer runs the fast path for you.) ## 5. Run your first dispatch Point o8 at a repository, describe a task to the orchestrator, and let it work: 1. The orchestrator plans the task and **dispatches** it to a coding agent in an isolated worktree. 2. When the agent finishes, the **governance layer reviews** the diff — and routes risky changes to a second, blind reviewer. 3. The change surfaces for your **approval**. Nothing merges until you say so. That loop — dispatch → review → approve — is the whole rhythm of o8. Everything else is a richer way to run it. ## Next - **[What is o8?](/docs/what-is-o8)** — the one-page picture. - **Agents & Dispatch** — the worktree model, the escalation ladder, and how review actually decides. --- # Concepts > The eight primitives o8 is built on — runtime, agent, session, packet, lane, mission, review, approval — and how they fit together. _stable · updated 2026-06-25_ o8 is built on eight primitives. They have different lifetimes and different jobs, so it's worth holding them apart — these names show up everywhere in the app. ## The mental model You describe an outcome. The **orchestrator** breaks it into **packets** — units of planned work — and groups the active batch into a **mission**, ordered as a dependency graph so independent packets run at the same time. To execute a packet, o8 opens a **lane**: a durable record binding the packet to an isolated git **worktree** and to a **session** running inside a **runtime** (the adapter for a CLI coding tool). The live process doing the work is an **agent**. When its diff is ready, **review** renders a verdict, and **approval** gates the actions that need a permission check. Plan and execution stay separate on purpose: a failed attempt is retried as a fresh lane without losing the plan. ## The eight primitives | Primitive | What it is | |---|---| | **Runtime** | The adapter for a CLI coding agent — a normalized interface the control plane talks to, not a running process. | | **Agent** | A live runtime process: one CLI invocation, in one isolated worktree. | | **Session** | A conversation thread inside a runtime. One runtime can carry many sessions. | | **Packet** | The orchestrator's unit of *planned* work — a brief plus its result, with a runtime target and a dependency list. | | **Lane** | The durable *execution* record — the row binding a session to a worktree to a packet, with a lifecycle from idle to merged. | | **Mission** | The current batch of packets in flight toward one goal. There is exactly one active mission at a time. | | **Review** | The diff verdict: accept, reject, or request changes. Per packet. | | **Approval** | A permission gate on a tool call or lane action. Per call — not the same as review. | ## Four distinctions worth keeping - **Runtime ≠ agent ≠ session** — the adapter, the process, and the thread inside the process. - **Packet ≠ lane** — the *plan* versus the *execution*. One packet can spawn several lanes; each retry is a new lane. - **Mission ≠ packet** — a mission is the active batch; a packet is one item in it. - **Review ≠ approval** — a per-packet diff verdict versus a per-call permission gate. --- # Control Room > The IDE-shaped pane you run the fleet from — the orchestrator chat, the panels, sessions, and the o8.md workspace spec. _stable · updated 2026-06-25_ The Control Room is the pane you run the fleet from. It's shaped like an IDE, but you don't drive it by typing code — you drive it by **talking to an orchestrator** that plans the work, hands it to agents, watches them, and brings the results back for your review. Think air-traffic control for coding agents: you say what you want built; o8 decides how, who builds what, in what order, and whether it's safe to ship. Three things make it not a code editor: - **You issue intent, not keystrokes.** The main act is a sentence to the orchestrator, not an edit to a buffer. - **Work runs in the background, in parallel** — several agents in isolated worktrees at once. You watch status; you don't babysit one file. - **Nothing the agents do is trusted blindly.** A governance layer sits between their output and your main branch, and review is a first-class surface (see [Review & approval](/docs/review-and-approval)). ## What's on screen | Region | What it's for | |---|---| | **Left column** | Your repos, with the live agent and packet activity grouped under each. Select a repo to focus it. | | **Center workspace** | Splittable tiles, each a tab. The **Orchestrator** tab is where you work; a **Terminal** is always available; a single-runtime **chat** opens when that agent's CLI is installed. | | **Right rail** | The fleet's status and tools — workspace, branches and PRs, activity (where governance events land), the **spec** (your o8.md), and **Review** with **Ask the Brain** beside it. | | **Status bar** | Settings, repo and branch pickers, running-process views, the supervisor inbox, and the merge controls. | ## The orchestrator chat This is how you drive everything. Open an **Orchestrator** tab and it starts compose-first — *"What should we build?"* — with editable context chips (project, worktree, branch) until your first message lands. What you say becomes work. The orchestrator **plans** (breaks your intent into packets with an order), **dispatches** them to agents in isolated worktrees, **watches** progress, and **reports** back inline — turn summaries, action cards, and live activity as agents run, including when a worker consulted the Brain. You steer by replying in the same thread; you rarely touch the agents directly. Your main throttle on autonomy is the permission mode. The chat runs in **full access** by default. Switch it to **plan** and a read-only banner appears: the orchestrator proposes and plans but won't make changes until you switch back. Plan first when you want to see the shape of the work before anything runs. ## Sessions Your conversations are **durable and resumable**. A **session** is a conversation thread inside a runtime — leave, come back, reopen a thread from the left column, and continue where it left off. Sessions sit inside the primitive chain from [Concepts](/docs/concepts): a *runtime* (the agent adapter) carries many *sessions*, and a *lane* binds a session to a worktree and a packet for one piece of execution. ## o8.md — the workspace spec `o8.md` is a plain-markdown file at the root of your repo: your working document of what should be built. It's the shared source of intent between you and the fleet — and the rule is simple: **you author it, agents annotate it, nobody overwrites it.** Agents leave threaded comments and non-destructive suggestions on the spec rather than rewriting it; you resolve the threads. In the app, the **spec** tab is the review surface for o8.md — threads, suggestions, and resolve state, with "Ask the Brain" beside it. From inside a worktree, an agent works the spec through the `o8` CLI — never by clobbering the file: | Command | What it does | |---|---| | `o8 spec read` | the raw o8.md content | | `o8 spec index` | the structured review threads + a summary | | `o8 spec pending` | only the unresolved threads | | `o8 spec comment` | leave a comment, optionally anchored to a snippet | | `o8 spec suggest` | propose a non-destructive add / delete / substitute edit | | `o8 spec reply` · `o8 spec resolve` | reply to or close a thread | The flow: **you write the spec, the fleet reads and annotates it, you resolve the threads.** The spec stays a reviewable source of intent, not a file agents rewrite. --- # Dispatching work > How a task becomes a merged change — missions, isolated worktrees, the runtimes, and where you sign off. _stable · updated 2026-06-25_ The whole job of o8 is to turn a described outcome into a reviewed, merged change — without you babysitting each step. Here's the loop. ## From task to merge 1. **Create** — the orchestrator reads the task (say, a set of GitHub issues) and opens a **mission**. 2. **Plan into a graph** — it breaks the work into **packets** and orders them as a dependency graph, so independent packets can run at once. 3. **Dispatch** — the scheduler launches the first wave: every packet with no unmet dependencies, in parallel. 4. **Isolate** — each agent gets its own git **worktree**. Main is never touched. 5. **Supervise** — o8 watches each agent's progress without spending a model call on it: detecting when one is stuck, retrying, tracking completion. 6. **Relay context** — when an agent finishes, its summary and changed files are captured and injected into the prompts of the packets that depend on it. The next wave starts already knowing what the last one did. 7. **Review** — the finished diff gets a verdict (see [Review & approval](/docs/review-and-approval)). 8. **Next waves** — dependent packets start as their prerequisites clear, wave after wave, until the mission is done. 9. **Merge** — the merge runs **through the policy engine**, not as a raw `git merge`. Nothing lands that the gate didn't clear. The short version: **create → plan → dispatch → review → approve.** Every feature in o8 serves that loop. ## One agent, one worktree The isolation is literal: o8 runs `git worktree add` onto a fresh branch and the agent works in its own directory. That buys four things: - **No conflicts** — agents on different issues never step on each other, and main is never touched. - **Real parallelism** — a whole wave runs at once. - **Damage containment** — if an agent goes off the rails, the worktree is removed and it's gone. - **GitHub as source of truth** — branches, PRs, and status are native, not a side database. When the work is good, the branch is pushed, a PR opens from it, and the worktree is cleaned up after the merge. ## The runtimes o8 doesn't talk to any one coding agent directly. It talks to a single contract — `AgentRuntime` — and every coding tool is an **adapter** behind it. Four ship today: - **Claude Code** - **Codex** - **Gemini** - **opencode** Because the control plane only ever speaks the contract, adding another is a small, well-shaped change — any agent that runs in a terminal can be plugged in. The contract normalizes the things that matter: spawn, attach, steer, stop, telemetry, approvals, artifacts. Capabilities are explicit, so the interface only ever shows controls a given runtime actually supports. ## Where you sit The orchestrator plans, dispatches, supervises, and audits — but the merge runs through the gate, and **you approve what matters.** Plans are reviewed before they execute. You can run the room from the desktop app, from mobile, from any agent that speaks MCP, or headless via the CLI — the same governed loop underneath all four. --- # Review & approval > How o8 decides what's safe to merge — risk-classified blind review and a five-layer recovery ladder with a hard cost ceiling. _stable · updated 2026-06-25_ "Nothing risky merges without your sign-off" has two halves: an AI half that catches what a human would miss on a fast-moving fleet, and a human half that keeps you the final gate. Here's how the AI half decides. ## Risk is a path, not a vibe Before any model reads a diff, a fast mechanical pass reads its *shape* — how much changed, whether whole files were rewritten, whether anything matches a dangerous pattern (an `eval`, an injection-flavored string, a mass deletion). That's triage, not the verdict. Then risk is decided by **what the diff touches**: | The diff touches… | Risk | What it gets | |---|---|---| | Schema, migrations, the lane state machine, the merge gate | **High** | a blind second review | | Whole-file rewrites or dangerous patterns | **High** | a blind second review | | Ordinary feature and UI code | **Standard** | one review, then merge | The logic: a subtle bug in a button color breaks one screen; a subtle bug in schema or the merge gate breaks the system every other agent depends on. So the dangerous diffs earn a second look, and the ordinary ones don't waste one. ## The blind second reviewer For a **standard** diff, a passing first review is enough — it clears the merge. For a **high-risk** diff, the first approval is deliberately *not* enough: it can only **nominate** the change. The merge stays blocked until a second, independent reviewer agrees. And that reviewer is **blind by design.** It's handed only the diff and the checks it must produce — never the first reviewer's verdict, score, or reasoning. There is nothing to rubber-stamp. It has to satisfy the protocol on its own: every guard live, every write partitioned correctly, every sub-requirement covered, and the execution path actually reaching the changed code. It returns one of a fixed set of verdicts — **agree, disagree, or inconclusive** — and only an independent *agree* turns the nomination into a cleared merge. Anything else sends the change back up the chain. > On the dangerous diffs, one model saying "looks good" doesn't open the gate. It opens a second, independent review. ## When a merge fails: the escalation ladder A branch can be green when it's written and still fail at merge time — main moved underneath it. o8 rebases onto current main and re-runs the typecheck before landing; if that fails, the lane doesn't stall and it doesn't loop forever. It climbs a fixed five-layer ladder — cheap and automatic at the bottom, you at the top — only as far as it has to: | Layer | What happens | Who decides | |---|---|---| | **1 — Auto-rerun** | one automatic retry, handing the worker the full typecheck output to fix its own branch | the system | | **2 — Escalate** | layer 1 failed → hand the lane to the orchestrator with the reason attached | the system | | **3 — Steer** | nudge the still-warm session to fix it in place — it already has full context | the orchestrator | | **4 — Redispatch** | the session's dead or the diff's wrong at the root → a fresh worker, with feedback | the orchestrator | | **5 — Human card** | the orchestrator tried 1–4 and it's still wrong → an explicit handoff to you | you | Two things make this a budget instead of a loop: - **Layer 1 means one.** Exactly one free automatic retry, counted since the lane's most recent dispatch — so a deliberate re-dispatch starts fresh, but a single failing run never spirals. - **Warm before cold.** The orchestrator prefers steering the warm session (cheap — the worker still has everything loaded) over a fresh worker, and only escalates to a human when both are exhausted. The order is the point. Most tools answer a failed merge by retrying until it works or until you notice — a runaway bill, a silent stall, or both. o8's answer is bounded: one automatic turn, then bounded attention, then you. **Recovery is a budget, not a loop.** --- # The Brain > o8's queryable memory — a cited map of how your project actually works, built from your specs, PRs, and every agent session. _stable · updated 2026-06-25_ Every coding-agent IDE is stateless: sessions start from zero, agents don't know what happened yesterday, and what your project knows lives in people's heads and scattered docs — never in the tool where the work happens. The Brain is o8's answer: a **queryable map of how your project actually works**, living on your machine, answering questions with cited sources. It's not file search, and it's not a vector index of raw code. It's a store of **distilled facts** — decisions, specs, processes, incidents, ownership, cross-repo invariants — each with a type, a confidence, and a source you can trace. ## What it solves When you (or a dispatched agent) ask "why is it built this way?", "who owns this?", or "what shipped last week?", the Brain answers from what your project has actually done — not a guess from whatever happens to be in context. Dispatched workers consult it instead of burning their context window searching files, and every answer comes back **cited**. It runs **local-first** — knowledge is stored in a database on your machine, and embeddings can run on a small model (local or hosted), so the Brain needs no cloud keys and your code never leaves the machine. It's free with your own CLI subscriptions. ## How it's built The Brain fills itself from the work you're already doing. An indexer reads your knowledge sources — merged PRs, your canonical specs (`CLAUDE.md`, `AGENTS.md`, `DESIGN.md`, `docs/`), review comments, and the outcome of every agent session — and **distills** them into durable facts. Each fact carries a **kind** (decision, spec, process, incident, ownership, cross-repo, directive) plus a confidence and the source it came from. Three guards keep the store honest: - **Verbatim provenance** — a fact's quoted excerpt must be a character-for-character substring of its source, or it's rejected. The Brain can't invent a name, number, or filename that isn't in the source. - **A confidence floor** — low-confidence extractions are dropped, not stored. - **Idempotent writes** — facts are fingerprinted, so re-indexing never duplicates. Not every source is equal. The Brain weights authority: your declared directives outrank merged PRs, which outrank closed session outcomes, which outrank conversational comments (opinions, not project rules). The longer o8 runs on your project, the deeper the Brain gets — written as much by your agents as by you. ## Two layers of memory The Brain holds two kinds of memory, doing different jobs: - **Explicit — directives.** The rules you *declare*: conventions, constraints, architecture decisions. You author and prioritize them in **Memory → Directives** (global or per-repo), and o8 injects the highest-priority ones into agents' prompts before they start — within a token budget, so the most important rules always make it in. Your canonical specs are ingested here automatically as high-authority directives. - **Implicit — the session ledger + distilled facts.** What the system *learns*: every agent run writes an outcome when it exits, and facts are distilled from PRs and docs as they land. This is the layer that answers "what shipped, and why." The explicit layer steers agents before they run; the implicit layer remembers what actually happened. ## How you ask it You query the Brain in plain language and get one cited answer. It's reachable from the **Brain card** on the canvas, the scratch chat ("Ask the Engineering Brain"), from a dispatched worker via `o8 ask` (which records that the worker consulted the Brain, with its sources), and from any external agent through the `cortex_ask` MCP tool. Under the hood, every question runs **classify → retrieve → compose**: - **Classify** — is this a lookup (who / when / where) or a reasoning question (why / how)? That decides how much it pulls. - **Retrieve** — several retrievers run in parallel — structured SQL, keyword (BM25) full-text, a knowledge graph, and the pre-extracted facts — and their results are fused, so keyword, semantic, and structured matches all get a vote. High-trust facts and freshly-ingested specs are pinned to the top. - **Compose** — a fast classifier routes the question, then an LLM composes the final answer from the retrieved facts and attaches its citations. Repeated and near-duplicate questions reuse a cached answer; any knowledge change clears the cache, so a re-ask after something lands reflects the new state. ## Staying current The Brain is built to not go stale: - **Incremental indexing** — new PRs, docs, and session outcomes are distilled as they arrive. - **A versioned store** — the database schema is versioned and migrates itself forward, so the Brain survives upgrades with no work from you. - **Confidence decay** — facts fade over time unless reinforced (an Ebbinghaus-style curve), so old knowledge doesn't masquerade as current. - **Memory Health** — a **Stale Queue** surfaces fading facts to reinforce or retire, and a **Conflicts Queue** surfaces contradictory facts so you can pick the winner. The Brain tells you when it's contradicting itself. > The compounding part: every session builds on every previous one. Every day you run o8, the memory gets deeper — and that's the part a competitor can't copy by shipping a feature. --- # Canvas > o8's spatial glass-space — work and media as draggable cards on one plane, with a navigator globe. Experimental. _experimental · updated 2026-06-25_ The Canvas is o8's **spatial workspace** — an experimental "glass-space" where work and media live as draggable, resizable glass cards on one open plane, instead of the fixed panels of the Control Room. Nothing has to live in one spot: the orchestrator, terminals, files, diffs, browsers, and images all float freely. It's **additive and dismissible** — it never replaces the Control Room. You open it, arrange things spatially, and exit back to the dashboard whenever you want. > The Canvas is **experimental** and off by default — turn it on in Settings → Operator Defaults (see *Turning it on* at the end). The card types below ship today; voice and multi-agent control are direction, and marked as such. ## The glass The Canvas re-skins the app as dark, tinted "Siri-style" clear glass — with the clearest material, your real desktop reads through the window. It's **tunable**: sliders for frost/blur, tint, ink brightness, and vibrance, with one-click presets (Clear / Siri / Frost). Behind the glass sits a deliberately minimal ambient backdrop you can pick — dots, paper, aurora, and a few others — kept subtle on purpose (big motion is hard on the eyes over a workday). ## What's on it Everything is a card you can drag, resize, and arrange: | Card | What it does | |---|---| | **Orchestrator** | A real conversation with the orchestrator — the same one that runs the dashboard — replies streaming into a side dock. | | **Brain** | Ask a question about the scoped repo; get a streamed, cited answer with source pills. | | **Terminal** | A real shell. | | **File** | Open any file; markdown renders with a Read/Edit toggle and a save. | | **Spec (o8.md)** | The repo's workspace spec at full parity with the dashboard — notes, talk-back, inline images, autosave. | | **Browser** | A URL bar and page with tabs and an element picker; agents can open pages here. | | **Diff + Review** | The governance surface as objects: a Review drawer lists live lanes, and picking one spawns a diff card with **Approve & merge** / **Request changes**. | | **Image & video** | Drag-drop media anywhere; drag a few together and they fan into a stack. | You arrange cards by dragging, zoom in steps, and switch between a free layout and a grid. New cards spawn into open space. ## The navigator globe In the bottom-left corner sits the **navigator globe** — a small glass loupe showing a scaled minimap of everything on the canvas (image cards render real thumbnails). Drag the ball to pan the view; use its −/fit/+ controls to zoom. It auto-hides when you're idle and slides back when your cursor approaches the corner. ## Where it's headed: voice and the room The Canvas is built to be driven by **voice across a fleet** — and this part is **direction, not shipped yet.** The intent: spawn several agents at once as cards, address one by name ("agent two, run the linter"), and **ask the room** — *"what's everyone working on?"*, *"which of these will conflict?"*, *"is this diff safe to merge?"* — answered out loud while the relevant cards light up. The governance posture is the point: observe everything, spawn freely, and **gate only the irreversible few** — merges, pushes to main, deletes, migrations, and spend always raise a visual approval card, while read-only questions run instantly. Voice will come in two tracks: a free local default and an opt-in realtime mode. Treat this section as the roadmap, not today's feature set. ## Turning it on The Canvas is **experimental and off by default.** Flip the **Experimental Canvas** toggle in **Settings → Operator Defaults** (where the glass-material sliders also live) and a **Canvas** button appears in the status bar. Click it to enter; an **Exit** control in the top dock returns you to the dashboard. It's desktop-only — there's no Canvas on mobile. --- # Symon > o8's voice operator — talk to o8 and it talks back, takes action by voice, and still stops for your yes on anything irreversible. _beta · updated 2026-06-25_ Symon is o8's **voice operator** — you talk to o8, it talks back, and it can take real actions on your Mac and inside o8 by voice. It's a distinct surface from the orchestrator: where the orchestrator dispatches the coding fleet and gates merges, Symon is the fast, hands-free plane you drive the room from. macOS only. The rule that makes voice safe: **Symon never gets a private back door around governance.** Every action with a side effect runs through the same approval gate as everything else in o8. ## Talking to it Two ways to converse, and they differ under the hood: - **Push-to-talk (the default, shipped).** Hold a key, speak a request, release. Symon runs a fast reasoning loop, takes the action or answers, and speaks the result back. Conversational in feel, turn-based in mechanism. - **Realtime voice-to-voice (opt-in).** A continuous mode where your speech and Symon's stream live, with the same native tools bridged in behind the same gate. It's a secondary track you turn on — a free local default with an opt-in realtime mode — not what runs out of the box. Either way, the tools and the safety gate are identical. A destructive action spoken into a live conversation still stops for your yes. ## Talking back Symon speaks — confirmations, results, and answers read aloud. Out of the box it uses the built-in macOS voice (no key, no network); higher-quality voices light up only if you configure them. It works two directions: you ask it a question by voice and it answers (in the floating dock as text, and spoken back), and when it wants to do something that needs your go-ahead, it speaks the proposed action and waits for your confirmation. ## The governance posture Voice can observe and act on low-risk things freely, but the irreversible stuff always stops for a yes. Symon sorts every action into three tiers: | Tier | Examples | What happens | |---|---|---| | **Read-only** | search, list, read, open an app | runs on its own, no prompt | | **Reversible** | create a reminder, event, or note | confirmed by default | | **Destructive / high-impact** | send mail, delete, run a Shortcut — and on the code plane, merges, pushes, migrations, spend | **always** raises a confirmation card; you can't suppress it | Two fail-safes back this up: anything Symon doesn't recognize is treated as destructive (it asks), and a hard never-do list — shell, sudo, keychain, credentials, secrets, system paths — is refused outright, not even gated. For a gated action it speaks the proposal, shows an Allow/Cancel card, and waits; no answer within the window means declined. > Direct your work by voice — and the irreversible stuff still stops for your yes. Voice inherits o8's "nothing merges unreviewed" gate; it doesn't route around it. For the hands-free text-input and command grammar, see [Dictation & say-commands](/docs/dictation). --- # Dictation & say-commands > System-wide hands-free dictation and a spoken command grammar — text and voice control in any app, not just o8. _stable · updated 2026-06-25_ Beyond the voice operator, o8 gives you **system-wide dictation** and a spoken command grammar — hands-free text and control in any app, not just o8. ## Dictation **Hold the Fn key, speak, release** — the polished text is inserted at your cursor. It's **system-wide**: it pastes at the caret of whatever app is frontmost — notes, browser, chat, your editor — not only o8. - **Double-tap Fn** for long-form, open-mic dictation; a single Fn tap finishes, Esc cancels. - Under the hood: on-device transcription captures what you said, an optional polish pass cleans up punctuation, casing, and obvious mishears (using what's on screen to spell names right), and the text is inserted without clobbering your real clipboard. - A small **floating dock pill** — always on top, transparent — shows the state (idle → recording → polishing → done), so it works even when o8 is minimized. ## Say-commands While dictating, a few spoken edits are handled deterministically: **"scratch that," "cancel," "new line," "new paragraph."** And saying **"say hello world"** makes o8 speak "hello world" aloud instead of typing it. ## Voice control **Hold the Option key and speak a request** — "remind me to call Sydney at 4," "what's on my calendar," "open Figma," "draft an email to…" — and Symon runs a short reasoning loop over a catalog of native Mac and o8 actions (Reminders, Calendar, Notes, Mail, Shortcuts, files, plus o8's own status, dispatch, and approvals). Anything with a side effect hits the governance gate — Symon classifies it and asks before anything irreversible (see [Symon](/docs/symon)). ## Setup First run asks for three macOS permissions, granted once: - **Input Monitoring** — so the global hotkey works everywhere. - **Accessibility** — to paste at the caret and read the current selection. - **Microphone** — to hear you. Dictation and the default macOS voice need **no API keys**. Higher-quality voices and the realtime voice mode are the opt-in extras. ### The hotkeys | Gesture | What it does | |---|---| | **Hold Fn** | push-to-talk dictation (pastes at the caret) | | **Double-tap Fn** | long-form dictation | | **Hold Option** | voice control — the reasoning loop over Mac + o8 actions | --- # MCP > o8 ships an MCP server first, an IDE second — any agent that speaks MCP can drive an o8 fleet through the same governance layer. _stable · updated 2026-06-25_ o8 ships an **MCP server first, an IDE second.** The desktop app, the mobile inbox, and the orchestrator's own tools are all clients of the same operator MCP server — and so is anything else that speaks the protocol. Claude Desktop, a terminal Claude Code session, Cursor, a third-party agent: each can drive an o8 fleet through the **same governance layer** that protects you on your phone. > We don't need to be everyone's editor. We need to be everyone's control plane. ## What an agent can do through it The server exposes o8's real operations as tools, grouped by what they do: - **Chat, status & approvals** — read the orchestrator's live state, send a message into a session, pull history, and resolve the diff waiting at the approval gate (`o8_status`, `o8_send`, `o8_history`, `o8_approve`, `o8_reject`). - **Mission dispatch** — the create → dispatch → status → review → approve sequence: the same calls the desktop runs when you dispatch a packet by hand. The spine is `create_mission` → `dispatch_mission` → `get_mission_status` → `submit_review` → `approve_and_merge`, with related controls for tailing, diffing, and retrying. - **Webview control** — screenshot, snapshot, click, type, read, navigate, and wait on the actual installed app. An external agent can write tests, reproduce a regression, and verify a UI fix landed in the real build (`o8_view_screenshot`, `o8_view_click`, `o8_view_read`, and the rest). - **The Brain** — ask a question and get cited facts back, or contribute an observation. Any connected agent inherits your organizational memory the moment it connects (`cortex_ask`, `cortex_propose_observation`). ## How it connects o8 runs the operator MCP server as a local stdio process — **bundled inside the signed app**, no separate clone or install. Wire it into a client from **Settings → MCP** ("install for Claude Desktop"), which writes the client's config (merge-preserving, with a timestamped backup) to point at the bundled server. A Claude Code session opened in your repo picks it up automatically. Everything stays on the loopback — no network port is exposed. ## Not a bypass An external agent driving o8 over MCP is bound by the same gates as the operator. The server calls the same internal APIs the desktop calls, behind the same loopback + token guard. A third-party agent's `dispatch_mission` still produces a packet the orchestrator reviews before it reaches your inbox; `o8_approve` still logs an event carrying the client's identifier, so you know *which* agent approved. Adding an MCP client is the same posture as adding a device to your network — it can do what the protocol allows, no more. --- # The CLI > The local o8 command line — an agent-first, JSON-by-default wrapper over o8's API, on $PATH in every worktree. _stable · updated 2026-06-25_ The `o8` CLI is an **agent-first wrapper over o8's local API.** It's on `$PATH` inside every packet worktree, so a dispatched worker drives o8 with it instead of curling the API — and you can use it too, for terminal-native fleet control. It's built for programs to consume: **JSON to stdout by default** (`--human` for pretty output), every payload carries a versioned schema, and the exit codes mean things — `0` ok, `2` connection refused, `3` unauthorized, `4` not found, `5` conflict — so an agent branches on the code without parsing strings. It's **loopback + token gated**: it works locally with no auth, and refuses over the network. It auto-resolves your packet and lane from the current directory. ## The command groups | Group | What it's for | |---|---| | `o8 status` · `version` · `doctor` | Fleet snapshot, versions, and a health check (`doctor --reap` clears zombie lanes). | | `o8 ask` | Ask the Brain a question; get a cited answer, scoped to your repo. | | `o8 run` | Run a process in an o8-owned terminal you can watch live (`--detach` for servers). | | `o8 packet` | Your dispatched work: `scope`, `diff`, `commit`, `review`, `report`, `capture` (visual proof). | | `o8 spec` | Annotate the repo's o8.md — `read`, `pending`, `comment`, `suggest`, `resolve` (never overwrite). | | `o8 task` | The project work queue: `list`, `create`, `claim`, `dispatch`, `report`. | | `o8 lane` | `lane touches --path ` — which other live lanes touch a file. | | `o8 cortex` | `cortex observe` — a worker writes a fact back to the Brain. | | `o8 browser` | Drive a browser the operator can watch: `open`, `read`, `click`, `type`, `wait`. | | `o8 team` | Coordinate multiple agents in one repo: `who`, `status`, `lease`. | A few in practice: - `o8 status` — the whole fleet at a glance. - `o8 ask "which middleware gate covers new API routes?"` - `o8 run -- pytest -q` — run tests in a watchable terminal. - `o8 packet diff`, then `o8 packet review --approve`. ## Who uses it - **Dispatched workers (primary).** A worker in its worktree gets its scope with `o8 packet scope`, commits with `o8 packet commit` (instead of raw git), consults the Brain with `o8 ask`, and surfaces progress with `o8 packet report` — all auto-scoped to its packet. - **You (power user).** Terminal-native control: `o8 status` for the snapshot, `o8 run` to launch something you watch live, `o8 packet review --approve` to merge. If `o8` isn't found, launch the o8 app once — it installs the CLI symlink on first run. --- # System & troubleshooting > Requirements, install and updates, the macOS permissions o8 asks for, and fixes for the common gotchas. _stable · updated 2026-06-25_ ## Requirements o8 is a native macOS app — a Next.js front end inside a Tauri shell, not a web app or Electron. - **macOS 14 or later.** - **Intel or Apple Silicon** — o8 ships one signed Intel build. On Apple Silicon it currently runs under Rosetta; a native arm64 build is on the way. ## Install & updates Download the `.dmg` from [o8.run/download](/download), drag o8 to **Applications**, and on first launch **right-click the app → Open** (the standard one-time macOS step). After that, o8 **auto-updates** — it checks for new releases and applies them in the background, and every update is **signed and verified** before it's trusted, so you stay current without doing anything. ## Permissions If you use voice (Symon / dictation), o8 asks for a few macOS permissions — one-time grants in **System Settings → Privacy & Security**: | Permission | Why | |---|---| | **Accessibility** | To capture the global push-to-talk hotkey and paste dictated text into whatever app you're in. | | **Input Monitoring** | A separate, stricter grant so the hotkey actually receives key events. Both this and Accessibility must be on. | | **Microphone** | To hear you, for dictation and Symon. | You only need these if you use voice; the rest of o8 works without them. ## Troubleshooting - **`o8: command not found`** — the `o8` CLI is a symlink o8 installs on launch. If it's missing, **relaunch the o8 app once** (it re-creates the link), then open a fresh terminal. - **The app won't open on first launch** — **right-click → Open** instead of double-clicking, to clear the one-time macOS prompt. - **The voice hotkey does nothing** — check that **both** Accessibility *and* Input Monitoring are enabled (they're separate toggles), then relaunch o8 so it picks up the grant. - **Dictation is silent** — Microphone was likely denied; re-enable it in System Settings → Privacy & Security → Microphone. --- # Plans > The honest deal — the whole app is free with your own keys, with an optional Founding Operator edition that runs a managed layer for you. _stable · updated 2026-06-25_ o8's deal is simple: **the whole app is free with your own keys.** No crippled tier, no trial, no feature held hostage behind a paywall. ## Free, with your own keys The governance gate, the Engineering Brain, multi-repo fleet orchestration, the canvas, mobile on your own network, and basic voice all ship **free**. It can be free because the actual coding work runs on **your own AI subscriptions** — bring your Claude or Codex CLI and o8 never injects its own key into the work path, so it carries no inference cost for you. Basic voice needs no keys either: dictation uses on-device speech, and o8 falls back to the built-in macOS voice. > Free is never the crippled version. We don't charge for capability — only for the cost of running the fast version for you. (One honest note: today's release is dev-first — it assumes you already have a Claude or Codex subscription to power the core loop. A managed allowance for newcomers is on the way, not live yet.) ## Founding Operator — the managed edition If you'd rather it be instant and hands-off, the optional **Founding Operator** edition is a one-time purchase that funds the build and turns on a **managed layer for life** (within fair use), so you don't run on your own keys for the essentials: - **Managed essentials, instant** — a fast Brain that answers immediately, automatic dictation polish, and premium speech-to-text. We run the fast version for you. - **Early access** — founders sit a release channel ahead; experimental features land for them first. Everything reaches free users eventually — it's timing, not a wall. - **An exclusive o8 theme**, a numbered Founding Operator badge, and your name on the [founders wall](/founders). See **[the Founding Operator edition](/founding)** for the tiers and what's left in the cohort. A couple of things stay bring-your-own-key for everyone, founder or not — premium third-party voices and speech-to-speech. And a few things are still coming: an off-network mobile relay and always-on cloud agents are direction, not today's feature set.