ollie/doc/USAGE.md

Usage

Examples assume $OLLIE is set to the ollie mount point (default: $HOME/mnt/ollie). Scripts under s/, b/, 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>	Enqueue prompt for later execution
/<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.

Batch jobs

b/ provides ephemeral one-shot agent runs — a single prompt, a single result, no persistent session state.

b/job

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

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

With -parallel N, N jobs run concurrently and results are separated by === {id} === headers.

b/q

Foreground one-shot query; thin wrapper around b/job:

$OLLIE/b/q "what is 2+2?"
echo "what is causing this?" | $OLLIE/b/q

b/sched

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

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

Poll for completion:

path=$($OLLIE/b/sched "write a limerick about Go")
until [ "$(cat $path/status)" = "done" ]; do sleep 0.1; done
cat $path/result

Fan out with -parallel N and collect results:

paths=$($OLLIE/b/sched -parallel 4 "draft a blog intro" < brief.txt)
for p in $paths; do
    until [ "$(cat $p/status 2>/dev/null)" = "done" ]; do sleep 0.1; done
    cat $p/result
    rm -r $p
done

Raw b/ access

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

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

AI pipelines

b/job and b/q write to stdout, so they compose naturally with Unix pipes:

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

u/optimize is a worked example — it generates N candidate prompts in parallel via b/q -parallel N, then judges them with a second b/q 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; the winning prompt goes to stdout, making it pipeable:

$OLLIE/u/optimize "translate this" >[2]/dev/null | $OLLIE/b/q < input.txt

Alternative front-ends

The s/sh shell and b/* scripts are the lowest-level interface to ollie. Two higher-level front-ends are available:

• ollie-tui — terminal UI with a readline loop, split input, and output rendering. The reference interactive front-end.
• ollie-el — Emacs front-end with a chat buffer, prompt composition, interrupt handling, and session management.

Both speak directly to the ollie-9p filesystem — no separate protocol. See each repo's README for installation and usage.