How OpenOrc works

What OpenOrc is

OpenOrc is an Electron desktop app for working with coding agents. It has no language model or agent of its own; the only model it runs is a small local embedding model for memory search. It starts the agent command-line tools you already installed and signed in to (Claude Code, Codex, and OpenCode) and talks to them through their machine-readable interfaces.

Agents report what they do as a stream of events: text, tool calls, command output, file changes, and requests for permission. OpenOrc shows that stream as it arrives and saves the finished messages, tool calls, and results in a SQLite database on your computer, together with your conversations, tasks, and project memory.

OpenOrc hands your message to the agent's CLI, and the CLI calls its model provider, such as Anthropic or OpenAI, directly with your login. OpenOrc does not proxy or inspect that traffic. There is no OpenOrc account and no OpenOrc server.

The parts

OpenOrc is four kinds of process working together.

Interface

A React app in an Electron window. Everything stored in OpenOrc comes to it from the core, except the update settings, which main keeps. It asks main for its connection to the core, terminals, the Preview browser, frames for MCP apps, native dialogs, opening links, showing files in the file manager, and window controls.

Core

A Node.js process that owns the database, starts the agents, runs Git, and offers OpenOrc's own tools to agents through a local Model Context Protocol (MCP) server.

Agent CLIs

One child process of the core per active run. Agents read files, edit them, and run commands in the conversation's folder themselves.

Electron main

Creates the windows and starts the core. It also hosts terminals and the Preview browser, and stores encrypted secrets.

Processes and messaging covers every process in detail.

Following one message

1. You press Send. The interface sends a request such as runs.start to the core over a MessagePort.
2. The core validates it, works out the conversation's folder, agent, model, and mode, and prepares a Git worktree if the conversation uses one.
3. The core starts the agent CLI with OpenOrc's instructions and your message, or sends your message to the process already running for this conversation.
4. The CLI calls its provider and starts working. It reports text, tool calls, and file changes as they happen.
5. An adapter translates that output into OpenOrc's event format. Events go to the window in batches, at most one per run every 16 ms, and to the database in batches every 50 ms.
6. When the turn ends, the core records token usage and, in a Git project, a snapshot of the files. Then it sends your next queued message, if there is one.
7. When the agent process exits while OpenOrc keeps running, and memory is on, the run is queued for memory extraction. Runs that end because you quit are not distilled.

Conversations, tasks, and runs walks through the same path function by function.

Words used in these docs

Project

A Git repository you imported. Its conversations can work in your checkout or in their own worktrees.

Workspace

The built-in home for conversations outside projects. Each Workspace conversation works in a folder you choose, the shared Workspace folder by default, which does not need to be a Git repository.

Thread

A conversation. It has a current agent, model, and mode, and no finished state: you can always continue it.

Task

A Markdown document that describes work, with a status. Saving a task never starts an agent.

Run

The lifetime of one agent process. A run can contain many turns.

Turn

One request and the agent's work until it stops.

Session

The provider's own conversation ID. OpenOrc stores it so a later run can resume where the last one stopped.

Provider

One of the supported agent tools: Claude Code, Codex, or OpenCode. The code calls them harnesses. The companies whose models they call, such as Anthropic and OpenAI, are called model providers in these pages.

Ledger

The database table that holds an agent's events in order. Streaming fragments are removed once the finished item is stored, and native provider output goes to a log file instead.

Memory

Short project facts, such as decisions and working commands, distilled from finished runs or recorded by agents and by you.

Team

An experimental, saved group of agents with roles. It is off by default.

Where your data lives

OpenOrc keeps its data in one profile folder: ~/Library/Application Support/OpenOrc on macOS and %APPDATA%\OpenOrc on Windows. The OPENORC_USER_DATA environment variable selects a different folder.

Treat this folder as private. It contains your prompts, source snippets, and command output. Local storage lists every file and table.

Source map

OpenOrc is a TypeScript monorepo. Every page in these docs names the files it describes.

About these pages

These pages were written from the source code and checked against it. When the code and a page disagree, the code is right, and the page is a bug. Please open an issue.

• Processes and messaging: The processes OpenOrc runs, how the interface talks to the core, and what happens at startup and shutdown.
• Agent providers: How OpenOrc starts Claude Code, Codex, and OpenCode, talks to them, and turns their output into one event format.
• Conversations, tasks, and runs: The records OpenOrc keeps for your work and the path a message takes from the composer to an agent and back.
• What OpenOrc tells agents: The exact text OpenOrc adds to agent prompts, where it goes for each provider, and the messages it writes on your behalf.
• Permissions and app tools: What each mode lets agents do, how approvals work, and the rules for OpenOrc's own tools: the browser, messages between conversations, and memory.
• Local storage: What OpenOrc stores on your computer, in which files and tables, how long it keeps it, and what deleting removes.
• Network connections: Every connection OpenOrc makes, where it goes, what it sends, and how to turn it off.
• Security model: What stops web pages, other accounts, and other programs from using OpenOrc's access, and what it cannot protect against.
• Project memory: How OpenOrc turns finished runs into short project facts, stores and ranks them, and gives them to later runs.
• Git and review: How OpenOrc runs Git, creates worktrees, shows changes, applies work to your checkout, and publishes commits and pull requests.
• Agent teams: How the experimental team preview schedules several agents, routes their messages, and combines their changes.
• Slack: How a Slack mention becomes a conversation on your computer, who can do what, and what OpenOrc posts back.
• Known issues: Limitations and bugs we know about in the current version, with what to expect when you run into them.