From 0fa5618a38b14aa10ca86064c7eb8dc340944bc7 Mon Sep 17 00:00:00 2001 From: Levi Neely Date: Tue, 14 Apr 2026 20:54:20 +0200 Subject: [PATCH] README: expand Observed Benefits section Co-Authored-By: Claude Sonnet 4.6 --- README.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 6aa9ca4..63fd1cd 100644 --- a/README.md +++ b/README.md @@ -79,11 +79,19 @@ git submodule update --remote ## Observed Benefits -**Filesystem as interface** — if you know how to operate a filesystem, you know how to operate ollie. Rename a session → `mv` the session directory. Start a new session → open `s/new`, fill in the fields, save. Prompt the agent → write your prompt to `s/{id}/prompt`. Check status → `cat s/{id}/state`. Any tool that reads and writes files — shell scripts, `ed`, a GUI file manager, `vim`, Python, even `cat` and `echo` — is already a fully capable ollie client. No SDK, no API, no protocol to learn. +**Filesystem as interface** — if you know how to operate a filesystem, you know how to operate ollie. Any tool that reads and writes files — `ed`, `vim`, Python, `cat`, a shell script — is already a fully capable ollie client. No SDK, no API, no protocol to learn. -**Simple front-ends** — building a front-end is just reading and writing files. A TUI reads `chat`, writes `prompt`, polls `state`. A web UI does the same over a thin bridge. An Emacs mode opens files it already knows how to edit. The protocol surface is zero because the protocol *is* the filesystem. +**Simple front-ends** — building a front-end is just reading and writing files. A TUI reads `chat`, writes `prompt`, polls `state`. The protocol surface is zero because the protocol *is* the filesystem. -**Crash resiliency** — `reasoning_plan` persists plans to the `ollie/pl` filesystem by default. If a session crashes or is killed mid-task, recovery is trivial: point a fresh session at the plan that was being executed. The agent's prompting already tells it how to discover plans in `pl/`, so it can resume cold — reading the plan, seeing which steps are done and which aren't, and picking up where the previous session left off. No context replay, no manual re-prompting, no lost work. +**Crash resiliency** — Memory (`m/`) and plans (`pl/`) are written to persistent storage outside the session. If a session crashes or is killed mid-task, neither is lost — a fresh session picks up where the previous one left off. + +**[Code execution tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool)** — Anthropic describes code execution as "a foundational primitive for building high-performance agents." ollie takes that literally: `execute_code` is the base layer, and `execute_tool` and `execute_pipe` build directly on top of it. New capabilities are added by dropping a script into `t/` and a skill in `sk/` — the tools provide the capability, and the skill tells the agent when and how to use them. + +**Radical transparency** — The rendered system prompt for any session is a plain file: `cat s/{id}/systemprompt` — the prompt the agent is actually running with, not a reconstruction. The prompt parts that compose it are readable in `p/`; the agent can read its own instructions but cannot modify them. The filesystem is the abstraction layer — you need only know how to read and write files. + +**Discoverability** — The filesystem is self-documenting. `ls s/{id}/` shows every control surface. `cat t/idx` and `cat sk/idx` show available tools and skills. When you forget the interface, `cat help` tells you. + +**Composability** — Agents can be composed by piping `reply` into another session's `prompt`. Tools can be composed via `execute_pipe`, chaining `execute_code` and `execute_tool` steps the same way Unix pipes chain programs. Both work because the interface is files. ## Credits