ollie/doc/9p.md

9P Filesystem: Everything is a File

The 9P namespace is the lowest-level interface to ollie. Everything — sessions, agents, prompts, tools, state — is a file. The o CLI wraps these operations, but the raw filesystem is the foundation.

Mounting

ollie-9p mount unix!/tmp/ns.$USER.$DISPLAY/ollie ~/mnt/ollie
cd ~/mnt/ollie
ls session/

Or connect remotely:

ollie-9p mount tcp!server:9564 ~/mnt/ollie

Raw session operations

# Create a session
echo "name={sname}" > session/new

# Submit a prompt
echo "fix the bug in main.go" > session/{sname}/agent/{aname}/prompt

# Stream the response
cat session/{sname}/agent/{aname}/chat

# Check state
cat session/{sname}/agent/{aname}/state

# Block until state changes
cat session/{sname}/agent/{aname}/statewait

# Read offset (byte position after user prompt)
cat session/{sname}/agent/{aname}/offset

Network transparency

9P is a network protocol. Mount the agent namespace from any machine and every session, tool, and config value is accessible as if local:

# From another machine:
9p -a 'tcp!server:5640' read session/{sname}/agent/{aname}/state

No SSH tunneling, no port forwarding, no API gateway.

Shell composability

Because operations are file I/O, they compose with the full Unix toolkit:

# Fan out a prompt to all agents
for s in session/*/agent/*/prompt; do echo "run tests" > "$s"; done

# Wait for all agents to finish
for s in session/*/agent/*/statewait; do cat "$s" > /dev/null; done

# Grep all agent plans
grep -r "TODO" session/*/agent/*/plan

# Monitor costs
cat session/*/agent/*/cost

# Strip block markup from chat output
cat session/{sname}/agent/{aname}/chat | grep -vE '^\[\[\[.*'

Pipe agents into awk. Filter with grep. Schedule with cron. Orchestrate with a 10-line shell script instead of a framework.

Plan 9 patterns

• /net/dns pattern — /generate and ctl are stateless per-fid: write a request, read back the result
• ctl files — control operations (stop, kill, rename, compact) are writes to a control file, not method calls
• Blocking reads — statewait blocks until state changes, replacing event subscriptions with a simple cat
• Multiplexing — multiple clients mount the same server simultaneously, each with an independent view through per-fid state

/generate — one-shot LLM

echo 'summarize this repo' | ollie-9p rdwr generate
cat main.go | ollie-9p rdwr generate
echo '{"prompt":"explain recursion"}' | ollie-9p rdwr generate

Key files per agent

File	Mode	Description
prompt	write	Queue a new turn
fifo	r/w	Prompt queue (write=enqueue, read=dequeue)
statewait	read (blocking)	Blocks until state changes
chat	read (streaming)	Filtered text (no markers/fences)
chat.raw	read (streaming)	Full markup with block markers
log	read	Last 64KB of conversation (non-blocking)
plan	r/w	Scratch space for agent planning
cfg	r/w	Agent config (key=value)
ctl	rdwr	Control commands (write cmd, read response)
stats	read	Token usage, cost, context size (key=value)
name	r/w	Mutable agent name
id	read	Immutable agent UUID
proc/{pid}	read	Detached process output