coding/

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

Links

Open Source Insights

README ¶

Or

Or is the product built on the reusable agent and llm libraries. Its packages are product implementation details and are not a public SDK.

Or and the Go packages use the same version.

Layout

coding/
├── client/                 React client
├── desktop/                Electron desktop shell
├── cmd/coding-desktop/     Authenticated desktop sidecar
└── internal/
    ├── app/                Product runtime composition root
    ├── desktopserver/      Authenticated API and renderer host
    ├── httpapi/            HTTP and SSE delivery
    ├── conversation/       Product conversation lifecycle and queueing
    ├── engine/             One stateful coding-agent session
    ├── transcript/         Session events, validation, recovery, and projections
    ├── contextprojection/  Hidden product-context staging and projection
    ├── compaction/         Context compaction
    ├── prompt/             Or system prompt
    ├── skills/             Skill discovery and loading
    ├── tools/              Or tools and local execution
    ├── permission/         Tool-call authorization and approval policy
    ├── mcp/                Product-level MCP configuration and connections
    ├── provider/           Provider settings and connection testing
    ├── workspace/          Workspace registry and scratch directories
    ├── usage/              Token and cost ledger
    ├── observability/      Privacy-safe lifecycle and performance events
    ├── snapshot/           On-demand provider exchange projection
    └── trace/              UI-facing diagnostic read model

Dependency direction

client -> desktopserver -> httpapi -> conversation -> engine -> agent -> llm
                              ^             |
                              |             +-> transcript, contextprojection
                              |             +-> compaction, prompt, skills
                              |             +-> tools, permission
                              +--- app creates and connects all services

Electron supervises cmd/coding-desktop, which hosts the runtime assembled by internal/app. Product policy stays inside coding; agent and llm must not import it. The coding product packages must not depend on harness.

Repository contributors can read the Coding Agent backend ownership and run invariants in internal/engine/ARCHITECTURE.md.

Session and diagnostic data

The append-only transcript is the durable source of truth for session recovery, product history, and inspectable provider exchanges:

transcript -> snapshot projection --+
                                  +-> trace -> HTTP API / UI
observability events -------------+

observability records privacy-safe timings, lifecycle IDs, retries, token usage, and cost. snapshot reconstructs a sanitized, provider-neutral request and response view from a committed transcript only when requested. trace persists nothing; it combines both projections into the task, request, attempt, checkpoint, and tool views consumed by the diagnostics UI.

Scope boundaries

Or currently targets trusted local workspaces. permission controls which effects need approval; it is not a security sandbox. Sandbox execution and browser automation are not contracts of the reusable agent or engine layers. Existing browser and preview integrations stay at the product edge in tools, httpapi, the client, and Electron so core coding behavior does not depend on them.

Agent Skills

Or implements the open Agent Skills specification. It loads user skills from ~/.agents/skills/<name>/SKILL.md and workspace skills from <workspace>/.agents/skills/<name>/SKILL.md. A workspace skill replaces a user skill with the same name.

SKILL.md must contain standard YAML frontmatter followed by Markdown instructions:

---
name: code-review
description: Review code for defects and regressions. Use when asked to review changes.
---

# Code review

Inspect the diff and report findings by severity.

Or validates the standard name, description, license, compatibility, metadata, and allowed-tools fields. Unknown top-level fields are rejected. The Markdown body is loaded unchanged; Skill files do not support argument substitution. Relative file references resolve from the skill directory.

Type / in the composer to search built-in commands and Skills in one catalog. Selecting a Skill creates a typed Skill reference. Or can also activate a Skill automatically when its description matches the task. Activated instructions are kept as protected session context across compaction. The experimental allowed-tools field is preserved but never bypasses Or's normal permission policy.

MCP servers

Or can discover and call tools from configured Model Context Protocol servers. See MCP configuration for the supported stdio and Streamable HTTP transports, workspace scoping, environment references, and security model.

Desktop

Electron supervises a dedicated Go sidecar on a random loopback port. The sidecar serves both the React build and /api, so the renderer uses one relative HTTP/SSE contract. Every request requires a per-launch HttpOnly session cookie installed by Electron before the first navigation.

The right-side Browser is rendered with Electron <webview> elements. React owns their layout and tab lifecycle, so menus and dialogs can compose above a page without hiding a separate native child view. A renderer-side registry owns navigation revisions, history state, failure reporting, and bounded read-only inspection. User-opened tabs belong to the Workbench and remain mounted when a conversation or task view opens; Agent preview tabs and control stay scoped to their owning session. The Workbench can keep multiple conversation tabs open; new empty conversations remain renderer-local drafts and appear in the session list only after their first message is sent.

