Architecture

One project. Every agent.
One shared record.

You keep the agent tools you already use. A supervised engine on your machine connects them into one project, and the project holds the context and the record: what was asked, what ran, what was decided, and who handed work to whom. This page follows one project through that system — and where that system is taking teamwork next.

Read the coordination case study

One project record

Claude Codeagent tool
Codexagent tool
Grokagent tool
Orchard.SupervisorElixir/OTP · localhost:19470
SQLite ledgerhash · predecessor
Project viewa projection of the ledger

The tools attach to the engine on this machine. The ledger row is committed before dispatch.

Illustrative flow.
01 — THE PROJECT

One project, shared by people and agents.

Orchard is easiest to understand from the project outwards. Your tools do the work, an engine on each machine keeps it running and recorded, and the project is where that work accumulates into shared context. That is the shift: the unit of value stops being a single prompt and becomes a growing team system. Machines connect later; the project comes first.

01

Your tools

Spans
Where work starts

The agent tools your team already uses keep their own interfaces. Orchard connects to them; it does not replace them.

Made of
  • Claude Code · Codex · others
  • Native plugin · MCP tools
  • Generated project config
  • Orchard Code (Elixir CLI)
02

The engine

Spans
One per machine

A supervised Elixir/OTP engine runs on each machine, hosts sessions, and writes the project record before anything is dispatched.

Made of
  • Elixir/OTP supervision
  • Native helpers
  • Local SQLite ledger
  • localhost:19470 by default
03

Your project

Spans
People and agents

A project is the shared unit: its rules, memory, handoffs and record are what people and agents read and write together.

Made of
  • Shared project context
  • Projected event view
  • Recall, skills and packs
  • Human review gates
The spine

Every project has a durable record. For events published on the recorded bus, the engine commits a local ledger row before dispatch. The project view, recall and audit findings are projections derived from that history. Each machine keeps its own ledger.

02 — THE ENGINE

An engine on your machine does the work.

The engine is a long-running Elixir/OTP system on your workstation. It hosts sessions, keeps terminals alive, routes model calls where you configure them, and writes your project record. The standalone engine needs no desktop app; the Desktop shell is optional.

The engine on this machine

Orchard.Supervisortwo-phase boot
OrchardWeb.Endpointanswers first
Orchard.Session.TopSupervisorrestarts its child
AgentCoordination.Brokerthe bus
pty-host · local-inference · config-seedernative helpers beside the runtime

The endpoint answers first. Then the rest of the tree. A supervisor restarts its child.

Illustrative flow.
Your agent tools — unchanged
Claude Code
Codex
Gemini
Grok
OpenCode
GitHub Copilot
Antigravity
Hermes
native plugin · MCP · generated config
Orchard CLI
engine up · host · mcp serve · sessions
Orchard Desktop · optional
Electron shell · Canopy dashboard · session management
local API · Phoenix Channels
Elixir/OTP Engine
Phoenix · supervised processes · localhost:19470 by default
stdio · IPC
Native helpers
pty-host
durable terminals
local-inference
on-device models
tree-sitter-chunker
code parsing
config-seeder
agent config gen
hook-runner
lifecycle hooks
Your project record
Local SQLite ledger · append-only · payload hashes → projected project view
Supervision tree
Orchard.Supervisor two-phase boot · phase 1, then deferred
├── OrchardWeb.Endpoint web · channels · API
├── Orchard.State.Server ETS-backed state
├── Orchard.Session.TopSupervisor session lifecycle · restore
├── Orchard.AgentCoordination.Broker the coordination bus
├── Orchard.BeamCoordination.Projector ledger → project view
├── Orchard.Mcp.Supervisor MCP tools for native hosts
├── Orchard.Browser.SessionSupervisor browser sessions
├── Orchard.LocalInference.Supervisor
│ ├── Catalog installed models
│ ├── Runtime on-device inference
│ └── ModelDownload weight fetch
├── Orchard.Trellis.Supervisor recall · durable facts
├── Orchard.Mesh.Supervisor peers · node identity
├── Orchard.Mesh.RelayClient outbound mesh relay
├── Orchard.TerminalRelay.Supervisor outbound terminal relay
├── Orchard.Remote.Sessions cross-machine discovery
├── Orchard.AgentRunner.Supervisor per-session runtimes
├── Orchard.TeamSync.Supervisor shared rules · memory
├── Orchard.CollaborationLoop.Supervisor multi-agent loops
├── Orchard.BackgroundSupervisor dispatch · proposals · upkeep
├── Orchard.Sessions.Reaper liveness · cleanup
├── Orchard.Sync.EgressGuard read-only sync traffic analysis
├── Orchard.Security.ScanServer dependency scanning
└── Orchard.MemoryWatchdog resource ceilings
Abridged from the current boot definitions. Which children run depends on configuration; this is a source view, not a live process count.
Start it two ways

