Skill v1.0.1

version: "1.0.1" name: oly description: "Use when starting a long-running or interactive CLI command with oly, especially when it may need later input, should be detachable, or should keep durable logs for supervision and resume. Also use to supervise sessions already running under oly: check status, read logs, send input to push them forward, stop or restart."

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

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:

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:

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

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

``bash oly logs <ID> --tail 40 --no-truncate --wait-for-prompt --timeout 5m ` Judge the tail: asking for approval? stuck on a menu? finished? `bash 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.

1. When the task completes, summarize the outcome for the user. Use oly stop <ID> if the process is still lingering, and optionally alert them:

``bash 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:

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

1. 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.
2. 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.
3. 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