Documentation
The reference shelf.
Every page here renders the same markdown maintainers read in the repository — one source, two doors. Working notes and pilot data stay in the repo.
Start here
- Native prerelease distributionThe native process VM can run without Bun, Cargo, or a repository checkout. Binary packages are qualified on two targets:
- Try the native VMThe native workbench is a complete local demonstration of durable approval, restart, exact effect recovery, and portable evidence. It uses one algal executable. Bun, Cargo, a repository checkout, credentials, and a web s
- Readable Algal sourceThe Bun CLI and SDK compile .algal source into the existing algal.organism.v1 manifest. Compilation makes no model calls, executes no host code, and requires no provider credentials. Both runtimes execute the compiled JS
- The ALGAL process VMFor a one-binary hands-on tour with a passive HTML workbench and actual SIGKILL proofs, start with the native workbenchnative-workbench.md.
Concepts
- What distinguishes ALGALALGAL's useful combination is a typed program format, bounded execution, content-addressed evidence, and portable process checkpoints. A manifest is JSON data: the host can inspect, hash, compose, generate, and admit it
- ALGAL: language, harness, habitatALGAL is the new product name for Algal, with a nod to ALGOL. The useful unifying object is a program with bounded authority and retained evidence. An organism is the program; a coding-agent session is one host applicati
- Design notesAn agentic workflow has two kinds of decisions. The ones that can be decided statically — routing, what context a step may see, how much work is allowed — belong in structure. The ones that need judgment belong in bounde
- Organisms and agent loopsALGAL organisms are themselves bounded agent loops. The interesting question is how they relate to the larger agent loop that deploys them: when do you compile a piece of agentic behavior into an organism, and when do yo
- ALGAL: programmable organismsBuild program, 2026-09-20. This expands the coding-harness memory spike into a reusable application architecture. The harness remains the first demanding user of that architecture and a continuing evaluation surface.
- ExecutorsAgent, classifier, and gate cells never reach a provider directly. Each activation emits a algal.effect.v1 request; the host's executor answers it. ALGAL owns the schedule, the bounds, and the receipt — the executor owns
- Program diagramsDiagrams are derived views of algal.organism.v1 manifests. The diagram contract is algal.diagram.v1; it carries the manifest digest, exact cells and edges, declared budgets, typed ports where known, and optional recorded
- Durable coding repairsThe repair host turns a coding-agent result into an inspectable, tested patch. The VM waits for the result, records validation, and verifies the episode offline. The host selects a clean checkout, the xcb executable and
Life and selection
- Habitats, self-reproduction, and civilizationThere is a deeper shape hidden inside ALGAL: not just a workflow runner, but a substrate for organisms that live, reproduce, and evolve in a shared runtime. This is not yet fully built, but the v1 contract already contai
- ALGAL CivilizationALGAL is not just a workflow runtime. It is a substrate for a new kind of programming: civilization software. Programs are organisms, organisms are data, and a host can evolve a population of them by selecting, composing
Applications and workflows
- Practical workflows with the ALGAL VMUse ALGAL for a bounded piece of agent work whose decisions must outlive a CLI invocation and whose execution must remain inspectable. The useful result is a retained proposal, checked patch, ordered set of replies, or v
- When ALGAL is usefulALGAL is useful when a workflow has stable structure around a few uncertain judgments: gather evidence, ask a narrow question, check the result, wait for authority, then act. Its program format makes that structure inspe
- Adaptive inventory applicationThis executable example applies ALGAL's application lifecycle to inventory observations and replenishment decisions. It uses actual bounded file probes, the native query engine and replay verification. Proposals are auth
- ALGAL as an agent toolA ALGAL organism is a content-addressed, replayable subroutine. Pack it once and any agent—OpenAI, Anthropic, a coding agent, or a shell script—can call it as a typed tool and receive a compact, verifiable result.
- Coding-harness pilotThe completed first pilotcoding-harness-pilot-results.md records the live development/proposal/frozen-holdout results and limitations. It established the integration path but no task-solving or policy-search benefit.
- Recover a retained coding outcomeA provider can finish a repair even when its caller never receives the final response. Algal can recover that result only when an admitted adapter durably identifies the operation and can retrieve its exact terminal outc
- PR and CI shepherdThe shepherd runs a finite PR observation workflow in the process VM. A mailbox event admits a GitHub observation. Pending CI suspends the process until a durable host timer or an explicit event wakes it. It produces a r
Specification
- algal.organism.v1The organism manifest contract. A manifest is data: it can be checked, canonicalized, hashed, and embedded. It never carries host code — the only programs it may carry are bounded, contract-owned ones algal.expr.v1, inte
- algal.expr.v1The bounded pure expression contract. An expr program is manifest data: canonical JSON that a contract-owned evaluator interprets under a fuel meter — never host code, never an effect, never ambient authority. One implem
- algal.foundry.v1A foundry report is content-addressed evidence for selecting one bounded organism population. It records no wall-clock values and contains no executable code.
- algal.search.v1A search report records bounded, validation-guided evolution over organism manifests. Search is a host layer over ordinary generator organisms and algal.foundry.v1 evidence; it adds no executable manifest primitive or au
- algal.bench.v1A bench report records one workload measured by several systems. A system is an admitted organism manifest plus a host-resolved executor list — so "one cheap call", "one frontier call", and "a decomposed organism with a
- Local mailbox admission and retained deliveryBoth runtimes use the existing algal.mailbox.v1, capability, message and delivery records. Mailboxes retain immutable message claims and move pending delivery markers into consumed when receiving. This local filesystem s
- algal.process.v1The local durable supervisor contract shared by the TypeScript and Rust CLIs. It wraps an algal.organism.v1 execution in a named, generation-bounded process. This is a filesystem ABI and lifecycle contract, not OS isolat
- algal.process-evidence.v1A portable, bounded snapshot of one process's immutable execution history. An exporter captures a fixed head, validates its chain and completed receipts, and records the source-store dependencies needed for replay. Verif
- Process recovery journalThe optional algal.process-journal.v1 sidecar adds recovery within one algal.process.v1 dispatch. It does not change process records, ordinary run receipts, or the rule that tick/schedule never reissue uncertain work. Re
- Application state, evidence, and revision boundariesThis contract joins the organism VM, scoped memory, and durable host supervision. It specifies local cooperating hosts using the retained SQLite custody protocol. An application is not an operating-system sandbox, distri
- Foreground coding jobsThis document specifies the unchanged v1 xcb host contract. The additive v2 operation-job contractcoding-job-v2.md applies only to explicitly admitted operation adapters; it cannot migrate or reconcile an existing v1 job
- Coding jobs with exact operation reconciliationalgal.coding-job.v2 extends the Bun CodingJobService with explicit operation adapterscoding-operation.md. It provides one submission followed by optional exact read-only lookup. It does not change the portable VM journal
- Coding operation adapter protocolalgal.coding-operation.v1 is the provider-neutral host boundary implemented by src/coding-operations.ts. It separates one admitted submission from exact, read-only observation of its retained outcome. It is not a portabl