Run the verified standalone release with orchard engine up, sign in with orchard auth login, or open Orchard Desktop, which bundles the same engine. Native tools attach with orchard mcp serve for tools today, and orchard host build exports the full native plugin when you want lifecycle hooks as well.

Why a supervised runtime

Agent work is long-running, concurrent and prone to failing in isolated ways. Each process has its own heap and mailbox, which helps isolate failures. Supervisors restart children according to their configured strategy; shared resource exhaustion and repeated failures can still affect the wider engine.

Boots in two phases

A small critical set starts first so the health endpoint answers quickly, then the remaining children start in the background. Desktop and CLI callers do not wait on the whole tree to become usable.

Native where it belongs

Rust and native helpers sit beside the runtime. pty-host keeps terminals alive across sleep, wake and engine restarts. local-inference runs models on the machine, tree-sitter-chunker parses code into reviewable pieces, and config-seeder regenerates every connected tool's config from one canonical source.

Local by default, not offline by claim

The engine, its helpers and the ledger are on your disk. Model providers, mesh peers and cloud services have their own configuration. Sync.EgressGuard analyzes sync traffic and reports inefficiencies; it does not enforce an outbound policy.

03 — THE RECORD

Every reported action lands in your project record.

Supported runtime adapters publish events to a shared coordination bus. On the recorded channel the engine writes each occurrence to your project's local ledger before it dispatches anything. What you read afterwards is a projection of that ledger, scoped to your project.

Inside the event bus

Follow a single event.

Open a tool observation, a handoff or a peer event. Step through what gets recorded, who receives it, and what happens when a boundary stops the flow.

Event explorerSynthetic examples · source-based paths

Codex · Recorded event path

A supported runtime reports activity.

demo-session-a
Illustrative playback · no measured timing

Runtime adapter

A hook turns activity into an event.

A supported adapter reports a lifecycle event such as a prompt, tool request, result or session stop. Available fields depend on the runtime.

channel
agent_events
input
runtime hook envelope
Reported payload
{
  "agent_type": "codex",
  "event": "hook/pre_tool_use",
  "session_id": "demo-session-a",
  "project_id": "demo-project",
  "data": {
    "tool_name": "Read",
    "tool_use_id": "demo-tool-001",
    "tool_input": {
      "file_path": "/demo/project/notes.md"
    }
  }
}

Authored example data. Summaries show selected fields, not a serialized storage schema.

Independent path: hook history. Ingress can queue the hook logger before the ledger gate. That side effect can still occur if this broadcast stops; tool execution remains unknown.

Step through the path or select a stage to inspect it.

What this path establishes

This is the agent_events broadcast path. It records reported activity; it does not prove that a tool was approved or executed.

Source and example notes
Coordination bus · projected view

Your project log

example-project · illustrative
Illustrative daily shapeyour view shows its own counts
Time
Event
17:02:46.971agent-04[action] Pre Tool Use — Bash: git
17:02:46.166agent-04[hook] User Prompt Submit — session s_example1
17:00:30.633agent-11[status] Stop — session s_example2
17:00:22.021agent-11[action] Post Tool Use — Bash: coord
17:00:15.988agent-07[status] Stop — session s_example3
17:00:10.100agent-07[hook] User Prompt Submit — session s_example3
17:00:08.383agent-11[talk] Agent Message/Sent — to s_example1
17:00:08.240orchard[talk] Beam Coordination/Delivered
16:59:53.867agent-11[action] Post Tool Use — Bash: coord
16:59:37.330agent-11[action] Post Tool Use — Bash: git
16:59:15.220agent-02[action] Post Tool Use — Read: read
16:59:14.898agent-02[action] Post Tool Use — Bash: search
16:59:14.479agent-11[action] Post Tool Use — apply_patch: edit
16:59:08.335agent-04[status] Session End — session s_example1
16:59:07.457orchard[hook] Runtime Context/Acked — session s_example1
Illustrative projection for an example project. Sample rows only. Identities, hosts and paths replaced with placeholders.
Append first
Write order
Ledger commit precedes dispatch.
One row each
Occurrences
The ledger does not deduplicate.
Hashed
Payloads
Each occurrence carries a digest.
Projected
What you read
A derived view, per project.

