// Use when operating peky from the CLI or TUI, especially for AI agents who need reliable, low-error procedures. Covers how to target sessions/panes correctly, use scopes, avoid confirmation prompts, and keep CLI/TUI/daemon in sync.
| name | peky |
| description | Use when operating peky from the CLI or TUI, especially for AI agents who need reliable, low-error procedures. Covers how to target sessions/panes correctly, use scopes, avoid confirmation prompts, and keep CLI/TUI/daemon in sync. |
Use this skill to operate peky safely and predictably from the CLI, especially when automating or controlling panes via an AI agent.
peky <command> --help before running.--yes for side effects to avoid hanging prompts in non-interactive runs.session|project|all. Never pass project names to --scope.peky session focus --name <session> first.pane list --json and pick the pane id.--pane-id @focused to target the currently focused pane.pane add defaults to active pane. For deterministic automation, pass --pane-id or --session + --index.peky session list
peky session focus --name "<session>" --yes
peky pane list --session "<session>" --json
peky pane send --pane-id "<pane-id>" --text "hello world" --yes
peky pane send --scope session --text "hello session" --yes
peky pane send --scope project --text "hello project" --yes
peky pane send --scope all --text "hello all" --yes
If --scope project fails, the focused session is missing or has no project path. Fix by focusing a session with a valid path.
Use this to avoid confusion in Codex/Claude sessions:
pane run = execute now. Sends the command and a newline. Best for shell commands or anything you want to run immediately.pane send = type only. Sends raw input without pressing Enter. Best when you need to compose input step‑by‑step or control submission.send: use pane key to press Enter when you decide to submit.--raw to bypass. Use --tool to target only panes running a specific tool.Examples:
# Run a shell command (executes immediately)
peky pane run --pane-id "<pane-id>" --command "ls -la" --yes
# Run on the currently focused pane (no lookup needed)
peky pane run --pane-id @focused --command "ls -la" --yes
# Type into a prompt without submitting yet
peky pane send --pane-id "<pane-id>" --text "draft message" --yes
peky pane key --pane-id "<pane-id>" --key enter --yes
# Target only Codex panes in a broadcast
peky pane run --scope all --command "hello" --tool codex --yes
# Send raw bytes (no tool formatting)
peky pane send --pane-id "<pane-id>" --text "raw bytes" --raw --yes
pane add is the first-class command. It defaults to the focused session + active pane.
peky pane add --yes
peky pane add --session "<session>" --index 3 --orientation horizontal --yes
peky pane add --pane-id "<pane-id>" --yes
Use pane split when you want an explicit split target and no defaults.
The CLI talks to the same daemon. You can run CLI commands from another terminal:
--temporary-run, the CLI must share that runtime/config env. Otherwise it won't connect.Use these when you don't want to touch existing state:
peky --fresh-config ...
peky --temporary-run ...
peky daemon # foreground
peky daemon stop --yes
peky daemon restart --yes
peky daemon --pprof # requires profiler build
Use --json for machine output and --timeout to avoid hangs:
peky pane list --json
peky events watch --json
peky pane tail --json --lines 50
Use the built-in stress battery for regression protection:
scripts/cli-stress.sh
Enable tool loops during stress (Codex/Claude):
RUN_TOOLS=1 scripts/cli-stress.sh
Tip: when using a local binary alias, always call $PP, not PP:
PP=./bin/peky
$PP version
If you need daemon logs:
tail -n 200 "$HOME/Library/Application Support/peky/daemon.log"
session focus --name <session>--yespane list --json, target by idpeky daemon or peky daemon start