Public HTTP(S) pages use the persistent persist:or-browser session. Workspace files use the in-memory or-preview session and a separate preview-only loopback origin that exposes no product API. Electron validates every guest at attach time, denies guest permissions and downloads, and converts popup or cross-origin preview navigation into application-owned browser tabs.

Run the desktop app in development:

cd coding/desktop
bun install
bun run dev

Build an unpacked application for the current platform:

cd coding/desktop
bun run package:dir

Use the following command to create ad-hoc signed macOS distributables under coding/desktop/release:

bun run package -- --mac --publish never \
  --config.mac.identity=- \
  --config.mac.hardenedRuntime=false

Repository vX.Y.Z tags build Apple Silicon and Intel Mac installers. See RELEASING.md.

Provider settings, sessions and transcripts live under ~/.or/coding. Set OR_DATA_DIR to use another location. The desktop shell is single-instance: launching it again restores and focuses the existing window.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
coding-desktop command Command coding-desktop runs the authenticated loopback server supervised by the Electron main process.	Command coding-desktop runs the authenticated loopback server supervised by the Electron main process.
mcp-test-server command Command mcp-test-server runs a deterministic local MCP server for manually exercising Or's tool discovery and result handling.	Command mcp-test-server runs a deterministic local MCP server for manually exercising Or's tool discovery and result handling.
internal
app
compaction Package compaction prepares and summarizes old coding-session context.	Package compaction prepares and summarizes old coding-session context.
contextprojection Package contextprojection manages product-generated context that is projected into model requests without becoming canonical conversation input.	Package contextprojection manages product-generated context that is projected into model requests without becoming canonical conversation input.
conversation
desktopserver Package desktopserver serves the Electron renderer and product API from one authenticated loopback origin.	Package desktopserver serves the Electron renderer and product API from one authenticated loopback origin.
engine Package engine owns one stateful coding-agent session.	Package engine owns one stateful coding-agent session.
httpapi Package httpapi is the product's HTTP delivery layer.	Package httpapi is the product's HTTP delivery layer.
httpapi/internal/genwire command Command genwire generates the browser's TypeScript wire DTOs from the Go structs and string enums in wire_contract.go.	Command genwire generates the browser's TypeScript wire DTOs from the Go structs and string enums in wire_contract.go.
imageprep Package imageprep validates and normalizes raster images before they enter provider-independent model content.	Package imageprep validates and normalizes raster images before they enter provider-independent model content.
mcp Package mcp owns Or's product-level MCP configuration, connection manager, leases, diagnostics, and adaptation of protocol tools to coding-agent tools.	Package mcp owns Or's product-level MCP configuration, connection manager, leases, diagnostics, and adaptation of protocol tools to coding-agent tools.
mcp/client Package client owns protocol-native Model Context Protocol connections, transports, tool discovery, and tool calls.	Package client owns protocol-native Model Context Protocol connections, transports, tool discovery, and tool calls.
observability Package observability records privacy-safe product lifecycle events.	Package observability records privacy-safe product lifecycle events.
permission Package permission owns the coding product's tool authorization policy.	Package permission owns the coding product's tool authorization policy.
prompt Package prompt deterministically renders the coding agent's stable system prompt, discovers the instruction files and environment that make up its dynamic context, and renders those as model-visible attachments.	Package prompt deterministically renders the coding agent's stable system prompt, discovers the instruction files and environment that make up its dynamic context, and renders those as model-visible attachments.
provider Package provider manages the coding product's persisted provider connection profiles.	Package provider manages the coding product's persisted provider connection profiles.
skills Package skills loads file-backed skills and exposes them to a coding agent.	Package skills loads file-backed skills and exposes them to a coding agent.
snapshot Package snapshot projects inspectable, provider-neutral model exchanges from committed transcripts.	Package snapshot projects inspectable, provider-neutral model exchanges from committed transcripts.
tools Package tools implements the coding agent's built-in tools and the product bridges those tools use to interact with the desktop surface.	Package tools implements the coding agent's built-in tools and the product bridges those tools use to interact with the desktop surface.
trace Package trace assembles performance events and private request snapshots into one UI-facing diagnostic read model.	Package trace assembles performance events and private request snapshots into one UI-facing diagnostic read model.
transcript Package transcript defines the durable, append-only history of a coding session.	Package transcript defines the durable, append-only history of a coding session.
usage Package usage is the coding product's token and cost ledger.	Package usage is the coding product's token and cost ledger.
workspace Package workspace owns the directories a coding session runs in: the project roots a user registers, and the scratch directories the server generates for standalone chats.	Package workspace owns the directories a coding session runs in: the project roots a user registers, and the scratch directories the server generates for standalone chats.