README
¶
Arbos
Arbos is a coding harness, with memory, and a website.
Install
curl -fsSL https://arbos.life | bash
Usage
arbos . # open the web UI for this directory
# or
arbos # run in the terminal (TUI)
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
arbos
command
Command arbos is the pi coding agent.
|
Command arbos is the pi coding agent. |
|
forest
command
Command forest runs a forest head (ADR-0034): the registry + relay that arbos nodes join with --forest.
|
Command forest runs a forest head (ADR-0034): the registry + relay that arbos nodes join with --forest. |
|
gen-tool-schemas
command
Command gen-tool-schemas generates JSON Schemas for a tool package's tools by reflecting their argument structs, and writes them as committed Go source (ADR-0004).
|
Command gen-tool-schemas generates JSON Schemas for a tool package's tools by reflecting their argument structs, and writes them as committed Go source (ADR-0004). |
|
head
command
Command head runs the arbos.life account backend: non-KYC, agent-first accounts with a prepaid balance, scoped API keys, and an OpenAI-compatible inference gateway that meters and forwards to OpenRouter.
|
Command head runs the arbos.life account backend: non-KYC, agent-first accounts with a prepaid balance, scoped API keys, and an OpenAI-compatible inference gateway that meters and forwards to OpenRouter. |
|
examples
|
|
|
bubblesort
command
|
|
|
internal
|
|
|
agent
Package agent is the composition layer above the leaf ports: an Agent runs a Task and streams KernelEvents, and delegation is one agent invoking another as a child parameterized by a Grant (tools + environment + budget).
|
Package agent is the composition layer above the leaf ports: an Agent runs a Task and streams KernelEvents, and delegation is one agent invoking another as a child parameterized by a Grant (tools + environment + budget). |
|
agent/pi
Package pi assembles arbos's first-class in-house coding agent ("pi"): a coding-tuned configuration of the kernel built from the existing ports.
|
Package pi assembles arbos's first-class in-house coding agent ("pi"): a coding-tuned configuration of the kernel built from the existing ports. |
|
ask
Package ask is the agent's structured question to the user: a tool that pauses the turn, puts multiple-choice questions on screen (Cursor's AskQuestion), and returns the user's selections as the tool result.
|
Package ask is the agent's structured question to the user: a tool that pauses the turn, puts multiple-choice questions on screen (Cursor's AskQuestion), and returns the user's selections as the tool result. |
|
browser
Package browser drives a real Chromium over the Chrome DevTools Protocol (chromedp) so the agent can render and act on pages a plain HTTP fetch can't: a JS-rendered localhost dev site, a screenshot the model actually sees, a click or a form fill.
|
Package browser drives a real Chromium over the Chrome DevTools Protocol (chromedp) so the agent can render and act on pages a plain HTTP fetch can't: a JS-rendered localhost dev site, a screenshot the model actually sees, a click or a form fill. |
|
compaction
Package compaction provides the reference ports.ContextPolicy: a token-budget policy that folds the oldest whole turns once the projected conversation exceeds a threshold, keeping the most recent turns intact.
|
Package compaction provides the reference ports.ContextPolicy: a token-budget policy that folds the oldest whole turns once the projected conversation exceeds a threshold, keeping the most recent turns intact. |
|
control
Package control is the kernel's headless control seam: a newline-delimited JSON protocol that carries Intents in and Envelopes out over any io.Reader/io.Writer (stdio, a Unix socket, a WebSocket shim).
|
Package control is the kernel's headless control seam: a newline-delimited JSON protocol that carries Intents in and Envelopes out over any io.Reader/io.Writer (stdio, a Unix socket, a WebSocket shim). |
|
core
Package core holds the kernel's foundational data types: the event log, the conversation projection, and the intent/event vocabulary that flows in and out of the engine.
|
Package core holds the kernel's foundational data types: the event log, the conversation projection, and the intent/event vocabulary that flows in and out of the engine. |
|
engine
Package engine is the kernel turn loop.
|
Package engine is the kernel turn loop. |
|
envfile
Package envfile loads simple KEY=VALUE .env files for local dev.
|
Package envfile loads simple KEY=VALUE .env files for local dev. |
|
extension
Package extension is arbos's Go-native equivalent of pi's self-extensible plugin system.
|
Package extension is arbos's Go-native equivalent of pi's self-extensible plugin system. |
|
extension/builtin
Package builtin registers sample extensions that ship with arbos.
|
Package builtin registers sample extensions that ship with arbos. |
|
fake
Package fake provides deterministic in-memory implementations of every port.
|
Package fake provides deterministic in-memory implementations of every port. |
|
forest
Package forest is the network of arbos nodes (ADR-0034): the head side — a self-hostable registry + relay that gives each joined node an ephemeral public URL — and the node side, a client that registers a device identity, leases a name, and serves its gateway back through an outbound tunnel.
|
Package forest is the network of arbos nodes (ADR-0034): the head side — a self-hostable registry + relay that gives each joined node an ephemeral public URL — and the node side, a client that registers a device identity, leases a name, and serves its gateway back through an outbound tunnel. |
|
gateway
Package gateway is the browser door onto the kernel: an HTTP server that carries the control seam over WebSocket (one connection = one control.Serve, frame-per-message) and serves the built web UI.
|
Package gateway is the browser door onto the kernel: an HTTP server that carries the control seam over WebSocket (one connection = one control.Serve, frame-per-message) and serves the built web UI. |
|
head
Package head is the arbos.life account backend: non-KYC, agent-first accounts with a prepaid balance, scoped API keys, and an OpenAI-compatible inference gateway that meters and forwards to OpenRouter (Chutes and other upstreams later).
|
Package head is the arbos.life account backend: non-KYC, agent-first accounts with a prepaid balance, scoped API keys, and an OpenAI-compatible inference gateway that meters and forwards to OpenRouter (Chutes and other upstreams later). |
|
mcp
Package mcp is a minimal Model Context Protocol implementation over stdio JSON-RPC 2.0: a client that maps an external MCP server's tools into an arbos ports.ToolRuntime, and a server that exposes an arbos ToolRuntime to external MCP runtimes.
|
Package mcp is a minimal Model Context Protocol implementation over stdio JSON-RPC 2.0: a client that maps an external MCP server's tools into an arbos ports.ToolRuntime, and a server that exposes an arbos ToolRuntime to external MCP runtimes. |
|
messenger
The phone's half of the ask tool (suspend-and-await questions, ADR-0018).
|
The phone's half of the ask tool (suspend-and-await questions, ADR-0018). |
|
mind
Package mind is the agent's memory: one global set of atoms (durable comprehensions) plus the two operations over it — Recall and Curate.
|
Package mind is the agent's memory: one global set of atoms (durable comprehensions) plus the two operations over it — Recall and Curate. |
|
modelcatalog
Package modelcatalog fetches the provider's live model catalog — the OpenAI-compatible {base}/models listing OpenRouter and the OpenAI API both serve.
|
Package modelcatalog fetches the provider's live model catalog — the OpenAI-compatible {base}/models listing OpenRouter and the OpenAI API both serve. |
|
obs
Package obs holds observability primitives: turn correlation IDs and the redacting slog handler used by every pi host entrypoint.
|
Package obs holds observability primitives: turn correlation IDs and the redacting slog handler used by every pi host entrypoint. |
|
outbox
Package outbox is the agent's voice when no conversation is open: durable messages to the user, delivered into the conversation that created them.
|
Package outbox is the agent's voice when no conversation is open: durable messages to the user, delivered into the conversation that created them. |
|
plan
Package plan is the agent's intent: the durable forest of goals it is pursuing, and the operations over it.
|
Package plan is the agent's intent: the durable forest of goals it is pursuing, and the operations over it. |
|
ports
Package ports declares the kernel's outbound interfaces (hexagonal "ports").
|
Package ports declares the kernel's outbound interfaces (hexagonal "ports"). |
|
ports/porttest
Package porttest provides reusable contract test suites for the kernel ports.
|
Package porttest provides reusable contract test suites for the kernel ports. |
|
provider/anthropic
Package anthropic is a native ports.LLMProvider for Anthropic's Messages API (the second real provider beyond the OpenAI-compatible one).
|
Package anthropic is a native ports.LLMProvider for Anthropic's Messages API (the second real provider beyond the OpenAI-compatible one). |
|
provider/google
Package google is a native ports.LLMProvider for Google's Gemini generateContent streaming API.
|
Package google is a native ports.LLMProvider for Google's Gemini generateContent streaming API. |
|
provider/internal/providerkit
Package providerkit holds the machinery shared by every ports.LLMProvider adapter (openai, anthropic, google): the SSE read loop, channel send with ctx, an error-snippet reader, the streamed tool-call accumulator, and the Base struct + options for the duplicated Provider plumbing (name, http client with redirect refusal, auth).
|
Package providerkit holds the machinery shared by every ports.LLMProvider adapter (openai, anthropic, google): the SSE read loop, channel send with ctx, an error-snippet reader, the streamed tool-call accumulator, and the Base struct + options for the duplicated Provider plumbing (name, http client with redirect refusal, auth). |
|
provider/openai
Package openai is the reference LLMProvider: an adapter for any OpenAI-compatible Chat Completions endpoint (OpenAI, OpenRouter, vLLM, Ollama, most aggregators).
|
Package openai is the reference LLMProvider: an adapter for any OpenAI-compatible Chat Completions endpoint (OpenAI, OpenRouter, vLLM, Ollama, most aggregators). |
|
recall
Package recall gives the agent a window onto its other sessions: the user's past chats and the agent's own autonomous runs (scheduler / Ralph-loop iterations).
|
Package recall gives the agent a window onto its other sessions: the user's past chats and the agent's own autonomous runs (scheduler / Ralph-loop iterations). |
|
secret
Package secret turns SecretRefs into outbound credentials at the trusted boundary and binds each secret to the destination hosts it may reach.
|
Package secret turns SecretRefs into outbound credentials at the trusted boundary and binds each secret to the destination hosts it may reach. |
|
sessiontree
Package sessiontree implements pi's session-tree fork over any ports.SessionStore.
|
Package sessiontree implements pi's session-tree fork over any ports.SessionStore. |
|
setmodel
Package setmodel is the agent's hand on its own model selector: a tool that switches the current session's model and can persist the choice as the host's default for future sessions.
|
Package setmodel is the agent's hand on its own model selector: a tool that switches the current session's model and can persist the choice as the host's default for future sessions. |
|
settings
Package settings is the host's durable preference file: the small set of agent-behavior knobs the Settings tab edits and every door (web, TUI, one-shot, serve) reads at assembly.
|
Package settings is the host's durable preference file: the small set of agent-behavior knobs the Settings tab edits and every door (web, TUI, one-shot, serve) reads at assembly. |
|
share
Package share is the capability model behind shareable links.
|
Package share is the capability model behind shareable links. |
|
sqlite
Package sqlite is the durable ports.SessionStore: an append-only event log on modernc.org/sqlite (pure Go, no cgo) so the kernel stays a single static binary.
|
Package sqlite is the durable ports.SessionStore: an append-only event log on modernc.org/sqlite (pure Go, no cgo) so the kernel stays a single static binary. |
|
theme
Package theme is the single source of truth for arbos's color palette.
|
Package theme is the single source of truth for arbos's color palette. |
|
tool
Package tool provides the ports.ToolRuntime implementation the kernel uses: a registry of named tools with typed handlers and build-time-generated JSON schemas (ADR-0004).
|
Package tool provides the ports.ToolRuntime implementation the kernel uses: a registry of named tools with typed handlers and build-time-generated JSON schemas (ADR-0004). |
|
tool/coding
Package coding assembles pi's coding tool runtime: it pairs each spec from codingspec with its generated JSON schema and registers them into a tool.Registry.
|
Package coding assembles pi's coding tool runtime: it pairs each spec from codingspec with its generated JSON schema and registers them into a tool.Registry. |
|
tool/codingspec
Package codingspec declares pi's coding toolset: argument structs, handlers, and metadata, rooted at a working directory (a starting point, not a boundary — paths resolve anywhere, see tool.Resolve).
|
Package codingspec declares pi's coding toolset: argument structs, handlers, and metadata, rooted at a working directory (a starting point, not a boundary — paths resolve anywhere, see tool.Resolve). |
|
tool/jsonschema
Package jsonschema derives a JSON Schema from a Go argument struct.
|
Package jsonschema derives a JSON Schema from a Go argument struct. |
|
trajectory
Package trajectory is the one home for a session's machine-readable export shape.
|
Package trajectory is the one home for a session's machine-readable export shape. |
|
transcript
Package transcript renders kernel tool events into compact, human-readable labels.
|
Package transcript renders kernel tool events into compact, human-readable labels. |
|
Package web embeds the built browser UI so the single arbos binary serves it with no extra files on disk: `arbos -web :8420` just works.
|
Package web embeds the built browser UI so the single arbos binary serves it with no extra files on disk: `arbos -web :8420` just works. |
Click to show internal directories.
Click to hide internal directories.