lkn
/
ollie
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
ollie/scripts/README.md

8.5 KiB
Raw Blame History

scripts

Shell scripts for interacting with the ollie 9P filesystem. All scripts read OLLIE (default: $HOME/mnt/ollie) for the mount path.

mk scripts installs them and exposes them via the mounted filesystem, so they are available without any $PATH changes:

exec $OLLIE/s/sh              # start interactive shell
$OLLIE/s/ls                   # list sessions
$OLLIE/s/kill <id>            # kill a session
$OLLIE/s/bfg "my prompt"      # foreground one-shot query; blocks until done
$OLLIE/s/bbg "my prompt"      # background one-shot query; prints session path
$OLLIE/s/cleanup              # remove all idle sessions
$OLLIE/u/optimize "prompt"    # generate and return best optimized prompt

Scripts are organized by the filesystem namespace they are hosted under:

  • s/ — session management and one-shot query scripts
  • u/ — utility scripts; compositions of other ollie primitives
  • x/ — elevation plugins; called by execute_code for privileged steps

s/sh

Interactive chat interface for ollie sessions. Resumes the most recent session for the current directory by default; creates a new one if none exists.

s/sh [-new] [-resume] [-session ID] [-cwd DIR] [-backend B] [-model M] [-agent A]

Flags

Flag Description
-new Always create a new session
-resume Resume last session for the cwd; error if none
-session ID Attach to a specific session by ID
-cwd DIR Working directory (default: pwd)
-backend B Backend override (e.g. ollama, anthropic)
-model M Model override
-agent A Agent config name

Input

At the > prompt:

Input Action
<text> Submit prompt, stream response
/q <text> Enqueue prompt for later
/<cmd> Send to session ctl (e.g. /compact, /clear)
/kill Kill the session and exit
Ctrl-C Interrupt running turn (or exit if idle)

Examples

s/sh                          # resume or create session for pwd
s/sh -new -model gpt-4o       # fresh session with model override
s/sh -session 1745123456-abc  # attach to a specific session

s/ls

List all active sessions.

s/ls

s/kill

Kill a session by ID and remove it.

s/kill <id>

s/bfg

Foreground one-shot query. Submits a prompt to a new session, blocks until the agent is done, writes the result to stdout, then removes the session. Exit code is non-zero on failure. Thin wrapper around s/b.

s/bfg [flags] [prompt...]
echo "prompt" | s/bfg [flags]

Accepts the same flags as s/b.

Examples

s/bfg "Summarize this repo in one sentence"
cat error.log | s/bfg "What is causing this error?"
s/bfg -output json "List the top 3 risks as JSON"
s/bfg -parallel 4 -keep "Write a haiku about filesystems"
s/bfg -backend ollama -model qwen3:8b "Explain this function" < main.go

s/bbg

Background one-shot query. Submits a prompt to a new session and returns immediately; prints the s/{id} path for each job. Thin wrapper around s/b -bg.

s/bbg [flags] [prompt...]
echo "prompt" | s/bbg [flags]

Accepts the same flags as s/b.

Examples

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

s/b

Core one-shot runner. Submits a prompt to a new session, optionally waits, and handles parallel fan-out. s/bfg and s/bbg are both wrappers around this script.

s/b [flags] [prompt...]
echo "prompt" | s/b [flags]

Flags

Flag Description
-name N Base session name; sessions are suffixed -1, -2, ...
-cwd DIR Working directory (default: pwd)
-agent A Agent config name
-backend B Backend override
-model M Model override
-json Append JSON-only instruction to prompt
-parallel N Run the same prompt N times in parallel (default: 1)
-keep Do not remove session(s) after printing result
-bg Submit and exit immediately; prints session path(s); implies -keep
-failfast On first failure, cancel remaining parallel jobs and exit

s/cleanup

Remove all idle sessions.

s/cleanup

u/optimize

Generates N candidate optimized prompts, judges them, and returns the best one to stdout. Debugging output (progress messages) goes to stderr.

