ollie/doc/USAGE.md

Usage

Server

Start and stop

olliesrv start          # start in background (daemonizes)
olliesrv fgstart        # start in foreground
olliesrv stop           # stop the daemon
olliesrv status         # check if running

By default the server mounts at $HOME/mnt/ollie. Override with -mount:

olliesrv start -mount /tmp/ollie

TCP listener

To also accept connections over TCP (e.g. for remote access):

olliesrv start -tcp :9564

Debug logging

Log level is controlled by OLLIE_LOG (default: warn). Set to debug for verbose output:

OLLIE_LOG=debug olliesrv fgstart

Valid levels: debug, info, warn, error. Per-subsystem overrides follow the pattern OLLIE_<TAG>_LOG=debug where <TAG> matches the logger's tag (e.g. OLLIE_SESSION_LOG).

---

Examples below assume $OLLIE is set to the ollie mount point (default: $HOME/mnt/ollie). Scripts under s/ and u/ are available directly via the mounted filesystem after running mk && mk scripts.

Interactive shell

s/sh is an interactive shell for prompting a session. It resumes the most recent session for the current working directory by default, or creates a new one if none exists.

exec $OLLIE/s/sh                                       # resume or create session for pwd
exec $OLLIE/s/sh -new                                  # always start a fresh session
exec $OLLIE/s/sh -new -model qwen3:8b                  # fresh session with model override
exec $OLLIE/s/sh -session 1744276689123456789-2b986c   # attach to a specific session

At the > prompt:

Input	Action
<text>	Submit prompt; response streams to terminal
/q <text>	Queue prompt for later execution (writes to fifo.in)
/<cmd>	Send to session ctl (e.g. /compact, /clear, /model qwen3:8b)
/kill	Kill the session and exit
Ctrl-C	Interrupt a running turn (or exit if idle)

s/sh tracks the last session per working directory in ~/.config/ollie/last-session, so switching directories and re-running s/sh resumes the right context automatically.

One-shot queries

s/bfg and s/bbg submit a single prompt to a new session. The difference is only in how the caller is treated: s/bfg blocks until the agent finishes and writes the result to stdout; s/bbg returns immediately and prints the path of the session.

Both are thin wrappers around s/b, which is the core one-shot runner.

s/bfg

Submit a prompt, wait for completion, print the result:

$OLLIE/s/bfg "Summarize this repo"
cat main.go | $OLLIE/s/bfg "explain this file"
$OLLIE/s/bfg -parallel 4 -keep "Write a haiku"
$OLLIE/s/bfg -backend ollama -model qwen3:8b "Explain this" < main.go

With -parallel N, N jobs run concurrently and results are printed as they complete.

s/bbg

Submit a background job and return immediately; prints the s/{id} path:

$OLLIE/s/bbg "summarize the recent git log"
# /home/lkn/mnt/ollie/s/1744276689123456789-0

Poll for completion:

path=$($OLLIE/s/bbg "write a limerick about Go")
until [ "$(cat $path/statewait)" = "idle" ]; do :; done
tail -c +$(($(cat $path/offset) + 1)) $path/chat

Fan out with -parallel N and collect results:

paths=$($OLLIE/s/bbg -parallel 4 "draft a blog intro" < brief.txt)
for p in $paths; do
    until [ "$(cat $p/statewait 2>/dev/null)" = "idle" ]; do :; done
    tail -c +$(($(cat $p/offset) + 1)) $p/chat
    rm -r $p
done

s/cleanup

Remove all idle sessions:

$OLLIE/s/cleanup

Schedule regular cleanup with a cron job:

*/15 * * * * /path/to/mnt/ollie/s/cleanup

Raw s/ access

cat $OLLIE/s/new                           # show the spec template
printf 'cwd=%s\n---\nSummarize this.\n' "$PWD" > $OLLIE/s/new
cat $OLLIE/s/<session-id>/state            # running | idle | failed: <reason>
cat $OLLIE/s/<session-id>/chat
rm -r $OLLIE/s/<session-id>               # cancel and remove

Valid spec keys: name (auto-generated if omitted), cwd (required), agent, backend, model.

AI pipelines

s/bfg writes to stdout and composes naturally with Unix pipes. When both args and stdin are present, args are treated as the instruction and stdin as the content:

echo "write a haiku about filesystems" | $OLLIE/s/bfg | wc -w
cat error.log | $OLLIE/s/bfg "what is causing this?" | $OLLIE/s/bfg "suggest a fix"
$OLLIE/s/bfg "list 5 blog post ideas" | grep -v "^$" | head -3 | $OLLIE/s/bfg "expand the best one"

u/optimize is a worked example — it generates N candidate prompts in parallel via s/bfg -parallel N, then judges them with a second s/bfg call to return the best:

$OLLIE/u/optimize -n 3 -cm qwen/qwen3-8b -jm anthropic/claude-opus-4-6 "explain recursion"

Progress goes to stderr; pipe the optimized prompt with content into a subsequent call:

prompt=$($OLLIE/u/optimize "translate this to Spanish" 2>/dev/null)
cat document.txt | $OLLIE/s/bfg "$prompt"

Alternative front-ends

The 9P filesystem is the lowest level interface to ollie. All interfaces are simply wrappers around filesystem operations, and s/sh is the standard chat interface. A couple of other front-ends are also provided:

• ollie-tui — a fancier terminal UI for the less curmudgeonly
• ellie — ellie.el is the Emacs front-end, just wire it into your init.el and M-x ellie

See each repo's README for installation and usage.