Ollama-Codex: What the maintainer has said to keep

The maintainer's standing directions on how OCX is designed and built, in their own words, each with where it was said. Every session reads this first (AGENTS.md). A change that goes against one of these needs the maintainer's word on the record first. Quotes are verbatim; a line marked "agent's words" is not a quote.

Structure the data, and the processes fall out of it

2026-10-13, at the terminal: "if the data is structured properly, the processes should just fall out of it." And: "I'm asking for data-driven programming as a way to keep the code simple." The reference example the maintainer gave is crystal-robots' parser (https://ollama.openbeagle.org/crystal-robots/file?name=src/compiler/parser.cr&ci=tip): the language is three tables, the order of a table carries meaning, and two small engines read them without naming any construct (agent's words).
2026-10-13, at the terminal: "I keep trying to drive you into solidifying simple, reusable patterns, but you keep going back to spewing out more and more incomprehensible code."
Decision 41 (2026-10-12): "don't put into code what is just data."
Decision 40 (2026-10-12): "there shouldn't be anything claude or codex specific in the CODE"; "I do want claude and codex specific TESTS, but not in our source code today".
Decision 40 (299410275b, 2026-10-12): "Just let the OCX message dictate the life of the session ... That's just a usage pattern and doesn't need to live in the code at all. It is just data."
c6e8607e39 (2026-10-13): "The OCX message itself should be written fully expanded to make it as clear as possible"; 2f97a190d5 (2026-10-13): "yes to fully expanded".
485bbd7e69 (2026-10-12): "keep the wiki assistance to help with the data patterns"; "the argument should take a URL to fetch a defined JSON block as a starting default".

Why ocx2, and where it is going

2026-10-13, at the terminal: "yes, indeed, trunk worked pretty well. I don't even remember what triggered me to rebuild. Mostly, the code was just hard to read and I think I hit the wall trying to get some features to work with Stone, but it was the corruption that kept happening that led to the improved sandboxing we have now where agents can freely write to the database because the synchronization is a separate step. Way safer on the database."
2026-10-13, at the terminal: "It would make me so happy if we could lock this up and get back to feature parity, but with an improved design and easier to read code."
f580dbd090 (2026-10-03): "the trunk sse serve design was pretty good."

The message definition comes first

2026-10-13, at the terminal: "The damn OCX message definition should include this stuff and it should have gone through all the heavy reviews."
2026-10-13, at the terminal: "let's please, please, please just define the lowest-level possible OCX protocol."
c6e8607e39 (2026-10-13): "OCX message definition and implementation shouldn't be targeting processes that don't end up with writes to Fossil."
2026-10-14, at the terminal: "Get a clean wrap-up of the OCX protocol v1, making it really clear as to the value of what we've defined--what real-world problems it solves for us--and make sure it is really stable. Extensible, but stable."
2026-10-14, at the terminal: "the Value comes from how well it serves our Virtues."
2026-10-14, at the terminal: "everything that you are re-writing, make sure it justifies itself. There should be single surfaces for editing."
2026-10-14, at the terminal: "if you have a question about scope, be sure to bring it to me."
2026-10-14, at the terminal: "let's not equate the OCX protocol v1 definition to the entirety of the project. Rather, put the protocol in perspective with the rest of the project."
2026-10-14, at the terminal: "It seems a massively needed and super, super fundamental feature of using locally hosted models is still very much left out of the architecture and parity discussion. ... Our rearchitecture is still very focused on how we enable lower-functioning agents".
2026-10-14, at the terminal: "AGENTS.md needs to point to KEEP.md. Make sure every document is linked. Doc mentions should be links. Need a knowledge-map.json to give agents a good overview and knowledge delineation so that we stop putting the same information in multiple places."
2026-10-14, at the terminal, on agents sending builds: "if this protocol doesn't allow agents to communicate with this backplane, what is it for?"; "I'm not asking you to back down on your principles. I'm just asking that you make things easy."; of an inbound pattern: "run/mcp-tunnel is the way to make a proxy to a remote agent."
2026-10-14, at the terminal: "I would encourage using tech-notes for future test records so that they don't clutter the workspace. ... I agree they are very valuable as original evidence and keeping them indexed provides justification for our current design (or perhaps a better version of it)."

Simplify, and remove what has no use

87d697dffd (2026-09-26): "you should always look to simplify."
72593caa3d (2026-10-03): "i am asking you to challenge and work to simplify our design, using as much of what fossil already provides when we don't need to reinvent it."
043c3bee1b (2026-09-24): "the just build-and-build approach is making crap."
485bbd7e69 (2026-10-12): "If there's other stuff in the code, I don't know what it is and you'll need to justify it to me."
479d0c60f9 (2026-10-08): "if I don't know when i would use the tool command, it ultimately needs to be pruned."
PLAN.md (2026-10-08): "just remove it. the discipline should be around adding any features without a use case. oh, testing is a valid use case, especially if it demonstrates a tool."
Decision 39 (2026-10-12): "Please, have the hook stick to the list of artifacts it was given unless you have a better reason not to do so. Parsimony."
ac150c4ae0 (2026-10-03): "please don't fall back to unnecessary special cases by strict interpretation of ineffective guards."

Keep

