# 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 tool scripts ({tool} steps)
OLLIE_MEMORY_PATH=~/.config/ollie/memory  # directory for memory files (ollie/m)
```

Shell environment variables take precedence over the env file.

## Remote Access

Because `olliesrv` speaks 9P over TCP, a remote instance can be mounted into the local namespace using `9pfuse`. This means agent sessions, tools, and all other filesystem state on a remote host are accessible as ordinary files — no special client needed.

### Start a remote server

On the remote host (or in a container):

```sh
olliesrv start -tcp :9564
```

### Mount the remote namespace locally

```sh
olliesrv mount remotehost:9564 ~/mnt/remotehost
ls ~/mnt/remotehost      # s/, t/, b/, ...
```

Sessions created under `~/mnt/remotehost/s/` run on the remote host, so tool calls execute close to the remote filesystem rather than over the wire.

### Container

A `Containerfile` is included for running a self-contained remote server:

```sh
podman build --network=host -t olliesrv .
podman run --network=host -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY olliesrv
```

Then mount locally:

```sh
olliesrv mount localhost:9564 ~/mnt/container-ollie
```

## Development

Update all submodules to latest:

```bash
git submodule update --remote
```

## 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