u/optimize [flags] [prompt...]
echo "prompt" | u/optimize [flags]

Flags

Flag Description
-n N Number of candidates to generate (default: 3)
-cb B Candidate generation backend
-cm M Candidate generation model
-jb B Judge backend
-jm M Judge model

Examples

u/optimize "Summarize this document"
u/optimize -n 5 -cm qwen/qwen3-8b -jm anthropic/claude-opus-4.6 "Write a haiku"
u/optimize "generate a hello world program. use c++." >[2]/dev/null | s/bfg

Outputs to stdout, making it composable with other pipeline stages.

x/elevate

Elevation plugin invoked by execute_code when a step is marked elevated: true. Runs the command outside the sandbox and returns its output.

Interface

execute_code resolves the plugin path and calls:

x/elevate -- <cmd>

The working directory is already set to the session's cwd before the call. The script must:

  • Write combined stdout/stderr to its own stdout
  • Exit with the command's exit code (non-zero is treated as failure)

That's the entire contract. Any script that satisfies it is a valid elevation backend.

The plugin is looked up in OLLIE_PLUGINS_PATH (first colon-separated entry) if set, otherwise in ~/.config/ollie/scripts/x/. Override via env to use a different location without modifying the installed scripts.

Minimal example

The simplest possible backend — unsandboxed exec, no privilege escalation:

#!/bin/sh
# x/elevate: run command outside the sandbox with no additional privileges.
shift  # drop the '--'
exec sh -c "$1"

This is useful for development or environments where the sandbox is the only restriction that needs lifting.

superpowerd example

The default x/elevate uses superpowerd as the elevation backend. superpowerd is a hypothetical privilege broker: it holds a session token, receives ExecuteCommand requests over a Unix socket, and runs them with the permissions granted to the session.

How it works, step by step:

  1. If SUPERPOWERD_SESSION_TOKEN is not in the environment, the script re-execs itself under superpowers run-session, which acquires a token and re-runs the script inside a privileged session context:

    if "SUPERPOWERD_SESSION_TOKEN" not in os.environ:
    os.execvp("superpowers", ["superpowers", "run-session", "--",
                               sys.executable, __file__] + sys.argv[1:])

  2. With the token present, the script connects to the superpowerd Unix socket. The socket path is resolved in order from SUPERPOWERD_SOCKET, SUPERPOWERD_SOCKET_DIR/superpowerd.sock, $XDG_RUNTIME_DIR/superpowerd/superpowerd.sock, or the default /run/user/<uid>/superpowerd/superpowerd.sock.

  3. A JSON-RPC ExecuteCommand request is sent with the token, command string, and cwd:

    {
  "jsonrpc": "2.0",
  "method": "ExecuteCommand",
  "id": 1,
  "params": {
    "auth": {"session_token": "<token>"},
    "command": "<cmd>",
    "working_dir": "<cwd>",
    "approval_timeout": 7200
  }
}

  4. The response's stdout, stderr, and exit_code are forwarded back to execute_code.

Session token injection

Because olliesrv is a long-running daemon, it does not inherit environment variables from the front-end process. SUPERPOWERD_SESSION_TOKEN must be injected into the session explicitly via the session's env file before any elevated step runs:

printf 'SUPERPOWERD_SESSION_TOKEN=%s\n' "$SUPERPOWERD_SESSION_TOKEN" \
    > $OLLIE/s/<session-id>/env

The simplest approach is to launch the front-end itself inside a superpowers session (superpowers run-session ollie-tui ...), which sets the token in the environment before the front-end creates any sessions.

Custom backends

Replace ~/.config/ollie/scripts/x/elevate with any executable. Examples:

sudo:

#!/bin/sh
shift
exec sudo sh -c "$1"

doas:

#!/bin/sh
shift
exec doas sh -c "$1"

Disabling elevation: replace x/elevate with a script that exits non-zero. Steps marked elevated: true will then fail rather than run unsandboxed:

#!/bin/sh
echo "elevation disabled" >&2
exit 1