OCX

OCX is a coding workbench that coordinates agents, human or model, over Fossil using Crystal.

ocx-node/ describes the container node for agent and CI runs. ocx-rootfs/ builds, starts and tests the public server and the client from a BQ2 seed.

Its architecture is governed by four core virtues designed to prevent failure: each part must be clearly stated, loosely coupled (replaceable), demonstrably verified, and parsimoniously bounded.

Fundamental building blocks

While the long-term goal is to make each of these building blocks replaceable, including fossil, crystal, and linux, they are seen as good working blueprints of a system that humans and machines can use to work together efficiently to solve problems computers are good at solving. ROADMAP.md says where each is headed, in this project and beyond it; docs/fossil.md, docs/crystal.md and docs/linux.md record what this project has learned about each.

Fossil

Fossil is the language for the data. It provides immutable records and interfaces for working with that data, including access controls and semantic context around the data—such as documentation presentation (Markdown/Pikchr), threaded conversation (Forum), live ephemeral chat, check-in code changes with tagged state, and many other features targeting data management useful for the development of code.

Crystal

Crystal is the language for the code. It provides a human- and machine-readable procedural programming language with static type checking and a rich standard library.

Linux

Linux is the operating system that exposes the features of the computer for running procedural code. Dependencies are kept to a minimum, but currently include process definition, file system access, and network access, including sandboxing of those resources.

Virtues

This coding workbench strives to embody specific coding virtues bound to engineering realities. The axioms below motivate those virtues. 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.

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.

What OCX is, in four questions

What is it for? Getting coding work done by people and agents together, with every step kept on a Fossil record that anyone with access can read later. A task, its conversation, its evidence and its result stay on one ticket or thread; each change says what it intends and what demonstrates it; people, CLI agents and local models work to the same contract, so their work can be compared; and a person accepts what ships. PLAN.md states that purpose, what is still missing and when it is done.

What is it made of? Fossil for the data, Crystal for the code and Linux for running it, as the building blocks above describe; and, day to day, the artifacts, pages and files that people and programs handle: threads and tickets holding OCX messages, the wiki pages that hold patterns, workspace directories, the web page and the command line. USAGE.md lists each one.

How is it put together? Fossil keeps the record; one daemon on each agent machine pulls its clones and starts a watcher for each run, as How a post reaches an agent explains. ARCHITECTURE.md shows the parts, whose requests they act on and how each watcher runs the work within its sandbox and limits.

What brought it here? A first attempt, a large first line of code that became hard to read, a careful rebuild and a human review of its principles, each driven by what failed before. HISTORY.md tells those events, the decisions taken and what to keep from 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.