doc: add USAGE.md; update 9p submodule
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Levi Neely
parent
4a643825ff
commit
c8795964f3
2
9p
2
9p
|
|
@ -1 +1 @@
|
|||
Subproject commit cf4ccc2cf1944766431caec85e867526bca28910
|
||||
Subproject commit 43dff2641521157429827856160922c9ef97f316
|
||||
|
|
@ -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 |
|
||||
|---|---|
|
||||
| `<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.
|
||||
|
||||
## 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/<session-id>/prompt
|
||||
```
|
||||
|
||||
Writes dispatch asynchronously on close; the shell returns immediately.
|
||||
|
||||
### Read the conversation
|
||||
|
||||
```sh
|
||||
cat $OLLIE/s/<session-id>/chat # full history snapshot
|
||||
tail -f $OLLIE/s/<session-id>/chat # follow output as it arrives
|
||||
```
|
||||
|
||||
### Check state
|
||||
|
||||
```sh
|
||||
cat $OLLIE/s/<session-id>/state
|
||||
# idle | thinking | calling: <toolname>
|
||||
```
|
||||
|
||||
### Control
|
||||
|
||||
```sh
|
||||
echo stop > $OLLIE/s/<session-id>/ctl # interrupt current turn
|
||||
echo compact > $OLLIE/s/<session-id>/ctl # summarize context
|
||||
echo clear > $OLLIE/s/<session-id>/ctl # clear history
|
||||
echo kill > $OLLIE/s/<session-id>/ctl # kill session
|
||||
echo "rn my-name" > $OLLIE/s/<session-id>/ctl
|
||||
echo "model qwen3:8b" > $OLLIE/s/<session-id>/ctl
|
||||
```
|
||||
|
||||
### Switch backend, model, or agent
|
||||
|
||||
```sh
|
||||
echo ollama > $OLLIE/s/<session-id>/backend
|
||||
echo qwen3:8b > $OLLIE/s/<session-id>/model
|
||||
echo myagent > $OLLIE/s/<session-id>/agent
|
||||
```
|
||||
|
||||
Writes to `backend`, `model`, and `agent` are rejected when the agent is not idle.
|
||||
|
||||
### Kill and rename
|
||||
|
||||
```sh
|
||||
rm -r $OLLIE/s/<session-id> # kill
|
||||
mv $OLLIE/s/<session-id> $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/<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:
|
||||
|
||||
```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
|
||||
```
|
||||
Loading…
Reference in New Issue