# 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
```