diff --git a/9p b/9p index cf4ccc2..43dff26 160000 --- a/9p +++ b/9p @@ -1 +1 @@ -Subproject commit cf4ccc2cf1944766431caec85e867526bca28910 +Subproject commit 43dff2641521157429827856160922c9ef97f316 diff --git a/doc/USAGE.md b/doc/USAGE.md new file mode 100644 index 0000000..578927a --- /dev/null +++ b/doc/USAGE.md @@ -0,0 +1,208 @@ +# 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. + +```sh +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 | +|---|---| +| `` | Submit prompt; response streams to terminal | +| `/q ` | Enqueue prompt for later execution | +| `/` | 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. + +## Sessions + +### Create + +```sh +cat $OLLIE/s/new # show required/optional KV pairs +echo "cwd=$PWD" > $OLLIE/s/new +echo "cwd=$PWD backend=ollama model=qwen3:8b" > $OLLIE/s/new +``` + +Valid keys: `cwd` (required), `backend`, `model`, `agent`. + +### Send a prompt + +```sh +echo "what files are in the current directory?" > $OLLIE/s//prompt +``` + +Writes dispatch asynchronously on close; the shell returns immediately. + +### Read the conversation + +```sh +cat $OLLIE/s//chat # full history snapshot +tail -f $OLLIE/s//chat # follow output as it arrives +``` + +### Check state + +```sh +cat $OLLIE/s//state +# idle | thinking | calling: +``` + +### Control + +```sh +echo stop > $OLLIE/s//ctl # interrupt current turn +echo compact > $OLLIE/s//ctl # summarize context +echo clear > $OLLIE/s//ctl # clear history +echo kill > $OLLIE/s//ctl # kill session +echo "rn my-name" > $OLLIE/s//ctl +echo "model qwen3:8b" > $OLLIE/s//ctl +``` + +### Switch backend, model, or agent + +```sh +echo ollama > $OLLIE/s//backend +echo qwen3:8b > $OLLIE/s//model +echo myagent > $OLLIE/s//agent +``` + +Writes to `backend`, `model`, and `agent` are rejected when the agent is not idle. + +### Kill and rename + +```sh +rm -r $OLLIE/s/ # kill +mv $OLLIE/s/ $OLLIE/s/my-friendly-name # rename +``` + +## 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: + +```sh +$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`: + +```sh +$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: + +```sh +$OLLIE/b/sched "summarize the recent git log" +# /home/lkn/mnt/ollie/b/1744276689123456789-0 +``` + +Poll for completion: + +```sh +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: + +```sh +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 + +```sh +cat $OLLIE/b/new # show the spec template +printf 'cwd=%s\n---\nSummarize this.\n' "$PWD" > $OLLIE/b/new +cat $OLLIE/b//status # running | done | failed: +cat $OLLIE/b//result +rm -r $OLLIE/b/ # 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: + +```sh +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: + +```sh +$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: + +```sh +$OLLIE/u/optimize "translate this" >[2]/dev/null | $OLLIE/b/q < input.txt +``` + +## Agents + +```sh +ls $OLLIE/a/ # list agents +cat $OLLIE/a/default.json # read config +cp $OLLIE/a/default.json $OLLIE/a/yolo.json # copy +mv $OLLIE/a/old.json $OLLIE/a/new.json # rename +rm $OLLIE/a/scratch.json # delete +``` + +## Example session + +```sh +$ echo "cwd=$PWD" > $OLLIE/s/new +$ exec $OLLIE/s/sh +> list the go files here +assistant: -> execute_code({"code":"find . -name '*.go'","language":"bash"}) += pkg/agent/core.go + pkg/agent/loop.go + ... +assistant: The Go source files are: core.go, loop.go, ... +> /compact +> /model claude-opus-4-6 +```