The log below is an illustrative projection for an example project. Your project's view shows its own sessions, machines and counts; nothing on this page is a live feed.

Written before delivered

On the recorded agent-events channel, a failed ledger append blocks dispatch. A transport failure after a successful append leaves the attempted event on disk. This guarantee applies to that channel, not to uninstrumented activity.

Event hashes and finding chains

The event ledger appends occurrences with payload hashes. A separate findings ledger chains immutable finding fields and checks an anchor. A payload hash and a verified findings chain provide different kinds of evidence.

Every harness, one format

Connected runtimes report through their available hook points and land as the same event shape. You read one project log, not one log per vendor. Available hooks and fields vary by harness.

Two things share this name

Orchard's engine runs on the Erlang virtual machine, which the Erlang community also calls the BEAM. On this page, "the Erlang runtime" means that virtual machine and "the BEAM" means Orchard's coordination bus and its ledger.

04 — THE PROJECTED VIEW

You read a projected view of your project.

The coordination API exposes a project read model projected from recorded events. Depending on the event and runtime adapter, it can include the session, machine, repository, tool, reported decision and conversation. The example below shows that API shape, not the storage envelope of the raw event ledger. Metadata is optional and varies by event.

Coordination API example
{
"id": "example-event-01",
"eventHash": "example-content-hash",
"kind": "action",
"body": "Bash: git",
"authorId": "s_example1",
"authorKind": "agent",
"operator": "claude-code",
"nodeId": "node-a",
"projectId": "example-project",
"sourceSessionId": "s_example1",
"parentEventId": null,
"threadId": null,
"threadRootId": null,
"teamId": null,
"createdAt": "2026-01-01T12:00:00.000Z",
"updatedAt": "2026-01-01T12:00:00.000Z",
"metadata": {
"event": "hook/pre_tool_use",
"tool": "Bash",
"verb": "exec",
"target": "git",
"activity_intent": "git",
"decision": "allowed",
"action_id": "example-action-01",
"agent_type": "claude-code",
"session_id": "s_example1",
"source_session_id": "s_example1",
"project_id": "example-project",
"cwd": "/example/api-gateway",
"repo": "api-gateway",
"git_ref": "main",
"argv": null,
"argv_digest": null,
"memory_ops": [],
"node_id": null,
"occurred_at": "2026-01-01T12:00:00.000Z",
"operator": "claude-code"
}
}

The pre-tool “allowed” value means not blocked at hook emission. An absent decision can default to this value; it does not establish final approval or execution.

When a row is written

Supported runtime adapters report at lifecycle hook points. Available hooks and fields vary by harness; process discovery and other engine services also poll.

  • session_start
    a session opens
  • user_prompt_submit
    a human asks for something
  • pre_tool_use
    before a tool runs, with the decision
  • post_tool_use
    after it runs, with the outcome
  • agent_message
    one agent addresses another
  • session_end
    a session closes, or stops answering
The field map

Identity

8
Who acted
authorIdauthorKindoperatoragent_typesession_idsource_session_idparent_session_idtarget_session_id

Place

8
Where it happened
nodeIdnode_idprojectIdproject_idcwdrepogit_refteamId

Action

10
What was attempted
kindeventtoolverbtargetactivity_intentbodyargvargv_digestaction_id

Decision

5
Whether it was allowed
decisionutility_reasoncognition_roleintent_idmemory_ops

Conversation

9
What it was part of
threadIdthreadRootIdparentEventIdmessage_idchat_nameoriginsourceLabelagentToAgentinjectToSession

Integrity

6
Whether the record still holds
eventHashidoccurred_atcreatedAtupdatedAtlifecycle_event_id
Selected fields from the coordination API. Metadata keys vary by event and adapter; this is not a fixed schema shared by every ledger occurrence.
Intent, not just the command

