--- title: Keel — Architecture name: keel category: architecture created: 2026-06-04 updated: 2026-06-04 tags: - keel - human-harness - architecture - antidrift - activitywatch status: authoritative --- # Keel — Architecture > **Name & home.** *Keel* is the system: a human-harness that helps Felix hold > course toward his higher goals. The name answers AntiDrift's metaphor — *drift* > is what a vessel does with nothing to hold it; the *keel* resists drift and > keeps you on an even keel (steady mind). **This repo (`antidrift`) is Keel's > seed**: AntiDrift's focus harness becomes Keel's first *mode*. The code/repo > rename is **deferred** until the controller-refactor decision (§8); for now > only this design doc lives here as the authoritative home. Moved from > `~/dev/higher/` on 2026-06-04 — that directory was the scaffold where the > decision to extend AntiDrift was made, and now retires. --- ## 1. What we're building (one sentence) **A harness** — a framework that pulls Felix's real state out of his existing tools, hands it to a swappable brain, and turns the reply into actions and two surfaces. The brain, the storage, and the data sources are all **reused**; the harness is the only thing we build. The target is one system (Keel — the single screen), grown by **loosening AntiDrift's controller**, not by starting over. The inversion holds: this is a *human-harness*. In an agent harness a model is the observed worker; here Felix is the observed subject and the model is the operator. --- ## 2. Core decisions (locked 2026-06-04) 1. **The product is the harness.** The brain (`claude` / `codex` / **Hermes**) is rented, interchangeable compute reached over a CLI or the network — *not* the point. The value is the framework that feeds information *in* and acts on what comes *back*. Hermes is real (an agent harness on another machine); it is one brain option, not a dependency. 2. **Reuse AntiDrift's engine; loosen its controller.** AntiDrift already is this harness for one plane. Its controller is welded to *commitment = next_action + success_condition + timebox*. We loosen that into a general **collect → brain → act** loop where a focus-session is just **one mode**. Other modes: house, body, review, capture, planning. The core architecture is salvageable — we widen scope, we don't rebuild. - Worked example (a non-focus mode): from the phone web UI, *"what work on the house should I do next?"* → the harness reads the house bugs/tasks, the brain proposes a strategy, the UI asks Felix for feedback, and on approval an effector files the task. 3. **Storage = ActivityWatch.** AW is already a general append-only event store with a REST API, and it is currently the single richest *unused* asset (~1 yr / ~287k events). Keel gets its **own AW bucket(s)** for memory. **No new database, no new event store.** AW is therefore both a *sensor* (screen-time ground truth) and the *store* (Keel's memory). 4. **Two surfaces, both — no fork.** - **Web UI** — configure, interact, discuss; phone-friendly. The place Felix *talks to* Keel. - **WM status bar** — reflect current status (AntiDrift already writes `~/.antidrift_status`). The reminder sentence lives here; it is one *status element*, **not** a deliverable. (No "nice summaries" as a product.) 5. **Life-information root = `~/owc`** (owncloud markdown), formerly called "clawd". Values, goals, the 22 `resources/bug-*.md`, weekly reviews, self-management frameworks, capture stream. **Reference, never duplicate.** 6. **Effectors: start gated, trend toward autonomy.** Day one: read + *propose, Felix confirms in the web UI*. Target: the brain does a lot on its own — **update Beeminder datapoints, update Marvin to-dos, update `~/owc` notes.** The gate (propose-and-confirm vs. just-do-it) is a **config surface per effector**, not a vibe — this is the agency-vs-cage line and it stays Felix's to set. 7. **Still in force:** don't build a new event store; AntiDrift is the substrate; reference source-of-truth; local-first; every session ends with visible proof; the status line stays small. --- ## 3. The harness (the components we build) ``` SOURCES (read) KEEL (the framework = the product) BRAIN (swappable) ───────────── ────────────────────────────────────── ────────────────── AW :5600 ───────┐ ┌──────────────────────────────────────┐ claude (local CLI) AntiDrift ──────┤ feed │ ① COLLECTORS → ③ ASSEMBLER → [BRAIN] │ send ──▶ codex (local CLI) HQ hq.db ───────┤ ───────▶ │ ▲ │ │ Hermes (remote API) Consume :8000 ──┤ │ │ ▼ │ ◀─ reply daily.db :2200 ─┤ │ ② MEMORY = AW buckets ④ EFFECTORS │ (just compute; Beeminder ──────┤ │ (reuse AW; no new DB) │ │ interchangeable) Marvin ammcp ───┘ └────────────────────────────────┼─────┘ ~/owc (frame) ──── grounds the brief ────────────────────────┤ ⑤ renders to ──┴──────────┐ ▼ ▼ WEB UI WM STATUS BAR (configure/interact/discuss) (current status) ``` Each component has one job, a defined interface, and can be built/tested alone: - **① Collectors** — one small read-only adapter per source. Contract: `read(window) -> Signal[]`. Today's real interfaces: AW `POST :5600/api/0/query/`; AntiDrift `tail ~/.antidrift/audit.jsonl` (+ live SSE `:7777/events`); HQ read-only `hq.db` (+ `:8765`); Consume `GET :8000/api/...`; daily read-only `daily.db` (+ `:2200`); Beeminder `beeline`; Marvin `ammcp` MCP / `am --json`. Depends only on the source being up; degrades to a dropped signal if not. - **② Memory** — AW buckets owned by Keel. Keel writes its own derived events here (mode_started, proposal_made, action_taken, spiral_flagged, …) so it *remembers across runs* and can see trends a single tool can't. Rebuildable, queryable via AW's REST API. Depends on AW only. (See §7.) - **③ Context assembler** — builds the brief handed to the brain = relevant collector signals + memory (recent + trend) + the `~/owc` frame (the value/goal at stake, the relevant `bug-*.md`). Budgets it. Depends on ① ② and `~/owc`. Privacy boundary lives here: titles that can leak secrets are filtered before they reach the brain. - **Brain adapter** — pluggable. Local: shell `claude --print` / `codex exec` (exactly what AntiDrift's `ai.Backend` already does). Remote: call Hermes over the network. Interface: `decide(brief) -> {status, proposals[]}`. Keel treats it as a black box; swapping it changes nothing else. - **④ Effectors** — one gated adapter per write target. Today's safe writes: Marvin task create/complete (`am` / `ammcp`, **preserve the `fieldUpdates` CRDT** on write), capture append (one file), AntiDrift start-session / enforce. Roadmap writes: Beeminder datapoint (`beeline`), `~/owc` note edits. Each effector reads its gate from config (propose-and-confirm | auto). - **⑤ Surfaces** — render Keel's state. Web UI (rich, phone-friendly, the interaction/approval surface) and the WM status bar (one live line). Both read the same Keel state; neither owns data. - **Control loop / scheduler** — drives the cycle: when to collect, when to think, when to surface, when to act. Cheap triggers (a switch-count spike, a Beeminder losedate approaching, a manual web-UI request) decide when to spend a brain call, instead of polling the LLM blindly. This is AntiDrift's state machine, generalized past the single session. - **Policy / gates** — per-effector authority + the value frame. Felix's dial from "read-only" to "act freely". Configured in the web UI. --- ## 4. AntiDrift is the seed, not a peer Keel is AntiDrift's port set, widened. The parts already exist: | Keel part | AntiDrift today | Keel (generalized) | |---|---|---| | Collectors | `evidence.Source` (X11), `tasks.Provider` (Marvin) | + AW, HQ, Consume, daily, Beeminder, `~/owc` | | Frame | `knowledge.Source` → one file | `~/owc`: values, goals, 22 `bug-*.md`, frameworks | | Brain | `ai.Backend` → local `claude`/`codex` | + Hermes (remote); pluggable interface | | Memory | ephemeral (dies in `state.json`) | **AW buckets** (durable, queryable) | | Effectors | `enforce.Guard` (window-minimize) | + Marvin, capture, Beeminder, `~/owc` notes | | Surfaces | web UI `:7777` + `~/.antidrift_status` | richer web UI (phone) + status bar | | Control loop | session state machine (locked/planning/active/review) | **modes** (focus is one); a session is one mode | **Loosening the controller** concretely means: generalize `Commitment` from a work-session into a *mode invocation* (a mode has its own collectors, frame slice, brain prompt, and allowed effectors); the focus-session remains the `next_action/success_condition/timebox` mode; a "house" mode reads house bugs and proposes a strategy; a "capture" mode just routes a thought. The runtime state machine becomes the loop in §3. --- ## 5. One loop, concrete House mode, from the phone, end to end: 1. **Collect** — `~/owc/resources/bug-*.md` house items + Marvin "house" tasks + (memory) what was proposed/done last weekend. 2. **Remember** — read Keel's AW `keel.state` bucket for prior house proposals so it doesn't repeat itself. 3. **Assemble** — those + the `house-integrity` goal from `~/owc/goals-2026.md`. 4. **Brain** — chosen brain returns a proposed next house task + short strategy. 5. **Surface** — web UI shows the proposal and asks for feedback. 6. **Act** — on approval, the Marvin effector files the task; Keel writes an `action_taken` event to its AW bucket (memory closes the loop). No new store touched. The brain was rented for one call. Everything else was Keel. --- ## 6. Sources & targets (the real ecosystem) | Tool | Read | Write | Role | Source of truth | |---|---|---|---|---| | ActivityWatch | `POST :5600/api/0/query/`, sqlite | new buckets via REST | sensor **+ store** | `peewee-sqlite.v2.db` | | AntiDrift | `audit.jsonl`, SSE `:7777` | `POST :7777` cmds, enforce | focus mode + enforcement | `~/.antidrift/` | | HQ | `hq.db` r/o, `:8765` | `dashboard.write_artifact` | agent-execution evidence | `hq.db` (~23k events) | | Consume | `GET :8000/api` | (later) | intake/reflection signal | item frontmatter | | daily | `daily.db` r/o, `:2200` | — | mood/habit checkout | `daily.db` | | Beeminder | `beeline` | `beeline` datapoints | committed-evidence rollups | Beeminder API | | Marvin | `ammcp` / `am --json` | `am` / `ammcp` (keep CRDT) | intent / to-dos / bugs | CouchDB | | `~/owc` | markdown globs, `.zk` | note edits (later) | values/goals/bugs frame | `~/owc` files | | Brain | — | — | rented compute | claude/codex/Hermes | Known frictions Keel inherits (from the survey): beesync has **no scheduler** (Beeminder data lags; `[daily]` bridge commented out); the life-bug concept is **forked** (22 rich `~/owc` markdown bugs vs. 5 thin Marvin tasks); **capture is broken** (`blurt` → clipboard, dead `inbox.md`, two rival `stream.md`); AW's year of data is read by nothing today. --- ## 7. Memory in ActivityWatch (the storage design) AW is a typed, append-only, timestamped event store with buckets + a REST/query API — i.e. it is already the event store the §0 correction said not to rebuild. Keel gets dedicated buckets (e.g. `keel.state`, `keel.events`) and writes **derived** events: `mode_started`, `proposal_made`, `feedback_given`, `action_taken`, `spiral_flagged`, `coach_line`. Properties: - **Reference, don't duplicate** — these hold pointers (a Marvin id, a `bug-*.md` path, an audit `session_id`), not copies of other tools' truth. - **Rebuildable** — derivable from the underlying ledgers; AW is a cache/index of Keel's own decisions plus a join surface over the sources. - **Queryable over time** — this is what unlocks trend/spiral detection ("caffeine bug + mood dip + rising switches, same shape as three weeks ago") that no single tool can do, because each tool only answers "what now". Open sub-decision: whether work-laptop AW data is peer-synced in (cross-device behavioral story) or left out initially. --- ## 8. Open questions (not yet decided) - **Effector gate policy** — exact default authority per write target on day one, and how Felix raises/lowers it from the web UI. - **Capture unification** — which single file is canonical (resolve `~/owc/stream.md` vs `~/wrk/pkb/stream.md` vs dead inboxes) and rewiring `blurt` to append there. - **Controller refactor shape** — how invasive the AntiDrift generalization is; do we branch the daemon or grow it in place. **This is also the trigger for the repo/code rename to `keel`.** - **Cross-device AW** — sync work-laptop AW or not (see §7). - **Secret hygiene** — an increasingly autonomous operator runs as the full Unix user; plaintext keys exist on disk; the privacy boundary in ③ must be real. --- ## 9. What this supersedes (from `~/dev/higher/`) - The whole `~/dev/higher/` planning directory: it was the scaffold for deciding to extend AntiDrift. This doc is now the authoritative home; that dir retires to a pointer. - "clawd" → **`~/owc`** everywhere. - The plan's premise that the operator "already knows Felix via `~/.hermes`" and the survey finding "Hermes doesn't exist" are both resolved: **Hermes is real but remote, and the brain is pluggable** — grounding comes from the `~/owc` frame regardless of which brain runs. - The plan's §6 recommendation ("a thin *reader* layer is the real architecture") is **superseded**: the reader is merely the **collectors layer** of Keel. The target is the full system (one screen, two surfaces, durable memory, gated→autonomous effectors), grown from AntiDrift. - "Don't build an event store" is **sharpened**: storage = **ActivityWatch buckets**. --- ## 10. Smallest real slice (a vertical, not a summary) To stay honest to "ship visible proof" without boiling the ocean: the first slice is **house mode, end to end** (§5) on the existing AntiDrift web surface — one collector (`~/owc` house bugs + Marvin), the brain, the web UI proposal, and the Marvin effector behind a confirm gate. It exercises every Keel component once, on the smallest mode, and produces a real filed task — interaction and action, not a coaching sentence.