ollie/doc/resources/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/*/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 — /complete, /generate, /route 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

/complete — code completion

Fill-in-the-middle:

echo '{"file":"main.go","prefix":"func ","suffix":""}' | ollie-9p rdwr complete

/route — task routing

echo 'implement login page' | ollie-9p rdwr route
# backend=anthropic model=claude-sonnet-4-20250514

Key files per agent

File	Mode	Description
prompt	write	Queue a new turn
statewait	read (blocking)	Blocks until state changes
state	read	Current state
chat	read	Full conversation history
context	read	Full message history as JSONL
offset	read	Byte position after last user prompt
plan	r/w	Scratch space for agent planning
prompt.prev	read	The last submitted prompt
env	read	Session environment variables
cost	read	Cumulative cost in USD