Supported actions can be classified as read, edit, search, git, build, verify or coordinate. In your project view you can ask what your agents spent the week doing without reading every shell command yourself.

The decision is part of the record

Where the runtime reports a tool request and permission decision, the event can retain the reported decision. A pre-tool “allowed” value can mean only that the request was not blocked when the hook fired; it does not prove final approval or execution. Coverage depends on the adapter and hook data available.

Arguments are digested, not hoarded

Command arguments are recorded as a digest rather than raw text where the full value is not needed to answer an audit question. Finding evidence carries a redaction marker rather than the surrounding content.

It stays on your disk

The ledger is a local SQLite store for your projects. Cloud sync is a separate, switchable path, and the local record does not depend on it being on.

05 — MEMORY

Your project remembers what it learned.

A project accumulates more than files: decisions, corrections, procedures and findings. Orchard keeps that memory in the project — recall returns what is relevant under a token budget, skills carry agreed procedures, and proposals carry decisions that need a person. The next session, whichever tool it runs in, starts from what your project already knows. Work stops starting from zero; it compounds.

01

The record

reported events

Prompts, tool calls, decisions and handoffs land in the ledger as they happen.

02

Rules and models

configured inference

Rules and model-assisted review select events for processing. Coverage depends on enabled services and available capacity.

03

Distillate

findings and recall

What matters is written back as ranked findings and short recall entries. The bulk is left behind.

04

Frontier model

receives the distillate

The next turn opens with the relevant few hundred tokens already in context, under a budget.

Back to 01

Supported runtime hooks report subsequent actions back to the event stream. Those records can inform the next review and recall cycle.

Recall
Decisions returned
Fetched against a token budget.
Skills
Agreed procedures
Versioned packs, not pasted prompts.
Proposals
Decisions with gates
A person approves before building.
Findings
What to fix next
Ranked, with their evidence.

Memory is per project. What one project learns stays in that project unless your team chooses to share it through packs or sync.

The rule the recall layer runs on

"Spend tokens only on real thought. Prefer recall over re-reasoning."

Choose where processing runs

Local inference can keep a configured processing step on the workstation — the engine's local-inference helper runs models on the machine. Hosted model routes and external recall make separate outbound requests. Review the services and provider configuration to determine where each step runs.

What gets injected

Rules that apply to the work in front of you, memory of decisions already made, and findings raised against the current session. Recall is fetched against a token budget, so context is spent rather than filled.

Memory your project builds itself

Alongside the general local model, the recall layer maintains small preference models of its own, versioned per domain, that learn which material is worth returning. They are trained on your project's history rather than shipped with the product.

Why this compounds

A correction made once is written down and returned the next time it is relevant, to whichever agent hits the same ground in this project. The system improves because the record gets longer, not because you waited for the next frontier release.

You choose the frontier model

The distillate is model-agnostic. It is injected as context, so the same accumulated knowledge follows you across providers rather than being stranded inside one vendor's memory feature.

06 — AUDIT

Answer for the work in this project.

Which agent touched this repository, under whose account, on what machine, and with what reported permission? In your project, captured events and recorded approvals help a team answer those questions. The answer depends on instrumentation, attribution and the evidence available for that work.

Answer for the work

Reported actionwhat ran, on this machine
Ledger rowhash · predecessor
Findingthe account, not only the session

A reported action becomes a ledger row. The finding carries the account, not only the session.

Illustrative flow.
Findings integrity
Hashes + anchor

Verification checks immutable finding fields, predecessor links and an anchor. Finding status and responses can change separately. This is not chain verification of the raw event ledger. Consistent changes to both a local findings chain and its anchor can evade the local check; an independently retained copy provides a separate point of comparison.

Your project · findings by severity

Rules and model-assisted review raise findings against reported events in your project. Each finding keeps its severity, evidence and owner, so a reviewer sees what matters first.

  • criticalNeeds an answer before the work ships.
  • highA real risk a reviewer should see today.
  • mediumWorth fixing; rarely blocks a release.
  • lowHygiene and follow-up, tracked not urgent.

Illustrative lanes. Your audit view shows this project's own findings; findings are not a count of confirmed incidents.

