108 lines
4.8 KiB
Markdown
108 lines
4.8 KiB
Markdown
# ollie
|
|
|
|
What happens if agent primitives are exposed as an ordinary filesystem? How much can be subtracted from AI agent implementations without reducing their usefulness? These are some of the motivating questions behind `ollie`.
|
|
|
|
- The [core system](https://github.com/lneely/ollie-core) provides a public library of AI agent primitives.
|
|
- The [9p filesystem server (Go)](https://github.com/lneely/ollie-9p) creates a virtual filesystem exposing the important state and behaviors as ordinary files and operations.
|
|
- A reference [TUI](https://github.com/lneely/ollie-tui) implementation proves that it is possible to build a functioning and user-friendly terminal front-end using only the Go standard library.
|
|
- And, just because I like my Emacs friends, a reference [Emacs interface](https://github.com/lneely/ollie-el) front-end implementation.
|
|
|
|
## Project Structure
|
|
|
|
- `core/`:
|
|
- `tui/`:
|
|
- `9p/`:
|
|
- `el/`:
|
|
|
|
## Getting Started
|
|
|
|
Clone with submodules:
|
|
|
|
```bash
|
|
git clone --recurse-submodules https://github.com/lneely/ollie.git
|
|
```
|
|
|
|
Or after cloning:
|
|
|
|
```bash
|
|
git submodule update --init --recursive
|
|
```
|
|
|
|
## Building
|
|
|
|
Build everything from the monorepo root:
|
|
|
|
```bash
|
|
mk
|
|
```
|
|
|
|
Or build specific components:
|
|
|
|
```bash
|
|
mk core # Build core library
|
|
mk tui # Build terminal UI
|
|
mk 9p # Build 9p filesystem server
|
|
```
|
|
|
|
For Emacs Lisp, copy `el/ollie.el` into your own Emacs configuration directory, and:
|
|
|
|
```lisp
|
|
(require 'ollie)
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### Environment: `~/.config/ollie/env`
|
|
|
|
```
|
|
OLLIE_BACKEND=openai # ollama | openai | openrouter | anthropic | copilot | kiro (default: ollama)
|
|
OLLIE_OLLAMA_URL= # base URL for Ollama (default: http://localhost:11434)
|
|
OLLIE_OPENAI_URL=https://openrouter.ai/api
|
|
OLLIE_OPENAI_KEY=sk-or-...
|
|
OLLIE_ANTHROPIC_KEY=sk-ant-...
|
|
OLLIE_COPILOT_TOKEN=...
|
|
OLLIE_KIRO_TOKEN=... # bearer token or sqlite:// path (auto-detected from Kiro CLI if unset)
|
|
OLLIE_MODEL=qwen/qwen3-235b-a22b
|
|
OLLIE_TOOLS_PATH=~/.config/ollie/tools # directory for execute_tool scripts
|
|
OLLIE_MEMORY_PATH=~/.config/ollie/memory # directory for memory files (ollie/m)
|
|
```
|
|
|
|
Shell environment variables take precedence over the env file.
|
|
|
|
## Development
|
|
|
|
Update all submodules to latest:
|
|
|
|
```bash
|
|
git submodule update --remote
|
|
```
|
|
|
|
## Observed Benefits
|
|
|
|
**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`. The protocol surface is zero because the protocol *is* the filesystem.
|
|
|
|
**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
|
|
|
|
Many sources of inspiration:
|
|
|
|
- [Plan 9 from Bell Labs](https://9fans.net) — for an interesting system
|
|
- [@9fans](https://github.com/9fans) — for the Plan 9 port
|
|
- [Suckless](https://suckless.org) — for articulating good software development principles
|
|
- [@simonfxr](https://github.com/simonfxr) — for a solid agent baseline to "borrow" from, and other nifty ideas
|
|
- [@aws](https://github.com/aws/amazon-q-developer-cli) — for a solid open-source agent implementation
|
|
|
|
## License
|
|
|
|
GPLv3 |