One Go runtime for agent work, typed tools, shared knowledge and observable experiments.
Take the tour · What is CSF · North star · Why CSF · Proofs · Architecture · Quick start · CSF guide · Agent instructions · Citation
If you are reading this cold, here is the whole idea in three measured sentences, each term defined the first time it appears.
CSF is one Go process — a single program written in the Go language — that
holds the tools, records, schedules and experiments around an agent (a
program that works a software ticket on its own). A compiler named csfc
checks the code against a written declaration of what the system is and
generates what used to be hand-written. The harness is the part of that
process that runs agent sessions behind a gate — a check on every shell
command and every commit.
One real example, measured: on 2026-10-02 a miner found that 64 of the 124 declared terms owned no directory; that one finding became a ticket stating the gate's predicate. The whole loop is this — a miner reads the record, finds one divergence between intent and code, and turns it into the next gate or change.
The scoreboard (csf scoreboard) prints the program's meters as measured
numbers only: consistency is percent(59.0) today, generated_share is
percent(2.0) against a target of percent(100), and no row prints a word
where a number is known.
Most robots run two kinds of software side by side: a slow, best-effort layer that decides what to do (planning, perception, learned policies) and a fast, real-time layer that does it (the control loop that must never miss a deadline). LITHE (Lim and Clites, 2026) turns that split into an architecture on one ordinary computer. A best-effort Brain proposes, a real-time Spine executes, and each gets its own CPU core. On LITHE's quad-core board, CPU 1 runs the Spine's control loop alone, CPU 2 runs the Brain, CPU 3 handles the motor bus, and CPU 0 is the housekeeping core: it takes the operating system's chores, absorbs timing jitter so the other cores never feel it, and prepares the next controller before it is swapped in. LITHE demonstrates this on one robot, but deciding versus doing is the shape of most robot software stacks, so we expect the architecture to carry over to most robots. Figure 1 is LITHE's own diagram of that split.
Figure 1. LITHE's system architecture: the Brain, Spine, Housekeeping and Transport roles, each on its own core of one Raspberry Pi, driving a one-degree-of-freedom robot. LITHE, Figure 2, shown from arXiv and not copied into this repository (Lim and Clites, 2026).
CSF is the LITHE philosophy applied to CPU 0. It is the housekeeping layer: the tools, records, schedules and experiments around an agent system's decisions, composed into one Go process so they talk through function calls instead of inter-process communication. In CSF the architecture is a checked artifact and the engineers are agents working under rules. It ships with working implementations (gotth-live, Warden, xetcas, pgmem, liquidproto) that prove the loop works. On LITHE's four-core board that is CPU 0 alone; on a larger computer, CSF's process scales across every core not reserved for the Spine, Brain and Transport. Figure 2 places CSF on LITHE's CPU 0.
Figure 2. CSF inside LITHE's CPU 0: one Go process holding typed tools, sessions, schedules, knowledge, observation and bounded workers. LITHE's Brain, Spine and Transport cores, and the external systems CSF talks to, sit outside it. Drawn by hand as our mapping onto LITHE; it is not generated.
New here? Take the tour of CSF: ten stops from the idea to the running pieces, each with a diagram, real code, an example next to a counterexample, and one command to run.
It has four parts, and together they form one loop:
- A language.
architecture.csfdeclares what the system is: its terms (124 today), how they contain and depend on each other, and the paper each borrowed word comes from. For example:term widget "Widget" "A component of gotth-live ...". - A compiler,
csfc. It checks the code against that declaration and generates what used to be hand-written: the glossary, the dictionary, the architecture diagrams below, and this README's north star. For example,tools/merge-pr.shrefuses a pull request whose ontology alignment score regresses againstmain. - A harness. One process per machine runs coding-agent
sessions with a gate on every shell
command and every commit. For example,
harness submit -recipe agent.jsonstarts an agent that cannot run a polling loop and whose first commit opens a draft pull request. - Miners (ouroboros). They read the operator–agent record and the repository, find where intent and code diverge, and turn each divergence into the next gate or change. For example, on 2026-10-02 the finding that 64 of the 124 terms own no directory became a ticket that states the gate's predicate; the gate itself is not built yet. Its method, RRSI [14], evolves the agents' harness itself against an exam mined from git history.
- An agentic software engineer. Hand it a ticket and it works the ticket end to end: an agent session in its own git worktree writes the change under a gate on every command and commit, opens a draft pull request at its first commit, and the merge gate refuses the change unless its checks and its architecture score hold. Many sessions run at once, one harness per machine, and you steer any of them from its chat page. CSF is developed this way.
- An agent-operated deployment system: propose and approve changes, reconcile applications, approve infrastructure updates, and watch the fleet.
- A server-driven live UI that keeps one copy of the state on the server and syncs every browser tab to it.
- A self-hosted build and evidence cache that uploads only what changed.
- Fast tests with real SQL and no database server.
What you get, grouped by what it is for:
- CSF — The Cerebrospinal Fluid, the core: a Go library and runtime for the coordination around an agent system, covering typed tools, sessions and worktrees, schedules, knowledge ingestion and search, traces and retained evidence. Its services are libraries mounted into one Go process through functional options, and each operation is generated once and served as HTTP, CLI and MCP. Start with the consumer example.
- Agent harness and ops view: one process per machine runs every agent session with gates on every command and commit. The
csfbinary is both that process and its client:csf initputs CSF into a repository,csf submittakes an assignment recipe,csf sendadds a turn, andcsf serveserves the Workbench, a gotth-live page with one live card per session (command reference). See Quick start. - Ouroboros: miners that read the record of what agents did, find mistakes no gate catches yet, and turn each into a gate once a walk-forward backtest on history finds every labeled case.
- RRSI: Regularized Recursive Self-Improvement [14], Ouroboros's method: it rewrites an agent's harness (prompts, tools and loop, not the model) and keeps only changes that beat noise on an exam mined from your own git history.
csfccompiler: checks the code againstarchitecture.csfand generates the glossary, the dictionary, the diagrams and this README's north star.
- Agent harness and ops view: one process per machine runs every agent session with gates on every command and commit. The
- Deploy, an agent-operated deployment system: an agent harness proposes, the deploy service approves and fences every change, the node executor reconciles Compose applications, and the operator UI watches.
- Deploy service and node executor, with the deployment kit for Compose applications.
- Warden: the fleet watchdog the deploy service fences against: Raft-style leader election [5] over a static peer set, liveness, incidents, and an authoritative view every mutation is checked against.
- Libraries you can use on their own:
- gotth-live: server-driven live user interfaces from Go. Widgets, event handlers and state are synced from the application layer, and the browser renders each change as the app commits it. State and rendering stay in your process; one WebSocket per tab carries events up and re-rendered fragments down. No npm, no CDN.
- xetcas: a self-hosted Xet [6] content-addressable storage server with a Git LFS [7] front door, used for build caches, snapshots and evidence archival. Re-pushing a 48 MiB model after editing 2% of it costs about 1 MiB.
pkg/: domain-neutral Go primitives:pgmem, a process-local PostgreSQL [8] emulator for fast tests (real PostgreSQL AST, no server);liquidproto, the runtime for Liquid Proto, protobuf with refinement types [9] compiled into the generated Go;cron,config,redact,telemetry,mailbox, and more.
Figure 3 shows how these pieces fit together, and why each one is shaped for a robot's CPU 0. Click it to open it full size.
Figure 3. How CSF fits together: two loops. The big loop builds the robot's
autonomy. Six parts sit clockwise around CPU 0: declare (the languages and csfc),
run (the runtime library), show (gotth-live),
change (the agent harness), ship (deploy and Warden) and learn
(xetcas; amber marks planned work). The centre is one Go process built on the
pkg/ primitives. Beside the agent harness sits the small loop,
Ouroboros, whose method is RRSI: it takes every session's trace
and hands back the next gate. The panel below opens it up. A miner extracts
facts from the corpus, a Datalog rule derives verdicts with proofs, and a
walk-forward backtest decides whether the miner becomes a gate; the gated runs
become the next corpus. The numbers are the DRAFT-PR-LATE miner's
(worked example).
Rose marks the steps that make LLM calls: the agent harness, an agent writing a
miner, and csf label proposing labels. Every other box is deterministic code.
The north star is a robot software
stack whose correctness is proven end to end; today that is a goal, not a
capability: the generated table below reports no completed milestone, and the
csfc verifier does not yet issue certificates. It ships as one Go monorepo
with a CLI.
The name comes from the architecture that shaped it. In LITHE (Lim and Clites, 2026), a best-effort Brain proposes and a real-time Spine executes, on one partitioned computer. CSF is the fluid around them: the housekeeping layer that carries tools, records and experiments between decisions (Figures 1 and 2).
New to the words used here? The glossary explains every CSF term in plain language, plus the words CSF borrows from papers, with citations.
First-party source is Apache-2.0. Dependencies, vendor simulator images and paper figures retain their own licenses.
Generated from architecture.csf; change that file, not this section.
Goal. End-to-end correctness of a robot software stack, proven relative to stated assumptions and checked against them at runtime. The physical world and the models in it are not proven; the envelope around them is: check before execute, contracts at every io boundary, and runtime monitors with a safe fallback.
Milestones. 0 done, 6 in progress, 2 planned. A done milestone names a path in this repository that the generator checks exists; PR and issue numbers refer to the source monorepo.
| # | Milestone | Status |
|---|---|---|
| 1 | Typed Io | in progress |
| 2 | Resolved Tiers | planned |
| 3 | Ros Seam | in progress |
| 4 | Turn Executors | in progress |
| 5 | Compilability | in progress |
| 6 | Self Improvement | in progress |
| 7 | Typed Documentation | in progress |
| 8 | Post Training | planned |
Every io boundary is a typed capability: a service crosses only what its constructor was granted, and the io tree is sorted by crossing tier. Process launch and PostgreSQL are capabilities today; the move into the tier-sorted io directories is planned.
Uses: I/O crossing, Crossing tier, Capability
Evidence: io/ipc/proc, io/ipc/db/csfpg, PR #290, PR #301, PR #321, issue #264
Each crossing's tier is resolved from runtime and placement state instead of being declared by hand.
Uses: Crossing tier, Placement rules, Runtime
Evidence: issue #264
The low-level controller is reached only through the ros seam, whose contract is proven ROS-side and monitored CSF-side with a safe fallback. The stub that answers every call with a typed not-connected error ships; the transport, proof and monitor are planned.
Uses: ROS spine capability, Low-level spine controller, Check
Evidence: io/net/ros, PR #299
Cites: KeYmaera X (glossary), VeriPhy (glossary)
Turn executors are interchangeable behind one contract while CSF owns the session, its context and its tools. Claude Code and the Copilot CLI run as turn executors under the same session gates, chosen by the recipe; CSF does not yet own the session's context.
Uses: Turn executor, Workbench conversation session, Claude Code provider, Copilot CLI provider
Evidence: io/net/model/claudecode, examples/claudecode, io/net/model/copilotcli, PR #322
Every unit of the system climbs the compilability ladder from prose to structured, typed, checked and finally discharged, where a checker discharges a stated proof obligation. csfc checks the declared architecture against its Go source on every change, and its check-generated command states lifetime and cleanup obligations that it does not yet discharge.
Uses: Compiler, Compile, Shared typed contracts
Evidence: csf/compiler/architecture, issue #329
Cites: CompCert (glossary), seL4 (glossary)
The system improves itself through Ouroboros, under gates it may not change: mined evidence proposes each change and every accepted change is an operator-approved pull request. The mining loop runs inside CSF: miners mine every log as it changes, a pre-check decides at no model cost which tickets a fixer can take, fixers run through the harness under a daily budget, the merge train merges what passes the gate, and the compounding rate is measured and shown. The slice dispatcher launches the ready slice graph within measured limits with no orchestrator. Unattended fixer launch waits for sandboxed launch.
Uses: Ouroboros, Miner, Pre-check, Fixer, Merge train, Compounding rate, Slice dispatcher
Evidence: services/ouroboros, services/dispatch, PR #237
No hand-written documentation: every claim is typed data in architecture.csf and its prose is generated, this section included.
Evidence: csf/compiler/language/architecture.csf, docs/GLOSSARY.md, PR #333
CSF post-trains its own model on its traces and the corrections its operator accepted, once the harness eval suite can score a post-trained model against the frozen one on the same tickets withheld from training. Until then CSF improves the harness only. Deferred by the operator on 2026-10-05; the question is csf_staging issue 415, prompted by NeoHorse-1.
Uses: Ouroboros, Turn executor, Brain
Cites: NeoHorse-1 (glossary)
LITHE runs a whole robot control hierarchy on one quad-core single-board computer by partitioning its cores (LITHE §III-B):
| LITHE core | Role in LITHE |
|---|---|
| CPU 0 (Housekeeping) | Linux housekeeping, SSH sessions and non-critical interrupts. It absorbs system jitter, and LITHE's loader thread prepares new controllers here (LITHE §III-E1). |
| CPU 1 (Spine) | The C++ control loop, alone on an isolated core. |
| CPU 2 (Brain) | The high-level Python runtime. |
| CPU 3 (Transport) | Blocking SPI/CAN bus I/O, kept off the control core. |
LITHE treats inter-process communication as architecture (LITHE §III-C): the Brain and Spine exchange state through lock-free, zero-copy POSIX shared memory whose layout a build-time generator owns. Its abstract names complex middleware as one cost of the conventional alternatives.
The coordination an agent system needs — tools, sessions, schedules, knowledge and observation — lands on the housekeeping side of that partition. Built the usual way, each capability is its own daemon, and every handoff inside CPU 0 becomes a socket, a serialization format and another process lifecycle to supervise.
CSF prevents that IPC problem inside CPU 0 by composing those capabilities in one Go process. Services are Go libraries selected with functional options. They exchange typed values through function calls and coordinate concurrent work with goroutines and channels; contexts and explicit ownership give each operation a cancellation and cleanup path. An internal handoff needs no socket, no wire serialization and no separate daemon. Separate architecture checks inspect selected Go ownership and process boundaries in source; they establish those source constraints, not runtime timing.
Figure 4 shows what that means inside the process, and who owns each part.
Figure 4. Monolithic microservices: who owns what. Teal is CSF, indigo is the Go runtime, amber is you, the consumer, and grey is the machine. Each service is a CSF part with the piece you supply; underneath, the Go runtime schedules every service's goroutines across the cores over one shared heap. On a LITHE robot CPU 1 to 3 are reserved, so CSF runs on every other core.
Figure 2 is our architectural mapping onto LITHE [1], drawn by hand; it is not generated from the architecture model. Its boundaries are exact:
- PostgreSQL, OpenSearch, Langfuse and external model or simulator processes keep their protocol boundaries. CSF removes IPC between its own capabilities, not IPC with systems that genuinely live elsewhere.
- LITHE's Brain–Spine shared-memory IPC remains a separate integration boundary.
- CPU affinity and isolation are deployment configuration. CSF does not implement LITHE's loader, CPU isolation or real-time controller hot swap.
examples/csf-consumer shows the composition:
CSF, its generated routes, its MCP server and the consumer's own endpoint in one
router owned by the consumer's process.
LITHE is explicit about where its guarantee stops. Its user-space real-time approach "provides a functional margin of safety, even if it lacks the formal mathematical guarantees of a verified real-time operating system" (LITHE §V-A). For model-written controllers, "it remains an area of active research to implement appropriate safety and verification bounds on the model's output" (LITHE §V-B); "theoretical stability guarantees remain an open challenge", so safety "must be enforced via strict hardware-level limits on torque and velocity" (LITHE §V-C).
A hardware limit is enforced per device. A proof about a language holds for every program written in it. CSF's direction is to narrow what a model may author to a typed, bounded language, and to prove what that language's compiled code computes. The model then chooses among checked options instead of emitting arbitrary code. That is how we think LITHE's idea scales past one robot on one bench.
What is proved today. csf/examples/proof/BrainSpine.lean
models the arithmetic slice of
brainspine.proto: a typed
expression language with constants, four observation slots, addition, integer
scaling and clamping over saturating integers, compiled to a postfix stack
machine. Lean machine-checks four theorems:
| Theorem | Guarantee |
|---|---|
compile_correct |
For every expression, inputs and existing stack, the compiled instructions push exactly the evaluated value and preserve the stack. |
evaluate_bounds |
Every expression evaluates within the saturation bound [-1000000000, 1000000000]. |
compiled_actuator_correct |
Compiled code run from an empty stack, then through the actuator clamp, agrees exactly with the clamped source evaluator. |
compiled_actuator_bounds |
Every compiled expression produces an actuator value in [-1000, 1000]. |
bash csf/examples/proof/check.sh downloads the pinned Lean release, verifies
its SHA-256, runs Lean with --trust=0, and audits the axioms of all four
theorems: only Lean's standard propext, Classical.choice and Quot.sound
are admitted, and sorryAx or custom axioms fail the check. CI runs it in its
own job.
What is not proved. Be precise about the gap:
- Agreement between the Lean model and the canonical wire semantics is a
reviewed translation boundary. CSF ships no controller implementation: the
low-level spine is external and ROS-side, reached through
ipc/ros. - The
csfccompiler verifier is a stub:CSFC.Verification.verifyreturnsnotImplementedfor every input and issues no certificate. - The actuator clamp proves a numeric range only. Timing, stability, collision avoidance, safe controller switching and physical safety are outside every theorem here. A hardware watchdog remains necessary.
- The Lean kernel, its official release build, the standard library, the operating system and the hardware remain trusted.
The improvement loop in Figure 5 is generated from the same architecture model as every CSF diagram. Choose and controller selection are planned: the low-level controller is external and ROS-side, and an agent choosing among proved options is the next step, not a shipped one.
%% Generated from csf/compiler/language/architecture.csf; do not edit.
%% Documentation model only; status labels do not establish runtime verification.
flowchart LR
classDef csf_existing fill:#0F766E,stroke:#115E59,stroke-width:2px,color:#FFFFFF;
classDef csf_planned fill:#FEF3C7,stroke:#B45309,stroke-width:2px,color:#78350F;
n_observe["Observe (existing)"]:::csf_existing
n_retrieve["Retrieve (existing)"]:::csf_existing
n_choose["Choose (planned)"]:::csf_planned
n_check["Check (existing)"]:::csf_existing
n_execute["Execute (existing)"]:::csf_existing
n_evaluate["Evaluate (existing)"]:::csf_existing
n_save_evidence["Save evidence (existing)"]:::csf_existing
n_ouroboros["Ouroboros (existing)"]:::csf_existing
n_select_controller["Select a controller between episodes (planned)"]:::csf_planned
n_observe -.-> n_retrieve
n_retrieve -.-> n_choose
n_choose -.-> n_check
n_check --> n_execute
n_execute --> n_evaluate
n_evaluate --> n_save_evidence
n_evaluate -.-> n_select_controller
n_select_controller -.->|"next agent iteration"| n_choose
n_save_evidence --> n_ouroboros
n_ouroboros -->|"next iteration"| n_observe
linkStyle 0 stroke:#B45309,stroke-width:2px,stroke-dasharray:5 5
linkStyle 1 stroke:#B45309,stroke-width:2px,stroke-dasharray:5 5
linkStyle 2 stroke:#B45309,stroke-width:2px,stroke-dasharray:5 5
linkStyle 3 stroke:#0F766E,stroke-width:2px
linkStyle 4 stroke:#0F766E,stroke-width:2px
linkStyle 5 stroke:#0F766E,stroke-width:2px
linkStyle 6 stroke:#B45309,stroke-width:2px,stroke-dasharray:5 5
linkStyle 7 stroke:#B45309,stroke-width:2px,stroke-dasharray:5 5
linkStyle 8 stroke:#0F766E,stroke-width:2px
linkStyle 9 stroke:#0F766E,stroke-width:2px
Figure 5. The improvement loop, generated from architecture.csf. Solid
steps exist today; dashed steps are planned.
Figure 6 is generated from
csf/compiler/language/architecture.csf
by the CSF documentation compiler, which also produces the
shared vocabulary and the plain-language
glossary. Solid connections are
existing components or configurable integrations; dotted connections are
planned. An integration shown here still needs its dependencies and
configuration; it is not automatically running when you import CSF.
%% Generated from csf/compiler/language/architecture.csf; do not edit.
%% Documentation model only; status labels do not establish runtime verification.
flowchart TB
classDef csf_existing fill:#0F766E,stroke:#115E59,stroke-width:2px,color:#FFFFFF;
classDef csf_planned fill:#FEF3C7,stroke:#B45309,stroke-width:2px,color:#78350F;
n_human["Human or agent client (existing)"]:::csf_existing
n_brain["Brain (existing)"]:::csf_existing
n_contracts["Shared typed contracts (existing)"]:::csf_existing
n_stores["Store (existing)"]:::csf_existing
n_jobs["Job ledger (existing)"]:::csf_existing
n_views["Prometheus#44; Grafana and Langfuse (existing)"]:::csf_existing
n_experiments["Training results and optional MLflow (existing)"]:::csf_existing
n_vendor["Copilot brain provider (existing)"]:::csf_existing
n_spine["Low#45;level spine controller (planned)"]:::csf_planned
n_hardware["Consumer sensors and actuators (planned)"]:::csf_planned
subgraph g_host["CSF#58; one Go application process"]
n_bench["Workbench (existing)"]:::csf_existing
n_api["Generated HTTP#44; CLI and MCP operations (existing)"]:::csf_existing
n_knowledge["Knowledge and retrieval (existing)"]:::csf_existing
n_ros["ROS spine capability (existing)"]:::csf_existing
n_workers["Configured worker goroutines (existing)"]:::csf_existing
n_inspect["Inspection (existing)"]:::csf_existing
n_widgets["Widget SDK and gotth#45;live (existing)"]:::csf_existing
end
style g_host fill:#EEF2FF,stroke:#4338CA,stroke-width:2px,color:#1E1B4B
n_human --> n_bench
n_brain --> n_api
n_contracts --> n_api
n_bench --> n_api
n_bench --> n_vendor
n_api --> n_knowledge
n_api -->|"spine status"| n_ros
n_api --> n_workers
n_api --> n_inspect
n_knowledge --> n_stores
n_workers --> n_jobs
n_jobs --> n_stores
n_inspect --> n_views
n_brain --> n_experiments
n_widgets -->|"keyed Kanban cards"| n_bench
n_ros -.->|"planned ROS transport"| n_spine
n_spine -.-> n_hardware
linkStyle 0 stroke:#0F766E,stroke-width:2px
linkStyle 1 stroke:#0F766E,stroke-width:2px
linkStyle 2 stroke:#0F766E,stroke-width:2px
linkStyle 3 stroke:#0F766E,stroke-width:2px
linkStyle 4 stroke:#0F766E,stroke-width:2px
linkStyle 5 stroke:#0F766E,stroke-width:2px
linkStyle 6 stroke:#0F766E,stroke-width:2px
linkStyle 7 stroke:#0F766E,stroke-width:2px
linkStyle 8 stroke:#0F766E,stroke-width:2px
linkStyle 9 stroke:#0F766E,stroke-width:2px
linkStyle 10 stroke:#0F766E,stroke-width:2px
linkStyle 11 stroke:#0F766E,stroke-width:2px
linkStyle 12 stroke:#0F766E,stroke-width:2px
linkStyle 13 stroke:#0F766E,stroke-width:2px
linkStyle 14 stroke:#0F766E,stroke-width:2px
linkStyle 15 stroke:#B45309,stroke-width:2px,stroke-dasharray:5 5
linkStyle 16 stroke:#B45309,stroke-width:2px,stroke-dasharray:5 5
Figure 6. CSF's architecture, generated from architecture.csf. Solid
connections exist or are configurable integrations; dotted connections are planned.
CSF separates what data is from where it lives, following the ANSI/SPARC three-level architecture [2] and Codd's physical data independence [3]:
| CSF | ANSI/SPARC | Meaning |
|---|---|---|
data structure (pkg/graph, Cell, Map, Queue) |
conceptual level | the data and its operations, with no placement, locks or I/O |
store (pkg/store.Store[D]) |
internal level | the physical placement of a data structure: memory (RAM), a file, or PostgreSQL; its crossing tier is derived from that backend |
store places data_structure |
conceptual/internal mapping | changing a store's backend never changes code written against the data structure (physical data independence) |
| view, dashboard | external level (specializes) | generated projections of typed records, not per-user schemas |
Status: operator ruling recorded 2026-10-02; pkg/graph, pkg/store and the ontology
terms are planned (source monorepo issue #366). The in-process Queue exists today in
io/inproc.
Anything that does something is a service, and cross-cutting behavior attaches to a service's actions the way aspect-oriented programming attaches advice to join points [4]:
| CSF | AOP | Meaning |
|---|---|---|
| action | join point | a service operation (an RPC method); the only thing a hook attaches to |
| hook | advice (before/after) | pre or post code on one action, supplied as a generated functional option such as WithPreSubmit, typed by that action's request and response |
| pointcut | pointcut | a typed selector of actions |
| aspect | aspect | one cross-cutting concern: a pointcut plus its hooks, e.g. the session gate, telemetry, admission, the merge gate |
| weaving (specializes) | weaving | applying aspects when the host app composes its services; no source or bytecode rewriting |
An action CSF does not execute itself, such as git commit, enters through an
adapter service whose operation is the join point.
Status: operator ruling recorded 2026-10-02; the generated options and ontology terms are planned (source monorepo issue #374).
.
├── csf/ typed coordination library, contracts, examples and consumer guide
├── pkg/ domain-neutral primitives — nothing in them knows about any service
├── services/ composable business logic — deploy, warden, the agent harness, cron, ops view and more
├── app/ runnable compositions — csf, harness, deploy, node executor, warden, intake
├── runtime/ the process runtime: the lifetimes every goroutine starts under
├── ipc/ boundary crossings, each a capability granted through a constructor
├── io/ the in-process io tier (io/inproc)
├── web/ the deploy service's and node executor's web layers
├── proto/ .proto sources and their committed Go bindings
├── infra/ deploy-kit/ (Compose stack, installer, fleet driver, updater) and local dev services
├── tools/ build wrapper, house gates, the CSF kit installer and the csf operator CLI
├── xetcas/ a Rust workspace (xetcasd) plus its generated Go bindings
├── examples/ one worked consumer per extension seam, each with its own suite
├── extensions/ copilot-pair, a GitHub Copilot CLI extension
├── docs/ extending.md (the four compile-time seams) and GLOSSARY.md (for humans)
└── bazel/ the legacy WORKSPACE shim
The three Go trees are separated by one rule, about who may import whom:
| Imports | Allowed direction |
|---|---|
Runnable compositions (app/) |
Services, CSF and shared packages |
| Domain services and CSF | Shared packages |
Domain-neutral packages (pkg/) |
No import of services or application compositions |
Nothing in pkg/ imports services/ or app/, which is what makes the
primitives usable on their own:
| Package | What it is |
|---|---|
gotth |
Server-driven live UI. Large enough to have its own documentation set. And it does. |
pgmem |
A process-local PostgreSQL emulator for fast tests — real PostgreSQL AST, no server. |
cron |
The schedule grammar: human-readable trigger declarations and their canonical five-field form. The scheduler that fires them is services/cron. |
liquidproto |
The runtime for Liquid Proto: protobuf with refinement predicates compiled into the generated Go. |
telemetry |
Trace propagation and structured JSONL over the candace.telemetry.v1 contracts, with no observability SDK. |
config |
Configuration-boundary parsing: environment lookup, private-origin validation, provider/model strings. |
mailbox |
Serializes ownership of a mutable value onto one goroutine — commands run in turn, so no field needs a lock. |
boundedbuffer |
An io.Writer that retains at most a fixed number of bytes while still reporting the true write lengths. |
redact |
Removes caller-declared sensitive values, and their URL-userinfo spellings, from log-bound text. |
labels |
Canonicalizes case-insensitive label lists so services compare and deduplicate them one way. |
core |
The zerolog logger the Go trees log through, plus the few formatters operator pages share. |
eventually |
The one typed await for tests: poll a value, judge it with a predicate, get the value that satisfied it back. |
widget |
The widget dialect and its toolchain: interpreter, validator, generator, and the typed SDK that mounts generated cards into a gotth-live host. |
pkg/proto and pkg/scripts hold tooling rather than a package.
| Component | Kind | Home | Definition |
|---|---|---|---|
| Ouroboros | component | planned 355 |
Use evaluated results to propose the next version of an agent's instructions or an allowed workflow.... |
| Brain | component | planned 346 |
An agent loop over a large model, reached through an inference provider or API. Brains are external ... |
| Agent | component | planned 346 |
A named worker: versioned instructions plus a live conversation session, holding assignments and rec... |
| Work continuity | component | candace/services/workcontinuity |
The task checkpoint service at candace/services/workcontinuity. It reads, validates and records chec... |
| Workbench conversation session | component | candace/services/harness |
A conversation and its execution records under a stable identifier. CSF stores Workbench sessions; t... |
| Host runtime | component | candace/runtime |
The runtime in source: candace/runtime.HostRuntime, one per process. The binary's main function buil... |
| gotth-live | component | candace/pkg/gotth |
The required owner of widgets and their web interaction. It belongs to CSF's web layer and runs with... |
| gotth-live service | component | candace/pkg/gotth |
The in-process capability that manages live UI connections and their goroutines for a host app. Its ... |
| Deploy | component | candace/services/deploy |
The deployment control plane: desired state, placement, operator approval, reconciliation against Wa... |
| Node executor | component | candace/app/nodeexec |
The service that applies one approved Compose assignment on one machine under a leader fence. It is ... |
| Agent harness | component | candace/services/harness |
The service that runs agent sessions: one process per machine runs every session concurrently, each ... |
| Infrastructure kit | component | candace/infra |
Deployment material that is not Go: Compose files, installers and shell drivers under candace/infra.... |
| Deployment kit | component | candace/infra/deploy-kit |
candace/infra/deploy-kit: the Compose files, installer, fleet driver and deploy-updater scripts that... |
| Database backends | component | candace/ipc/db |
ipc/db: one package per database backend CSF reaches, named csf<backend> (csfpg for PostgreSQL; a la... |
| CSF PostgreSQL backend | component | candace/ipc/db/csfpg |
candace/ipc/db/csfpg: CSF's PostgreSQL backend: the only pool owner, the schema's generated queries ... |
| Model providers | component | candace/ipc/model |
The ipc subtree ipc/model: the brain contract IBrain and the brain providers behind it, one subpacka... |
| Copilot provider package | component | candace/ipc/model/copilot |
The package ipc/model/copilot that implements the brain contract over the Copilot brain provider (ve... |
| Claude Code provider | component | candace/ipc/model/claudecode |
The ipc/model provider for Claude Code sessions, each an agent loop in its own process on the same m... |
| Turn executor | component | planned 346 |
A turn executor is the external agent loop that carries out one turn: Claude Code, Codex, Copilot, w... |
| Relay | component | candace/services/relay |
The agent messaging service: it delivers typed envelopes from one agent address to another agent's i... |
| Event intake | component | candace/services/intake |
The service candace/services/intake: GitHub activity as the typed candace.intake.v1.Event. Its webho... |
| Compiler | component | candace/csf/compiler |
The CSF OCaml compilers under csf/compiler: the documentation language, the architecture checker and... |
| ROS spine capability | component | candace/ipc/ros |
candace/ipc/ros: the ISpine boundary through which CSF submits an Action to the external ROS-side sp... |
| Job ledger | component | candace/services/jobs |
candace/services/jobs: the durable record of requests admitted to external executors. The ledger is ... |
| Cron | component | candace/services/cron |
The cron service, candace/services/cron: the durable in-process scheduler that mounts into the host ... |
| Session gate | component | candace/services/harness/sessiongate |
A structural check the harness installs into every session it runs, as a hook the turn executor call... |
| Recall | component | planned 365 |
Cross-session agent knowledge: retrieved when a new session resumes an agent's work. A capability se... |
| Human zone | component | candace/humans |
The operator interface and decisions, separate from CSF's automated runtime. Terms and operations wi... |
To put CSF into a repository of yours, run csf init at its root. It
writes a sample assignment under .csf/ and registers the repository with
this machine's agent harness, starting it if none is running. Then:
csf submit -recipe .csf/assignments/sample/agent.json # an agent session starts
csf events -assignment <id> # ends with a draft pull request
csf chat -assignment <id> # the session's chat addresscsf comes from this repository, once per machine, with only Docker on the
machine: tools/kit/install.sh from a clone. The CSF kit guide
walks every step, its success check and how to undo it.
Use Go 1.26. The smallest CSF example needs no database, GPU, model account or extra process:
go run ./examples/csf-theme --listen 127.0.0.1:8089 --theme-dir ./examples/csf-themeThat mounts the generated HTTP API and MCP at http://127.0.0.1:8089/mcp. The
caller owns the process; CSF only registers routes and hands back a handler.
From examples/csf-consumer/main.go:
service, err := csf.New(options...)
if err != nil {
return nil, fmt.Errorf("create CSF: %w", err)
}
router := httpserver.NewEngine(applicationName)
service.Register(router)
router.Any(mcpPath, gin.WrapH(service.MCPHandler()))
registerConsumerSummary(router, service)Agent-native onboarding. The intended first instruction to your agent is
“Learn about CSF.” The LearnAboutCSF MCP operation explains the pinned
version's capabilities and extension points and, when knowledge is configured,
submits the embedded guidance plus selected consumer files for indexing. Your
own tools join the same MCP server with typed inputs and outputs; the pinned MCP
SDK derives and validates their schemas, and CSF rejects name collisions with
its own operations. The signature, from csf/service.go:
func WithMCPTool[In, Out any](tool mcp.Tool, handler mcp.ToolHandlerFor[In, Out]) OptionThe host still owns listener startup, authentication, repository authorization and consumer checks. The CSF guide covers the Workbench, onboarding and every example with its boundary.
gotth-live, the web layer CSF's Workbench uses, runs with no npm or code generation:
go run ./examples/gotth/countercounter: http://127.0.0.1:8080
counter: allowed origins [http://127.0.0.1:8080 http://localhost:8080]
Open that URL in two browser tabs. The number lives in the Go process and
neither tab holds a copy of it: click in one and the other repaints, reload
either and the count survives, and the client script that carried the patch
was compiled into the binary and served by the same handler that serves the
WebSocket. examples/gotth/counter/README.md
follows one click all the way through and names the file each step lives in.
The optional CSF Workbench has a separate browser-asset build documented in its
README.
It is a one-way snapshot of the canonical repository at one exact revision,
published with no upstream history. The canonical repository is
private CSF staging since 2026-10-02; v0.1.3 and earlier were exported from a
private monorepo's candace/ folder. Snapshot updates arrive as ready pull
requests from the candace-export branch against main, and releases from
candace-release. Make source changes in the canonical repository; editing the generated
destination directly would conflict with its next snapshot.
After its review PR is merged, the publisher verifies that tree and creates
immutable v<version> and export-<sha12> tags. The GitHub Release uses the
semantic-version tag; .candace-export.json records the exact source revision.
Cite a tag, not a branch.
Releases are published on candacelabs/csf; the current one is v0.3.0. For a
private staging release, download the release assets with authenticated access
and use the
verified local-archive consumer.
The Go module path is github.com/candacelabs/csf in both cases.
New releases carry csf-<sha12>.tar.gz and its .sha256; historical releases
retain their original archive names. The tarball is
this tree re-rooted so MODULE.bazel is at the archive root, plus a deterministic
.candace-source.json recording the source revision and selected tree, built twice and
byte-compared before it is kept.
Download both files from the same Release. In their directory, replace <sha12>
with the 12-character revision from its tag and verify the hexadecimal checksum, then compute
the base64 SRI value required by Bazel (Bash, sha256sum and OpenSSL):
set -euo pipefail
archive='csf-<sha12>.tar.gz'
sha256sum --check "$archive.sha256"
printf 'sha256-'
openssl dgst -sha256 -binary "$archive" | openssl base64 -A
printf '\n'Copy the complete sha256-... output line into integrity in your own
MODULE.bazel; the .sha256 file's hexadecimal value is not an SRI value. The
archive's module() still declares version 0.1.0, so bazel_dep keeps that
version while the URL names the release tag:
bazel_dep(name = "csf", version = "0.1.0")
archive_override(
module_name = "csf",
integrity = "sha256-...", # base64 SRI output from the command above
strip_prefix = "csf-<sha12>",
urls = ["https://github.com/candacelabs/csf/releases/download/v0.3.0/csf-<sha12>.tar.gz"],
)Then depend on what you use — @csf//services/deploy/component,
@csf//pkg/gotth/live, @csf//services/warden — and build. Since v0.2.0 the
deploy service sits at services/deploy/ and its kit at infra/deploy-kit/;
v0.1.3 and earlier used services/candaceos/ and candaceos/.
Not a Bazel repository? The module path is the repository path:
go get github.com/candacelabs/csf@v0.3.0Use the published semantic version matching your archive, not @latest.
The accompanying export-<sha12> tag identifies its exact source snapshot.
docs/extending.md covers both shapes in full, plus the
http_archive fallback and the legacy WORKSPACE path.
Every extension seam has a worked example with its own test suite. They are the contract's executable half — the documentation says what is guaranteed, and these fail if it stops being true.
| Example | Shows |
|---|---|
csf-consumer |
CSF mounted beside a consumer's own Go endpoint in one process, its generated client, MCP tool discovery and shutdown. Its archive acceptance script builds a fresh repository with networking disabled. |
external-consumer |
A complete outside repository choosing every seam at once: its own identity and overlay, its own sidebar entry and page, three composed services, a custom agent harness, and the deploy service binary linked from them — built and tested both supported Bazel ways. This is also the acceptance test every release archive passes. |
custom-brand |
The deploy service wearing another product's identity — name, agent, wordmark, palette, an overlay asset, an extra sidebar entry and page — with no edit to the deploy service. |
custom-ui-page |
The smallest useful UI extension: stock identity, one sidebar entry, one page of your own. |
gotth/counter |
gotth-live at its smallest: a number that lives in Go, four buttons, and every open tab kept in step by the server. |
gotth/chat |
One room in Go, several browsers, and every message reaching every session over a server push. |
gotth/dashboard |
A feed pushing twenty times a second, three live regions patched independently, and two plain-HTMX regions on the same page. |
Bazel is the primary build and comes from a pinned container, so the command is the same on a laptop and on a runner. Docker is the only prerequisite:
tools/bazel.sh build -- //... -//xetcas/... # everything but the Rust workspace
tools/bazel.sh test -- //... -//xetcas/...
tools/bazel.sh build //xetcas/... # the Rust workspace and its Go bindings
tools/bazel.sh test //xetcas/...The plain go command works on the same tree and needs no Bazel:
go build ./...
go test ./...The Rust workspace builds with plain Cargo too — that is the path its demo,
container images, and just targets take:
cd xetcas && cargo build --workspace && cargo test --workspace.bazelversion (Bazel 9.2.0) and MODULE.bazel (rules_go 0.62.0, Gazelle
0.52.2, Go SDK 1.26.5, rules_rust 0.73.0) are the only version authority. BUILD
files are generated by Gazelle (tools/bazel.sh run //:gazelle) and CI fails on
drift.
The deployment kit installs and runs the whole one-box stack (deploy service, node executor and operator UI) from this clone. The default install is deliberately harmless: a simulated harness, a dry-run executor, and no Docker socket bind-mounted anywhere.
./infra/deploy-kit/install.sh # then open http://<host>:7780
./infra/deploy-kit/status.sh
./infra/deploy-kit/uninstall.shThe deploy service publishes on all host IPv4 interfaces with no built-in authentication:
put it behind your own authenticating proxy before exposing it beyond a trusted
network. infra/deploy-kit/README.md is the operations manual,
and infra/deploy-kit/AGENTS.md states the trust model as eight
invariants with their enforcement points.
csf/README.md— the CSF guide: Workbench, onboarding, examples and release evidence.AGENTS.md— the repository's own guide: taxonomy, seams, invariants, conventions.docs/extending.md— the four compile-time seams and how to pin a snapshot.docs/GLOSSARY.md— every CSF term and borrowed literature term in plain language, for human readers.pkg/gotth/README.md,xetcas/README.md— each subsystem's own front page.app/*/CLAUDE.md— what may not be changed casually in each binary.
[1] He Kai Lim and Tyler R. Clites. LITHE: Bridging Best-Effort Python and Real-Time C++ for Hot-Swapping Robotic Control Laws on Commodity Linux. arXiv:2603.07442 [cs.RO], 2026. Submitted to IROS 2026. https://doi.org/10.48550/arXiv.2603.07442
@misc{lim2026lithe,
title = {{LITHE}: Bridging Best-Effort {Python} and Real-Time {C++} for Hot-Swapping Robotic Control Laws on Commodity {Linux}},
author = {Lim, He Kai and Clites, Tyler R.},
year = {2026},
eprint = {2603.07442},
archivePrefix = {arXiv},
primaryClass = {cs.RO},
doi = {10.48550/arXiv.2603.07442},
url = {https://arxiv.org/abs/2603.07442},
note = {Submitted to IROS 2026}
}CSF's architecture is inspired by LITHE [1]. To cite CSF itself, name the exact release tag you used:
@software{csf2026,
title = {CSF — The Cerebrospinal Fluid},
author = {{Candace Labs}},
version = {0.3.0},
year = {2026},
url = {https://github.com/candacelabs/csf}
}The LITHE paper and its figures are distributed under arXiv's non-exclusive distribution license, not a Creative Commons license. © the authors; this repository's license does not cover them. Figure 1 is displayed from arXiv; no figure file is copied into this repository.
[2] D. Tsichritzis and A. Klug. The ANSI/X3/SPARC DBMS framework report of the study group on database management systems. Information Systems 3(3):173–191, 1978. https://doi.org/10.1016/0306-4379(78)90001-7
[3] E. F. Codd. A relational model of data for large shared data banks. Communications of the ACM 13(6):377–387, 1970. https://doi.org/10.1145/362384.362685
[4] G. Kiczales, J. Lamping, A. Mendhekar, C. Maeda, C. Lopes, J.-M. Loingtier and J. Irwin. Aspect-oriented programming. ECOOP '97, LNCS 1241, pp. 220–242, 1997. https://doi.org/10.1007/BFb0053381
[5] D. Ongaro and J. Ousterhout. In search of an understandable consensus algorithm. 2014 USENIX Annual Technical Conference (USENIX ATC 14), pp. 305–319, 2014. https://www.usenix.org/conference/atc14/technical-sessions/presentation/ongaro
[6] Hugging Face. xet-core: the Xet storage protocol, client and content-addressed chunk format. https://github.com/huggingface/xet-core
[7] Git LFS contributors. Git Large File Storage. https://git-lfs.com/
[8] M. Stonebraker and L. A. Rowe. The design of POSTGRES. Proceedings of the 1986 ACM SIGMOD International Conference on Management of Data, pp. 340–355, 1986. https://doi.org/10.1145/16894.16888
[9] T. Freeman and F. Pfenning. Refinement types for ML. Proceedings of the ACM SIGPLAN 1991 Conference on Programming Language Design and Implementation (PLDI), pp. 268–277, 1991. https://doi.org/10.1145/113445.113468
[10] N. Fulton, S. Mitsch, J.-D. Quesel, M. Völp and A. Platzer. KeYmaera X: an axiomatic tactical theorem prover for hybrid systems. CADE-25, LNCS 9195, pp. 527–538, 2015. https://doi.org/10.1007/978-3-319-21401-6_36
[11] R. Bohrer, Y. K. Tan, S. Mitsch, M. O. Myreen and A. Platzer. VeriPhy: verified controller executables from verified cyber-physical system models. PLDI 2018, pp. 617–630, 2018. https://doi.org/10.1145/3192366.3192406
[12] X. Leroy. Formal verification of a realistic compiler. Communications of the ACM 52(7):107–115, 2009. https://doi.org/10.1145/1538788.1538814
[13] G. Klein, K. Elphinstone, G. Heiser, J. Andronick, D. Cock, P. Derrin, D. Elkaduwe, K. Engelhardt, R. Kolanski, M. Norrish, T. Sewell, H. Tuch and S. Winwood. seL4: formal verification of an OS kernel. SOSP 2009, pp. 207–220, 2009. https://doi.org/10.1145/1629575.1629596
[14] P. Xia, R. Han, Z. Wang, Y. Chen, Y. Zhuang, Y. Lee, C. Huang, H. Yu, Z. CuiZhu, Y. Ming, H. Yao, B. Gokturk, T. Pfister and C.-Y. Lee. RRSI: Regularized Recursive Self-Improvement of Agent Harnesses. arXiv:2609.24972, 2026. https://arxiv.org/abs/2609.24972
The north star's "Builds on" column links KeYmaera X [10], VeriPhy [11], CompCert [12] and seL4 [13].
Apache License 2.0. See LICENSE.
AI systems assisted with work in this repository. Their output is not presumed correct, secure, reviewed, or production-ready.