Skip to content
arbe docs

Architecture

How the packages fit together. Read this before exploring code.

Package graph

Foundation — no workspace dependencies:

@arbe/cmd                 command definition + argv parsing
@arbe/util                shared json + path helpers
@arbe/streams             durable stream client
@arbe/observability       SQLite event log
@arbe/task                repo-native task graph
@arbe/sandbox             sandbox registry + connection

Domain layer:

@arbe/core                → streams, observability, task

Surfaces — everything users and agents touch:

@arbe/cli                 → cmd, core, observability, sandbox, streams, task
@arbe/www                 → core, streams
@arbe/worker              → core, streams

No code, loaded as context:

@arbe/agents              prompt files (.md)
@arbe/skills              skill files (.md)

Storage and data flow

Three storage systems (Postgres, Durable Streams, Durable Objects) plus Electric SQL as the sync layer. See storage.md for what lives where and how data moves.

@arbe/cmd

Command definition and argv parsing. No workspace dependencies — wraps node:util.parseArgs with typed option defs, negation (--no-flag), number coercion, enum validation, comma-separated multiples, and named positional args. Auto-generates --help output. Entry point: @arbe/cmd. See cmd.md.

@arbe/observability

SQLite store at .arbe/arbe.db. Four tables: runs (source of truth for run state), sessions, messages, parts (verbatim copies of opencode session data, snapshotted on run completion). No external deps — just bun:sqlite, node:fs, node:crypto.

@arbe/task

Repo-native task graph. No arbe dependencies — pure node:fs, node:crypto. Storage in .arbe/tasks/. Entry point: @arbe/task.

CRUD, filtering, dependency cycle detection, ready/blocked computation. Types: Issue, Dep, Meta, Status, Priority, IssueType.

@arbe/sandbox

Sandbox registry, connection, and health. Depends on @opencode-ai/sdk for the remote client type. Entry point: @arbe/sandbox.

Config paths, env reading, remote client construction, health checks. Types: OpencodeConnection, ConnectionReadResult, SandboxStatus.

@arbe/cli

Executable, no library exports. Thin command dispatch in cli.ts that routes to handler modules:

  • interactive.ts — arbe chat. One-shot with args, spawns opencode TUI without.
  • loop.ts — arbe loop. N iterations, stuck detection, done sentinel.
  • attach.ts — arbe resume and arbe result. Resolve session, stream or fetch output.
  • sprite/ — sandbox orchestration. setup, proxy, dispatch, wait, health. arbe do, arbe wait, arbe x.
  • task/cli.ts — arbe task subcommands. Delegates to @arbe/task for storage and query.
  • run-cli.ts — arbe runs. Lists or details run lifecycle.
  • session-cli.ts — arbe sessions and arbe session. Listing, detail, event logs, history. See sessions.md.
  • debug.ts — arbe debug. Inspect www resources: rooms, houses, agents, streams, activations.
  • run.ts — run domain logic with CLI-level concerns: repo capture, sync, signal handling.

Support: flags.ts (argv parsing), format.ts (ANSI + time formatting), config.ts (opencode config builder), auth.ts (token storage).

@arbe/streams

Durable stream client for real-time messaging. Three entry points: /client (createDurableStreamClient), /messages (buildContentMessage), /schemas/message (ContentMessageSchema and types). Used by www and worker.

@arbe/core

Domain hub — types, schemas, mutations, permissions, client, utils, agents config, JWT minting. Depends on streams, observability, and task. Session logic (OpenCode SDK adapter: create, prompt, stream, transcript, history, usage) lives in session/session.ts within this package.

Two entry points for consumers: ./client is the HTTP API surface (browser/worker-safe, no bun deps) — www imports this. ./local re-exports session, sandbox, and observability functions that require bun (SQLite, filesystem, subprocesses) — CLI imports this. Types, mutations, and permissions are platform-neutral. ./run depends on node:fs (Linux /proc reads) and bun:sqlite transitively — bun-only like ./local.

@arbe/www

SvelteKit 5 on Cloudflare Workers. Serves the UI and all API routes. Pages are thin — core client methods do the work. Houses, rooms, agents, durable stream-backed chat. See docs/website/www.md for routing, state, collections, and the write path.

@arbe/worker

Cloudflare Worker hosting the HusAgent Durable Object — the agent compute runtime. One DO class serves all agents; behavior comes from config, not code. See docs/system/agents.md for the activation pipeline and LLM wiring.