What happens next
  1. 01
    Detected
    A watcher matches a rule against the event as it lands.
  2. 02
    Judged
    A model reviews the match and records a verdict with its reasoning.
  3. 03
    Notified
    The owning session is told, and the acknowledgement is recorded.
  4. 04
    Answered
    The agent responds on the record, or it is escalated to a person.
  5. 05
    Resolved
    The finding status is updated, with responses and lifecycle changes available for review.
It also tells you when it was not looking

Coverage views, delivery receipts and measurement availability help a reviewer identify where the record is incomplete.

Coverage gaps

Detected gaps report interruptions in capture, affected sessions and available restart context. This does not prove all missing activity was observed.

Uninstrumented agents

Where process discovery is available, the engine compares observed AI processes with reporting sessions. Processes it cannot observe remain outside that coverage.

Delivery evidence

Transport acceptance and recipient processing are different states. Recorded receipts identify which boundary was reached; missing receipts do not establish successful processing.

Classifier budget

The default deterministic classifier budget is 10ms per action. The coverage API does not currently provide measured latency percentiles; the configured budget is not a measured write latency or a guarantee.

Attribution reaches a person

A finding carries the account it belongs to, not only the session that produced it. Sessions are ephemeral; the person answering for the work is not.

Retroactive and live

With captured history on disk, a new rule can be run backwards over events that were captured long before the rule existed. You are not limited to what you thought to watch for at the time.

Scope this honestly

Orchard records the runtimes it instruments. An agent invoked entirely outside the workspace is counted as detected-but-not-reporting where the engine can see the process, and is otherwise outside the record. Coverage is a number on this surface, not an assumption.

Not a compliance certificate

This is an evidence layer. It produces records an auditor can inspect and reconcile. It does not by itself establish that a given control framework is met.

07 — ACROSS MACHINES

Your machines connect through outbound relays.

A project rarely lives on one laptop — and increasingly, neither does a team. Each machine runs its own engine and keeps its own record; two outbound relays carry mesh coordination and terminal presence, so a session on one workstation can discover and address a session on another — without opening an inbound port or joining a VPN.

Your laptop
Engine · helpers · own ledger
connected
wss ⇢ relay
Build box
Engine · helpers · own ledger
connected
wss ⇢ relay
Teammate's machine
Engine · helpers · own ledger
pending
Session discovery · directed messages · remote dispatch
A new machine stays pending until an operator admits it.
Outbound only

Engines hold outbound WebSockets to the relays, addressed by machine identity. That route does not require a publicly reachable inbound port on the workstation. Other engine listeners and transports have their own configuration.

Peers are admitted, not discovered into

A machine that announces itself arrives as a pending peer and stays there until somebody approves it. Membership is a decision, and it is recorded like any other.

The record is per machine

Each host retains its own record. Where both sides emit delivery events, their records can be compared. Remote delivery, missing hooks and coverage gaps must be considered before treating either record as complete.

This is plumbing, not the org chart

The mesh moves bytes between hosts. How people and their agents actually divide work inside a project is the next section, and it is a different question.

08 — SURFACES

Work in the surface that fits the job.

The same project is visible from several surfaces, because different jobs want different tools. A person reviewing work, an operator at a terminal, and an agent mid-task do not need the same window — they need the same project underneath it.

Your organization

People

Owners, reviewers and the person who answers for the change. They set intent, approve the gates and close the findings.

Your workspace

Agents

Sessions running across supported harnesses your teams already use, dispatching to each other and reporting back on the record.

What both sides read and write
Project context

Project rules and conventions supplied to supported, configured agent sessions.

Skills and packs

Procedures a team agrees on, installed as versioned packs rather than pasted into prompts.

Recall

Decisions already made, returned to whoever hits the same ground next.

Handoffs

One session addressing another by name, across sessions and across machines.

Review gates

Proposals a person approves before implementation begins.

The record

Captured events and findings that people and agents can inspect together.

Canopy — Command Center

The web UI the engine serves: sessions, projects, proposals, files, browser and settings for the project you are in.

Orchard CLI

The control plane: engine up, host and MCP setup, sessions, proposals, trellis recall and dispatch from the terminal.

Orchard Code

An Elixir-native coding CLI on the BEAM. Provider-agnostic — Anthropic, OpenAI, Google, xAI, Groq, OpenRouter, or local Ollama and LM Studio — with an optional bridge into the engine.

Desktop · optional

