oly

When to use

Use oly start instead of a direct terminal invocation when ANY of these apply:

• The command may prompt for input later (approvals, confirmations, credentials).
• The session must survive terminal closes, disconnects, or agent handoff.
• Logs, replay, or auditability matter.
• Another human or agent may need to resume or inspect the work.

Also use oly to supervise sessions already running under it: list, inspect, send input, stop, restart.

Do not use oly for short, non-interactive commands — a normal terminal is simpler.

Prerequisite

All commands talk to the daemon. If a command fails to connect, start it first:

oly daemon status            # check
oly daemon start --detach    # start if needed

Principles

• Supervisor mindset. Start the job, monitor it, intervene only when needed.
• Small tails first. Use --tail 40; expand only when context is insufficient.
• Fewer polls, longer waits. Set --timeout to match the expected next checkpoint — reduces churn and token cost.
• Machine-readable listing. Use oly ls --json --status running for scripting or structured decisions.
• ID optional. Most commands target the most recently created session when the ID is omitted — pass the ID explicitly when juggling multiple sessions.

Workflow

1) Start

oly start --title "task 1" --cwd /path/to/dir --detach the_cmd --arg1 --arg2

Flag	Purpose
--detach	Return immediately with the session ID.
--disable-notifications	Suppress notifications when you will supervise yourself.
--node <name>	Run on a connected secondary node.

2) Monitor

oly logs <ID> --tail 40 --no-truncate --wait-for-prompt --timeout 10s

• --wait-for-prompt — blocks until the session likely needs input or timeout expires.
• --timeout — accepts 250ms, 10s, 5m, 1h (default 5m). Shorten for fast tasks; lengthen for slow ones.
• On timeout it prints only the Waiting for session ... line and exits 0 with no log output — treat that as "nothing new, decide whether to wait again."
• Start with --tail 40; increase only when recent context is insufficient.

3) Send input

oly send <ID> "hello world!" key:enter
oly send <ID> oly-clipboard
oly send <ID> "cat " oly-file:/path/to/file key:enter

• Arguments are sent left-to-right. Plain text is literal; special keys use key: prefix.
• Keys: key:enter, key:ctrl+c, key:alt+x, key:shift+tab, key:up, key:down.
• Raw hex: key:hex:.... Piped stdin is supported when no positional chunks are given.
• Clipboard content uses oly-clipboard. Local file upload uses oly-file:<path>. This is normally used for remote node sessions.

Input strategy:

Scenario	Action
Menu / TUI selection	Navigate with key:up / key:down / key:enter.
Freeform text prompt	Send text + key:enter.
Stuck / needs interrupt	key:ctrl+c (or relevant control sequence like key:esc).

4) Lifecycle

oly attach <ID>      # Detach: Ctrl-], then d
oly update <ID> --title "better name"
oly update <ID> --title ""
oly update <ID> --tag prod --tag release
oly update <ID> --tag ""
oly stop <ID>
oly restart <ID>      # new ID and logs; source history is retained; --force kills a running source
oly rm <ID>           # delete a stopped session + its logs; --force also kills a running one
oly ls                # oly ls --json for agents

• oly update changes session metadata without restarting the session.
• --title "" clears the title. If --title is omitted, the existing title is kept.
• --tag "" clears all tags. If --tag is omitted, existing tags are kept.
• Repeating --tag replaces the full tag list with the provided tags.
• oly restart <ID> creates a new session from persisted command, arguments, cwd, title, tags, and notification settings. It retains the source record and logs; running sources require --force and are killed first.
• oly rm <ID> deletes a stopped session's DB row and on-disk logs. Running sessions are refused unless you pass --force (which kills the session first).

5) Notify

oly notify send <ID> --title "Done" --description "Summary." --body "Details."

• <ID> is optional — include it to link the notification to a specific session. It must be a running session; omit the ID if the session already ended.
• Toggle per-session notifications: oly notify enable <ID> / oly notify disable <ID>.
• Notifications go to the human (desktop / configured notification hook), never to another session. To message another session, use oly send with the report-back protocol below.

Help

oly --help            # or: oly <command> --help
oly skill             # print the bundled copy of this skill — bootstrap other agents with it

Recipes

Supervise an agent session and push it forward

User: "Run the fixer agent and keep it moving until the tests pass."

1. Start it and note the returned ID:

   oly start --title "fix tests" --cwd /repo --detach <agent-cmd>
   

2. Loop until done — wait, read, decide, act:

   oly logs <ID> --tail 40 --no-truncate --wait-for-prompt --timeout 5m
   

   Judge the tail: asking for approval? stuck on a menu? finished?

   oly send <ID> "yes" key:enter        # unblock a confirmation
   oly send <ID> key:ctrl+c             # interrupt a hang, then re-prompt
   

   Repeat with a timeout that matches the task's pace.
3. When the task completes, summarize the outcome for the user. Use oly stop <ID> if the process is still lingering, and optionally alert them:

   oly notify send <ID> --title "fix tests" --description "Done — tests pass."
   

Do NOT answer prompts blindly — when a decision is consequential (destructive action, credentials, ambiguous choice), report to the user instead of guessing.

Delegate to a worker agent session

Hand a task to another agent CLI and have it report back to you:

1. Start the worker and note the ID:

   oly start --title "worker" --cwd /repo --detach pi
   

2. Optional — switch its model interactively: send /model key:enter, type a filter, then key:enter. Pause ~2s between TUI steps and verify each with oly logs before sending the next.
3. In the task prompt, tell the worker to run oly skill itself to learn the CLI — do NOT paste the reference into the prompt. The prompt must include: the task, your own session ID, and the report-back protocol below.
4. Supervise with the loop from the previous recipe; oly stop <ID> when done.

Report-back protocol (busy-safe). Sending to another session is not guaranteed: a stopped session rejects input outright (exit 1), and a busy TUI may queue or swallow it. So the sender must check, send, confirm, and retry:

oly ls --json --status running          # 1. receiver must be running
oly send <TARGET> "worker <ID> DONE branch=... commit=... summary=..." key:enter   # 2. send
oly logs <TARGET> --tail 15             # 3. confirm your text landed in its output
sleep 10                                # 4. if missing: wait and resend, up to 3 tries

Make report text self-identifying (sender session ID, status, key results) — a busy receiver may only act on the message later.

Watch several sessions at once

oly ls --json --status running      # what's still alive?
oly logs <ID> --tail 40             # spot-check one session
oly notify enable <ID>              # let the human get pinged when it needs input

Recover a stuck or failed session

oly send <ID> key:ctrl+c            # interrupt a hang
oly logs <ID> --tail 120            # confirm the failure mode
oly restart <ID>                    # rerun same cmd/cwd, fresh logs (source history kept)
oly restart <ID> --force            # even if the source is still running