485bbd7e69 (2026-10-12): keep "the cgi/cli/mcp tool interfaces (including create to write the message), the testing for the precepts, the release image management (stage, accept, and rollback), the tag helper (audit), the hook installer/uninstaller, the import/export tools with hook, the basic debug/help tools (list, help, status, and echo), the session/cgi-based run tool (run) and some mechanism for a session to wait on new artifacts and respond".
Manual runs, 466b4822e7 (2026-10-11): "remember there is a difference between creating the run record and using the definition to perform a manual in-shell run. the cli/cgi should be able to do both." 2026-10-13, at the terminal: "Manual runs are needed for bring-up and debug. Stop trying to remove them."
Subscriptions, 2026-10-13, at the terminal: "Subscriptions to check-ins, forum posts and ticket comments are needed to feed STDIN when not using attach." 2026-10-09: "the ability to filter on sender is good, just it should be an option."
Sessions and runs to completion, 2026-10-09: "some processes should run to completion, like a ci run, and others should detach, like an agent run that will take inputs to continue the same process."
audit, 2026-10-13, at the terminal: "audit is all I know to use and it is simple."
Nodes on other hosts, 2026-10-13, at the terminal: the reason for the review of the message definition was to add the build machine and lab boards as nodes.
7fcdcca8bf (2026-10-03): "scripts/ should not be lost or integrated. they need to read clean."

Fossil is the abstraction, in Fossil's words

Decision 25 (2026-09-23): "Fossil is our abstraction to the storage wherever it can handle it".
b3c1f11f59 (2026-09-24): "Fossil is the data. The wiki describes the data."
2e75b94342 (2026-10-11): "use fossil terminology wherever it can be used."
2026-10-07: "I want to approve every new term".
Words the maintainer approved for the protocol, 2026-10-13 ("the terminology in 13 seems mostly fine to me. I appreciate you avoiding the conflicting terminology and hope you make the right notes to make it stick"): layer, envelope, value (written $$name$$), step (one action of the workspace layer; never "tool", which names OCX's commands), process, in its care, works for, kept logs; and "manual run", a run whose process waits until a person starts it, its field manual (true or false). The maintainer, 2026-10-13, of when with immediately and manually: "I hope you can find better words than I did there. I don't like them in that reading/context at all." See docs/protocol-v1.md, section 13.
c28028fbd5 (2026-10-12): "the protocol of 'ocx message' should not be defined in the glossary. the term should be defined, not the actual protocol."
c6e8607e39 (2026-10-13): "It hasn't been made clear to my why the identifiers provided by fossil aren't sufficient to define a node." Still open.

Restrictions, the sandbox and the environment

25e4422aa1 (2026-10-11): "it should not be required for a node to implement them or a record to require them. the node should be smart enough not to run the record request if it can't provide the restrictions requested".
4e87952652 (2026-10-11), on the batch "Runner, Subscription and Limits": "go ahead with the next batch"; "try to not add undue restrictions that are easily handled."
2026-10-13, of moving env and the budget out of the sandbox object below: "my previous sandbox object approval was just tentative as it looked reasonable. getting it implementable and at the right layer is more important." The promoted protocol (HISTORY.md decision 44) has them in the process and limits layers.
The approved sandbox, 62e45fcde6 (stone, 2026-10-08): the run's own sandbox object, written fully expanded: network, read_only and read_write (host paths), homes (sign-in files bound into the workspace), env (the whole environment, PATH among it, with OCX's release directory on PATH and read-only so its tools work inside), and budget; beside it the run's command, such as ["claude", "--remote-control"]. 2f2c0068cc (2026-10-07): "I'd prefer if the OCX Record is written by the command-line that it would get expanded to the full environment variables, read-only paths, read-write paths, etc., a bit more like they were on the previous "ocx" branch."
2f2c0068cc (2026-10-07), on when a run starts and what it is given: "I think it is more a matter of when, which is immediately ("hook"), manually ("hand") or on some event"; "we'll want to filter which records get turned into inputs and if those start the process or simply message to it."
2f2c0068cc, on a shell in a run's sandbox: "including a command is necessary, but it should be treated as a default for invocations, allowing for other commands to be invoked from the CLI"; "ocx2 run OCX-RECORD -- /bin/sh or ocx2 run OCX-RECORD --shell would be fine"; "ocx2 run OCX-RECORD should run the provided command"; "the result should go into a forum post as a reply to the OCX-RECORD post (or a ticket comment for the associated ticket if OCX-RECORD is a ticket comment)".
2f2c0068cc, on the workspace: "I thought it could have been done with that same create command or done as needed when the OCX Record is run (if it doesn't yet exist)."
2026-10-13, at the terminal: these sandbox and limits parameters belong in the message, and are deferred so they do not hold up the basic protocol and the workspace setup. Later the same day: "start the definition rewrite as tables and consider how you can put in our workspace definition into the definition rewrite along with the sandboxing and limits, moving them to the right level"; "Let's not allow any silent adds--I liked your macro usage better to pull up system-provided values into the message."
c6e8607e39 (2026-10-13): "Each variable should be strictly monitored, but I think a few are actually necessary, like PATH, HOME and maybe USER, no?"
a079dce491 (2026-09-26): "sharing a clone between agents should absolutely never be considered. clones and workspaces should be kept cheap."

Code

da9b54d909 (2026-10-07): the Fossil module should have methods that "describe the actions", not a Fossil.run that "doesn't capture the intent of the method".
236e40d65b (2026-10-04): "agents continue to not get to know the crystal standard library."
834ceded37 (2026-10-10): "provide a value-aligned extension to Fossil, using Crystal, to collaborate with agents in ways that makes them efficient and tolerates lower reasoning. The axioms should hold or be challenged. The functionality should be justified by the values."
HISTORY.md, "What to keep": "the 400-line-per-file limit was also helpful."

Working with the maintainer

e75e2aa192 (2026-09-23): "I need questions, and there are open questions, dealt to me one at a time."
2026-10-13, at the terminal: "Please use PRECISE LANGUAGE with me, WITHOUT JARGON, WITH BREVITY".
2026-10-13, at the terminal: "Why can't I be heard? why do I have to keep saying this crap over and over and over."