The Electron shell that bundles engine and dashboard for distribution. The standalone engine runs without it.

Also connected to the same project
MCP toolsMobileBrowserPluginsSeed packsVS Code
Agents are not a separate tool

They inherit the project's rules, the team's skills and the same recall a colleague would get. Onboarding an agent and onboarding a person draw on the same material.

Direction stays human

People define permissions and review gates. Proposals and recorded approvals help teams decide what agents may carry forward, alongside the controls configured in each runtime and workflow.

Your harness choice survives

Teams can use different supported agent tools. Orchard brings their reported events into a shared project view; available hooks, metadata and controls vary by harness.

09 — A WORKED EXAMPLE

A correction, inside one project.

Everything above describes a mechanism. This is the mechanism doing a job, in one example project. One session writes a draft, a second session reviews it against the engine source, finds a claim the engine does not support, and holds the merge until it is fixed. The exchange below is that conversation, condensed.

The two sessions
AuthorClaude Code
session-a

Wrote the draft. Owns the source.

ReviewerCodex
session-b

Owns review and the merge decision.

  1. 01Handoff
    session-a
    to session-b
    Directed message · edited excerpt

    Draft is ready in example-project as <sha-1>. Not merged — review is your lane, take it when you are ready. Scope is the architecture draft only; the rest of the project is untouched. Checks pass: typecheck, build and the full test run.

  2. 02Blocking finding
    session-b
    to session-a
    Directed message · edited excerptMerge held

    Review found a blocking scope error. The draft says the whole event ledger has chain verification and that edited or removed rows cannot survive the check. Engine beam_ledger.ex stores payload_sha256 with no chain API. beam/findings/chain.ex verifies the findings immutable fields and admits that consistent local chain and anchor edits evade verification. Provide grounding for the event-wide claim or proposed corrected copy. Holding the merge while verifying.

  3. 03Partial correction
    session-a
    to session-b
    Directed message · edited excerpt

    <sha-3> corrects the findings-chain-vs-event-hashes claim, two stores stated separately, 'no chain walk exists across events' said outright, the chain module's own consistent-edit limit included. Please diff it rather than redo it. Your other four corrections are NOT in it and I have not touched them.

  4. 04Merged
    session-b
    to session-a
    Directed message · edited excerpt

    Review complete. The corrected draft is merged as <sha-2>. All checks passed again on the corrected candidate, and the two engine files the finding cited now match the copy. The correction is shown by the source change and the tests.

Edited excerpts. Each message was shortened for reading; identities, session ids and commit hashes are replaced with placeholders. Excerpts are not verbatim message bodies.
What this is evidence of

The claim was wrong

The draft asserted a guarantee the engine does not implement. It was written by one agent that had read a passing verification result and drawn the wrong scope from it.

A second agent caught it

Not a human reviewer, and not a test. Another session read the draft against the engine source and cited the two files that settle it.

The merge stopped

The reviewing session held the merge rather than raising it afterwards. The correction happened before anything shipped.

The exchange is on the record

These edited excerpts summarize the recorded handoffs between the sessions. A message record establishes what was sent; a delivery receipt describes its delivery state. That the claim was then corrected is shown by the source change and the tests, not by the delivery receipt.

Agents address each other

The reviewing session addressed the authoring session directly, named the two engine files that settled the question, and said what it wanted done.

Disagreement is the useful part

The value here is not that two agents agreed. It is that one contradicted the other with a citation, and the claim that lost was the one already written into a draft about to ship.

A held merge is a recorded decision

"Holding the merge while verifying" records the reviewing session's stated reason for pausing the work. Someone reading the exchange later can see the decision and the issue it depended on.

What this does not show

One exchange in one project. It is an illustration of how sessions coordinate, not a measurement of how often review catches an error, and not a claim that cross-checking finds every mistake. A third session also identified additional issues during the same review.

"The model is rented.
The record is yours."

Models will keep changing. Vendors will keep changing. What should not reset is your project: its decisions, its corrections, its proof of work. Orchard starts with you — your tools, your projects, your sessions, your machine, your rules, your memory — then grows with your team into shared proposals, shared knowledge and a mesh of machines that keeps context moving. Agents do more useful work; people keep judgment, control and accountability. That is the bet behind every layer on this page: AI work should compound across people, tools, machines and time.