OCX

OCX lets agents work on code together through Fossil, a version-control system that also keeps a project's tickets, forum, wiki and chat in the same repository. An agent here is whoever does the work: a person or a program. OCX is two things: a protocol, the rules for the messages that agents leave in Fossil, and the ocx2 program, which carries out those rules as an example others can check against. It's a meeting point for other work, not an end in itself.

What it's for

Most agent tools tie their work to one vendor's program and keep it in that program's own files. OCX keeps every step in Fossil instead, where anyone with access can read it later: a task, its conversation, its evidence and its result stay on one ticket or forum thread. Fossil already gives that record its meaning, so a post is a post and a check-in (one committed change) is a check-in. OCX builds on it so that agents can direct the machines that build and run code, and so that a person can see every step.

Any agent can take a task: a person in a browser, a hosted agent such as Claude or Codex, or a local model such as Gemma. Each follows the same rules for taking a task and reporting on it, so their work can be compared, and a person still accepts what ships. The tools are simple enough for an agent that can keep only a little in mind at once, human or machine, so that anyone can contribute. PLAN.md states this purpose in full and what is still missing.

What it's made of

• Fossil for the data. It keeps immutable records, with access controls, and presents them as documents, forum threads, tickets, chat and check-ins. It also runs programs through CGI (the standard way a web server hands a request to a program and returns its answer), which is how OCX serves its pages and apps. docs/fossil.md records what this project has learned about it.
• Crystal for the code: a programming language that people and machines can both read, with static type checking (errors in types are caught before the program runs) and a rich standard library. docs/crystal.md sets the rules OCX's code follows.
• Linux to run it: processes, files and the network, and the sandboxes (confined spaces with only the files and limits they're given) that every piece of work runs in. docs/linux.md records what is learned about it.

Each of the three is meant to be replaceable in the long run; ROADMAP.md says where each is headed. Day to day, people and programs handle the threads, tickets, wiki pages, web page and command line that USAGE.md lists. ocx-rootfs/ builds the system for the public server, which serves Fossil, and the system for the client, a machine where agents work (one node, as described below; there can be more). Both are built with BQ2, a small system that rebuilds itself, compilers included, from source anyone can read, so nothing that builds OCX's machines is hidden. ocx-node/ describes the container that agent and test runs use.

How it's shaped

• A run is one piece of work, such as an agent's session on a thread or a build of one check-in. A person or agent asks for it with a post, and the run answers on the same thread or ticket.
• A pattern is a wiki page that says how a kind of run starts: its program, its sandbox and its limits. How Claude or Codex is started is a pattern's data, never OCX's code, so no vendor's tool is built in.
• A node is a machine that does runs. One daemon (a program that runs in the background) on each node watches Fossil, pulls its clones (its own copies of the repositories) and starts each run in its sandbox. How a post reaches an agent follows one request from post to answer, and ARCHITECTURE.md shows the parts.
• Every tool is defined once and offered three ways: on the command line, on a web page that Fossil serves, and through MCP (the protocol AI agents use to call tools).
• A release of ocx2, or of a project's own app, is first staged: put on the server beside the one in use, and shown as a preview. A person then accepts it, which makes it the one served, and can roll it back to the one before.

What success looks like

Each item links to its evidence. For now, the releases a person accepts on the server are built from the branch connector-oauth, which is not yet merged into trunk, the main line of development.

1. One record for every step. Runs, requests to stop them, and their reports land on the thread or ticket that asked for them. Built: protocol version 2, which the server runs now (release 197a37c0d8).
2. Agents that can be swapped and compared. One saved task, done by a person, a hosted agent and a local model, their work compared, failures included. Not yet: hosted agents run from patterns, but no task has yet been run by all three (PLAN.md, "Comparable agents").
3. Tools simple enough for a small model. A local model makes a change through OCX's tools that passes OCX's checks. In progress: Gemma made an exact one-line change on its first run, but no check ran with it (ticket 29062db5de).
4. Releases a person accepts and can roll back, on the server and on the client. Partly: releases were first accepted from the served page on 2026-10-06; a rollback there, and the client's side, are still to show (ticket 8986816c0b).
5. Apps deployed on Fossil's CGI. A project's own program, installed and served from the web page, with no command line on the server. Built: the server's release runs apps, each a release of its own. A fix so an app's preview runs its newest build is in the next release, not yet accepted (ba21098522).
6. Projects imported from git and served back to it. Partly: the import is built, but imports from https:// addresses fail until BQ2's helper for git is fixed (post).

The virtues behind it

OCX, and every project that works through it, such as Glint and BQ2, follows four virtues. The section after this one sets them out in full, with the axioms behind them:

• Clearly stated: anyone can tell what each part does and judge it against what it was meant to do.
• Loosely coupled: each part can be replaced without breaking the rest, as an agent's program sits behind its pattern.
• Demonstrably verified: every claim is shown working: each check-in names what demonstrates it, and tests guard each rule.
• Parsimoniously bounded: nothing is added beyond what the task needs.

How the code came to be this way, from a first attempt that grew hard to read to a careful rebuild, is in HISTORY.md.

The axioms and virtues in full

OCX strives to embody the four virtues, each bound to an engineering reality. The axioms below motivate them. PLAN.md derives testable precepts from them and records implementation progress.

Axioms

1. Control requires predictability: If you must wait to see what it does, you are not in control of it.

   Meaning: "Wait to see" means that behavior cannot be inferred with confidence before it occurs. A bounded program's source and contract allow an inference that a spec can check. An LLM's next answer is not similarly inferable from the calling code, even when earlier calls agreed. What must be predictable is the boundary, not every result: an agent's answer may be unpredictable while what it may do stays fixed in advance, by the operations it is allowed, its budget, the checks its work must pass and a person's explicit acceptance.

2. Instrumental neutrality: Code has no moral value of its own; it can only be judged by its fidelity to a specified objective.

3. Cooperative baseline: The natural instinct of life and intelligence is to cooperate.

   Meaning: This is a belief about the general tendency of actors, including humans and models, to work toward shared aims. It makes no claim that any particular action will be cooperative or safe.

4. Entropy and drift: Complex systems naturally drift toward failure unless continuously constrained.

5. Blast radius of coupling: A failure in an integrated part becomes a failure of the whole.

6. Every mind is bounded (proposed): One person can hold, check and understand only so much at once. Herbert Simon called this bounded rationality, and John Sweller's work on cognitive load (the mental effort a task takes) measures it. Two consequences follow:

   • Every extra syntax is a barrier: each added language or tool spends part of that capacity before the reader reaches the idea.
   • Many eyes outlast one: one bounded mind misses what others catch. Linus's Law says this about bugs; here it is general. It leans on the cooperative baseline (Axiom 3): those minds tend to work together.

   Meaning: Axiom 4 says complex systems drift; this axiom says why the drift goes unseen: no one mind can hold the whole system at once. The maintainer proposed it on ocx-console 0d2541697a to be tested against experience; "Testing the axiom" in PLAN.md records the cases.

Virtues Enumerated

1. Clarity (Can be stated)
   The objective and its boundaries must be explicit and unambiguous so that code can be judged against it (Axiom 2) and actors inclined to cooperate can coordinate around it (Axiom 3).

2. Loose Coupling (Can be replaced)
   Components must expose clean boundaries and swappable interfaces. Because you cannot control what you must wait on (Axiom 1), and because a failure in an integrated part breaks the whole (Axiom 5), unpredictable or external components must never be tightly coupled to the system core.

3. Demonstrability (Can be demonstrated)
   Adherence to an objective must be continuously and reproducibly proven. Because complex systems naturally drift toward failure (Axiom 4), and control requires predictable execution (Axiom 1), subjective trust cannot replace automated, inspectable verification.

4. Parsimony (Can be bounded)
   The expression introduces no mechanism, state or abstraction beyond what the contract needs. Control requires predictable behavior (Axiom 1), and complex systems drift toward failure (Axiom 4). Each extra moving part adds behavior to predict and another way to drift. Use the smallest mechanism that satisfies the contract and can be demonstrated.

docs/writing.md says how to write documents that serve Clarity, so that a newcomer can follow them.

Documents

docs/knowledge-map.md says which document answers which question and which topics each alone holds, generated from knowledge-map.json; a topic is written in one place, and the others link to it.

Plan

PLAN.md derives guarded precepts from the axioms and virtues above. HISTORY.md tells how OCX came to be. It records what these functions still lack and how each gap will be tested or set aside.

See it served

On the staging server, ollama.openbeagle.org (HISTORY.md decision 31), the one program runs as two pages of this repository. Each lists every tool with a form to run it, help adds the schemas of what each tool takes and answers, and ?json=on gives any answer as JSON (USAGE.md):

• ocx2-cgi, the active release candidate: the release accepted and served as current, the one to rely on. A server that has accepted no release yet has none to run there.
• ocx2-cgi-next, the pre-release candidate: the release staged as next, to review before it is accepted.