# Loa Arbor

Arbor runs agents, plain code and people together, each doing its part. Start with one agent and add a teammate at a time.

Example, Shared coding session: A product manager and two engineers shape the plan in one conversation, and agents pick up the work, each coming back with a branch for a person to approve.

10 people, 40 actors, one conversation. No problem. Everyone joins in a role and sees only what's meant for them. Agents talk to each other and to people while they work, not only when they're done. Example, Game night: A game night with a narrator, a voice for every character and a private whisper for each player. No, seriously. Watch 10 people and 40 actors, 27 of them agents, in one session, with replies in about 5 seconds: under two minutes, recorded: https://arbor.getloa.app/en/benchmarks/#crowd

Servers die. Your agents don't. Every step is saved as it happens, and a call can wait days for a person. Example, Bookshop research team: A front agent sends three researchers to work at once, on two machines that share one database. Kill the machine in the middle of the answer, and the other one takes over from the last saved step and finishes.

- Coming soon
- See examples: https://arbor.getloa.app/en/#blocks

## Architecture

- Your product (a browser or mobile app with the client library, your own backend, or a webhook for SMS and email) → Arbor (runs your app's actors and agents, one saved step at a time): HTTP API: messages in, one stream out
- You and your coding agent (Claude Code or any agent in a terminal, with the arbor CLI and the docs it ships) → Arbor (runs your app's actors and agents, one saved step at a time): the arbor CLI: build, publish, run, test
- Arbor (runs your app's actors and agents, one saved step at a time) → Models (as many providers as you like, any that speak the OpenAI or Anthropic API; each agent picks its own): calls, priced and recorded
- Arbor (runs your app's actors and agents, one saved step at a time) → Tools and services (your own code, MCP servers, and the HTTP endpoints you allow): calls; a finished one never runs again
- Arbor (runs your app's actors and agents, one saved step at a time) → Postgres (every step, in one write; one node can run on a SQLite file): one transaction per step

## The building blocks

### Actors

Plain code with saved state, a function over the next batch of messages. Routing, timers and status labels are actors that never call a model.

Source, in arbor at v0.2.5: docs/model.md §0; docs/site/arbor-architecture.html, "Plain actors"

### Agents

An actor whose function is the model loop. It builds the context, calls the model, runs the tools the model asks for and repeats until it replies. Each agent picks its own model and provider, so one app can mix them, and a new revision can change them.

Source, in arbor at v0.2.5: docs/site/arbor-architecture.html, "What an actor is", "The three layers"

### Subagents

An agent starts children for work that can run in parallel. They message each other while both are working, so a parent can correct a child halfway through and a child can report progress before it's done.

Source, in arbor at v0.2.5: docs/site/arbor-architecture.html, "Agents and subagents exchange messages while both are working"

### People in roles

People join a session in the roles the app declares, and each sees only what is meant for them. A message addressed to one person goes to that person's stream alone.

Source, in arbor at v0.2.5: docs/model.md §0; docs/site/arbor-architecture.html, "Example: a support conversation"

### Relays

A ready-made actor that sends each message to its audience, everyone, one role or one person, so people and agents share one record.

Source, in arbor at v0.2.5: docs/site/arbor-architecture.html, "Status"; examples/seed/20-relay

### Tools, and calls that wait

Tools come from your code or from MCP servers. A call can wait for a person to approve it, for an answer on someone's screen, or for outside work to finish, for minutes or days and across restarts.

Source, in arbor at v0.2.5: examples/seed/15-held-calls; docs/site/arbor-architecture.html, "Approvals that wait"

### Memory and documents

One store of notes, each with a reach, a session, a partition or the whole app, and an audience. Documents are named and versioned, and can be held to a schema.

Source, in arbor at v0.2.5: docs/site/arbor-architecture.html, "Partitions, shared memory and schedules"; examples/seed/16-artifacts

### Partitions and schedules

A partition groups sessions by customer, campaign or tenant, so what was noted on Monday is there on Tuesday. A schedule posts a message on a timer, with no one having to write in.

Source, in arbor at v0.2.5: docs/site/arbor-architecture.html, "Partitions, shared memory and schedules"

### Skills and programs

An agent loads a skill, its rules and its tools, only when it needs it. With the run tool, the model writes a short program over its tools, and every call inside it is still a saved step.

Source, in arbor at v0.2.5: examples/seed/14-skills; docs/site/arbor-architecture.html, "Letting the model write a program"

### Connections and workspaces

An assistant can act for one person, with that person's own account on an MCP server; the token never reaches the code, the model or the record. A workspace gives an agent its own clone of a repository, where every command runs in the OS sandbox.

Source, in arbor at v0.2.5: examples/seed/23-connections; examples/seed/22-coding/README.md

Every block, with its code: https://arbor.getloa.app/en/blocks/

## Overwhelmed? Don't be.

Arbor was designed to be written and run by coding agents like Claude Code. It's built for the command line first, with a console operators can use to keep track of things.

### Your coding agent writes the app

A coding agent builds and manages the app from a terminal, with a person reviewing. A person can run the same commands by hand.

Source, in arbor at v0.2.5: docs/site/arbor-architecture.html, "Built to be operated by a coding agent"

### The docs ship with it

`arbor docs search` and `arbor docs get` work offline and match the version that's running. A new project gets an `AGENTS.md` that points the agent there.

Source, in arbor at v0.2.5: the same section, "The documentation is in the binary"

### Every command answers in JSON

Every command takes `--json`. An error is one JSON object with a stable code, the fields at fault and whether a retry can help, and the exit code says what kind of error it was.

Source, in arbor at v0.2.5: the same section, "Everything answers in JSON"

### Changes are staged, then published

The agent stages settings into a draft, a person or the agent reviews it, and one command publishes it as a new version. A command that destroys something runs only with `--yes`, and a script is refused rather than left waiting for a keypress.

Source, in arbor at v0.2.5: the same section, "Changes are staged, then published" and "Nothing pages, and a script is never asked"

### Your product calls one HTTP API

Your product opens a session, posts each message and reads one stream of everything that happens, over HTTP or with the client library for browsers and phones.

Source, in arbor at v0.2.5: docs/site/arbor-architecture.html, "Arbor"; client/

### A console for operators

The console comes with Arbor. It shows each session's people, what it has spent against its budget, and a graph of the app's actors drawn from the app itself.

Source, in arbor at v0.2.5: docs/site/arbor-architecture.html, the console screenshots' captions

The developer workflow: https://arbor.getloa.app/en/workflow/

## Examples

### Support desk

From a single actor to a room of customers, staff and agents, one block at a time. Each step is one of the seed apps in Arbor's repository, and the count is its lines of code, comments left out. The code with each step is cut down, with what the step adds marked.

1. One actor (01, 9 lines): Plain code that answers each message. No model.

```ts
import { actor, bundle, isMessage } from '@arbor/sdk';

const front = actor('front', {
  receive(ctx, batch) {
    for (const m of batch) {
      if (isMessage(m, 'user_msg')) ctx.emit('reply', { text: m.body.text });
    }
  },
}).wake('chat');

export default bundle({ app: 'seed-echo', roots: [front], session: { exposed: [front] } });
```

2. An agent (03, 23 lines): Give it instructions and the same actor becomes an agent, with a model loop inside.

```ts
import { agent, bundle } from '@arbor/sdk';

const front = agent('front', {
  instructions: 'You are the assistant of a small shop. Answer briefly and plainly. …',
})
  .wake('chat')
  .labels({ sale_captured: { type: 'boolean', mutable: true } })
  .hooks({
    beforeTurn: (ctx) => { /* … */ },
    afterTurn: (ctx, { answered, reply }) => { /* … */ },
  });

export default bundle({ app: 'seed-labels', roots: [front], session: { exposed: [front] } });
```

3. Subagents and memory (06, 43 lines): The agent starts researchers for questions it can look up in parallel, and keeps notes for this conversation and for the whole shop.

```ts
const researcher = agent('researcher', {
  instructions: 'You research one question for the shop. Answer in under 120 words. …',
});

const front = agent('front', { instructions })
  .wake('chat')
  .labels({ sale_captured: { type: 'boolean', mutable: true } })
  .subagents({ template: researcher, when: 'one independent question that needs looking up' });

export default bundle({
  app: 'seed-team',
  roots: [front],
  session: { exposed: [front] },
  uses: {
    memory: {
      notes: {
        tone: { across: 'session', among: 'subtree', description: 'how to talk to this customer' },
        house_style: { across: 'app', description: "the shop's standing guidance" },
      },
    },
  },
});
```

4. A second person (11, 28 lines): A member of staff joins the same conversation in a role of their own. The agent knows who said what.

```ts
const front = agent('front', { instructions })
  .wake('chat')
  .participants(['customer', 'staff'])
  .principal('opener')
  .clientEvents({ subtypes: ['participant_joined', 'participant_left'] });

export default bundle({
  app: 'seed-participants',
  roots: [front],
  session: {
    roles: {
      customer: { max: 1, principal: true },
      staff: { max: 2, join: 'invite', may: ['session.grant'] },
    },
    exposed: [front],
  },
});
```

5. Calls that wait (15, 60 lines): A refund over $100 waits for a member of staff to approve it, for minutes or days, across restarts.

```ts
const front = agent('front', { instructions })
  .wake('chat')
  .participants(['customer', 'staff'])
  .tool({
    name: 'refund',
    description: 'Refund an order. Refunds over $100 wait for a member of staff to approve them.',
    params: { /* order, amount */ },
    handler: (args, ctx) => {
      const amount = Number(args.amount);
      if (amount > 100 && !ctx.approved) return ctx.needsApproval(`a refund of $${amount} is over $100`);
      return { refunded: true, amount, approved_by: ctx.approved?.by ?? null };
    },
  });
```

6. A room (20, 93 lines): A relay sends each message to its audience, to everyone, to staff only or to one person. A coach agent hears it all and writes notes for the staff.

```ts
const coach = agent('coach')
  .wake('chat')
  .hooks({ beforeTurn: async (ctx) => { /* fold what it heard; a "NOTE: " line goes to the staff */ } });

const lobby = relay('lobby', {
  roles: ['customer', 'staff'],
  messages: {
    text: {},
    note: { for: { role: 'staff' } },
    whisper: { for: { participant: 'to' } },
  },
  readers: [coach],
  writers: [coach],
});

const desk = agent('desk', { instructions })
  .wake('chat')
  .participants(['customer', 'staff'])
  .subagents(breakout);

export default bundle({
  app: 'seed-relay',
  roots: [lobby, coach, desk],
  session: { roles: { customer: { max: 2, principal: true }, staff: { max: 3 } }, exposed: [lobby, desk] },
});
```

### Game table

A tabletop campaign that a game master and up to six players come back to over many evenings. Each step is a seed app; 14 starts again from a one-agent chat.

1. A table, and a line each (12, 31 lines): One agent narrates for the whole table. Each player also gets a private line to the game master, made the first time they use it; no player reads another's.

```ts
import { agent, bundle } from '@arbor/sdk';

const table = agent('table', {
  instructions: 'You are the game master of a small dungeon crawl, narrating for the whole table. …',
})
  .wake('chat')
  .participants(['player', 'dm']);

const whisper = agent('whisper', {
  instructions: 'You are the game master, in a private line with one player. …',
})
  .wake('chat')
  .participants(['player'])
  .instance('participant')
  .principal('opener');

export default bundle({
  app: 'seed-instances',
  roots: [table, whisper],
  session: {
    roles: { dm: { max: 1, principal: true }, player: { max: 6 } },
    exposed: [table, whisper],
  },
  uses: { memory: {} },
});
```

2. A campaign (13, 51 lines): Each evening is a session, and the campaign ties them together. Notes on the world last from one evening to the next, the narrators keep secrets the players never see, and the table spawns a character to voice each scene.

```ts
const npc = agent('npc', {
  instructions: 'You voice one character of the campaign for a single scene. …',
});

const table = agent('table', { instructions })
  .wake('chat')
  .participants(['player', 'dm'])
  .subagents({ template: npc, when: 'a player speaks to a character of the world' });

export default bundle({
  app: 'seed-campaign',
  roots: [table, whisper],
  session: {
    roles: { dm: { max: 1, principal: true }, player: { max: 6 } },
    partition: { by: 'campaign', from: 'input' },
    exposed: [table, whisper],
  },
  uses: {
    memory: {
      groups: { narrator: [table, whisper] },
      notes: {
        world: { across: 'partition', description: 'what is true of the campaign world' },
        secrets: { across: 'partition', among: 'narrator', description: 'what the narrators keep from the table' },
      },
    },
  },
});
```

3. Rules when needed (14, 53 lines): The narrator loads the combat or the travel rules, each a prompt and a tool, only when the story calls for them, and searches the rule book instead of reading all of it.

```ts
const combat = skill('combat', {
  description: 'Resolving fights: who acts first, attacks against guard, harm and vigour',
  prompt: fromPrompt('combat-rules'),
  tools: [strike],
});

const travel = skill('travel', {
  description: 'Journeys: legs, supplies, foraging and weather',
  prompt: fromPrompt('travel-rules'),
  tools: [forage],
});

const narrator = agent('front', { instructions: fromPrompt('narrator') })
  .wake('chat')
  .skills([combat, travel], { maxLoaded: 2 })
  .docs({ search: true, paths: ['docs/rules/**'] });

export default bundle({
  app: 'seed-skills',
  roots: [narrator],
  session: { exposed: [narrator] },
  uses: { artifacts: {} },
});
```

4. Character sheets (16, 51 lines): Each character lives on a sheet its player owns, checked against a schema, and the narrator changes only what changed, such as hit points. Handouts are kept and searched the same way.

```ts
const sheet = {
  description: 'a character sheet',
  schema: { type: 'object', properties: { name: { type: 'string' }, hp: { type: 'integer', minimum: 0 } /* … */ } },
  across: 'partition' as const,
};
const handout = { description: 'a handout: a map, a letter, a rumour', across: 'partition' as const, search: 'lexical' as const };

const table = agent('table', { instructions })
  .wake('chat')
  .participants(['gm', 'player'])
  .artifacts(['sheet', 'handout'], { write: ['sheet', 'handout'], maxPins: 2 });

export default bundle({
  app: 'seed-artifacts',
  roots: [table],
  session: {
    roles: {
      gm: { max: 2, principal: true, may: ['artifacts.read'] },
      player: { max: 6, may: ['artifacts.read:handout', 'artifacts.create:sheet'] },
    },
    partition: { by: 'campaign', from: 'input' },
    exposed: [table],
  },
  uses: { artifacts: { kinds: { sheet, handout } } },
});
```

### Engineering team

Three apps, each built from the same blocks as the others. 23 builds on 17; 22 starts again from a one-agent chat.

1. A router (17, 31 lines): Plain code asks an outside service once which group a conversation belongs to, and hands every message to that group's agent. The answer is recorded, so a restart never asks twice.

```ts
import { actor, agent, bundle, isMessage } from '@arbor/sdk';
import { endpoint } from 'arbor:http';

const quick = agent('quick', { instructions: 'Answer in one short sentence.' }).wake('chat');
const careful = agent('careful', { instructions: 'Give two short reasons, then the answer.' }).wake('chat');

const router = actor('router', { state: { cohort: '', routed: 0 } })
  .wake('chat')
  .receive(async (ctx, batch) => {
    for (const m of batch) {
      if (!isMessage(m, 'user_msg')) continue;
      if (!ctx.state.cohort) {
        const res = await endpoint('experiments').get('/cohort', { query: { session: ctx.session.id } });
        ctx.state.cohort = (res.json as { cohort: string }).cohort;
      }
      ctx.send(ctx.state.cohort === 'b' ? careful : quick, 'user_msg', m.body);
    }
  });

export default bundle({
  app: 'seed-router',
  roots: [router, quick, careful],
  session: { exposed: [router] },
  peers: [{ from: router, to: quick }, { from: router, to: careful }],
  http: { experiments: { url: 'https://experiments.example', methods: ['GET'] } },
});
```

2. An assistant each (23, 64 lines): Each person on the team gets their own assistant, which reads their own Jira issues with their own account; nobody's token reaches the code or the model. A schedule wakes the desk to check in with everyone present.

```ts
const worker = agent('worker', { instructions: "You are one person's own Jira assistant. …" })
  .instance('participant')
  .principal('opener')
  .participants(['user'])
  .tools('jira.*');

const desk = actor('desk', { state: { checkins: 0 } })
  .participants(['user'])
  .receive(async (ctx, batch) => {
    for (const m of batch) {
      if (m.sender.principal === 'participant') {
        ctx.send(`worker[${m.sender.participant}]`, 'user_msg', { text: m.body.text });
        continue;
      }
      for (const w of await ctx.instances(worker)) ctx.send(`worker[${w.key}]`, 'user_msg', { text: CHECKIN });
    }
  });

export default bundle({
  app: 'seed-connections',
  roots: [desk, worker],
  peers: [{ from: desk, to: worker }],
  uses: { connections: { jira: { provider: 'atlassian-mcp', scopes: [/* read, search */] } } },
  schedules: { checkin: { text: 'check in', root: desk } },
});
```

3. A coding agent (22, 23 lines): Told a test fails, an agent opens a workspace, a clone on its own branch where every command runs in the OS sandbox. It finds the function, fixes it and commits, and the branch is pushed only once a person approves.

```ts
import { agent, bundle, workspace } from '@arbor/sdk';

const fixer = agent('fixer', {
  instructions:
    'You fix failing tests in the repository app. Open a workspace on it first. Find the function with ws_grep, ' +
    'change it with ws_edit, commit, push the branch with ws_push, and report the branch. …',
})
  .wake('chat')
  .subagents(workspace);

export default bundle({
  app: 'seed-coding',
  roots: [fixer],
  session: { exposed: [fixer] },
  uses: { coding: {} },
});
```

Fuller examples, in code and prose: https://arbor.getloa.app/en/examples/

## What Arbor handles for you

### A crash loses at most one step

Each step is saved in one write before the next begins. If a node dies, another picks the actor up after the last saved step, and no finished model or tool call is made twice. A session that is waiting uses no compute.

Source, in arbor at v0.2.5: docs/model.md §0; docs/site/arbor-architecture.html, "What a step saves", "What happens when a node crashes"

### Spending is exact, and capped

A model call's cost is saved in the same write as its answer, so the bill and the record can't disagree. Caps on an actor, on an agent and its subagents, or on a session can warn, refuse further calls, or stop.

Source, in arbor at v0.2.5: docs/model.md §2.7; docs/site/arbor-architecture.html, "What a step saves"

### Rules on every tool call

For each app or agent, a tool call can be allowed, warned about, blocked, halted or held for a person. If a node dies mid-call, a read-only or repeatable tool runs again; any other is not, and the agent is told the outcome is unknown, unless the tool's author chose to hold it for a person.

Source, in arbor at v0.2.5: docs/site/arbor-architecture.html, "Traces, the ledger and cost", "What a step saves"

### Any conversation can become a test

Copy a real conversation at the step where it went wrong, give the copy a new prompt, model or tool, and compare the two, with what each cost. The copied steps aren't run again, and for each kind of call you choose who answers: the live system, the recorded answer, or a stand-in. A tool that sent an email in the original doesn't send it again.

Source, in arbor at v0.2.5: docs/site/arbor-architecture.html, "Copying a session at any point to test a change"

### New versions never change a running conversation

A session keeps the version of the app it started on until it closes. A new version can take a share of new sessions first.

Source, in arbor at v0.2.5: docs/site/arbor-architecture.html, "Releasing a new version"

### Nodes hold nothing

Any node can carry on any actor, so you can add and remove nodes while Arbor runs. One node runs on a SQLite file; a fleet shares Postgres, Redis and a blob store.

Source, in arbor at v0.2.5: docs/site/arbor-architecture.html, "Running Arbor", "How Postgres provides the durability"

### Every step is traced

Where the time went, what each actor decided and what it cost come from the same saved steps, so they always agree. Traces are OpenTelemetry, and a console ships in the binary.

Source, in arbor at v0.2.5: docs/site/arbor-architecture.html, "Traces, the ledger and cost"

### Tested

About 2,900 Go tests run with the race detector, plus an integration suite against Postgres. Each storage interface has one test suite that every implementation must pass.

Source, in arbor at v0.2.5: docs/site/arbor-architecture.html, "Status", "Running Arbor"

## Benchmarks

- 10k: commits a second (10,414) across 16 sessions, on Postgres on one laptop (docs/site/arbor-architecture.html, "How Postgres provides the durability", 5 October 2026)
- 1.2ms: median commit in that same test; 0.6 ms for one actor on its own (the same table, "16 sessions, 1 actor each" and "1 session, 1 actor")
- 1,086: turns a second through one node, 200 sessions at once, on Postgres and Valkey, with a scripted model on one development machine (1,093 on a second run) (docs/tasks-history.md, K-68, "Read 2026-11-16", configuration postgres-valkey)
- 1.6ms: the slowest 1% of commits in that same test (the same table, "16 sessions, 1 actor each")

How each number was measured: https://arbor.getloa.app/en/benchmarks/

## When Arbor isn't a good fit

- Milliseconds matter, as in a medical device or a self-driving car. Arbor puts reliability and safety ahead of speed: every step is written to the database before the next one starts. On one laptop that write takes a median of 0.6 ms, under 0.8 ms for the slowest 1%, about 2 ms when four actors share a session, and about 12 ms with sixteen. Beside model and tool calls that take hundreds of milliseconds or more, the overhead is negligible. (docs/site/arbor-architecture.html, "Where Arbor is the wrong choice"; "Commit test")
- You want a general-purpose programming platform. Arbor is a durable ledger with a lightweight actor model, for building rich agentic business processes with little effort. It's like a workflow engine, without the rigidity. Apps are short TypeScript, written to be authored by coding agents, and reach the outside through tools and MCP servers. (the same section)
- You want a library inside your own process. Arbor is a server you run and call over an API. (the same section)
- You need voice. It isn't built. (the same section)
- You need a vendor behind it. There's no hosted service or support contract today. If that's what's stopping you, let's talk. Arbor is pre-release, and stored data doesn't survive a change to its schema yet. (mailto:arbor@getloa.app) (the same section; "Status")
- The job is one prompt and one answer. A single stateless call gains little from a durable runtime. (the same section)

Loa Arbor. Licensed under the Functional Source License 1.1, with MIT as its future licence (FSL-1.1-MIT): each release becomes MIT two years after it comes out. Coming soon: the download opens when the repository goes public.
