peky

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.

peky

Overview

Use this skill to operate peky safely and predictably from the CLI, especially when automating or controlling panes via an AI agent.

Quick Rules (read first)

• Do not guess flags. Use peky <command> --help before running.
• Use --yes for side effects to avoid hanging prompts in non-interactive runs.
• Scopes are only session|project|all. Never pass project names to --scope.
• Project scope requires focus. If you see "focused project unavailable," run peky session focus --name <session> first.
• Prefer pane IDs for precision. Use pane list --json and pick the pane id.
• Shortcut: use --pane-id @focused to target the currently focused pane.
• pane add defaults to active pane. For deterministic automation, pass --pane-id or --session + --index.

Targeting: Session vs Project vs Pane ID

1. Find session names

peky session list

2. Focus the session you intend to operate on

peky session focus --name "<session>" --yes

3. Send to a specific pane (recommended)

peky pane list --session "<session>" --json
peky pane send --pane-id "<pane-id>" --text "hello world" --yes

4. Send to the whole session or project

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.

Run vs Send

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.
• Submitting after send: use pane key to press Enter when you decide to submit.
• Tool-aware input (default): send/run uses pane tool metadata (Codex/Claude/etc) to format input (bracketed paste + submit). Use --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

Adding Panes

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.

When the TUI is running

The CLI talks to the same daemon. You can run CLI commands from another terminal:

• If the TUI was launched with --temporary-run, the CLI must share that runtime/config env. Otherwise it won't connect.

Fresh / Temporary Runs (safe testing)

Use these when you don't want to touch existing state:

peky --fresh-config ...
peky --temporary-run ...

Daemon Management

peky daemon            # foreground
peky daemon stop --yes
peky daemon restart --yes
peky daemon --pprof    # requires profiler build

JSON + Automation

Use --json for machine output and --timeout to avoid hangs:

peky pane list --json
peky events watch --json
peky pane tail --json --lines 50

Stress + E2E (local + self-hosted)

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

Logs (macOS default)

If you need daemon logs:

tail -n 200 "$HOME/Library/Application Support/peky/daemon.log"

Troubleshooting Checklist (fast)

• "focused project unavailable" -> run session focus --name <session>
• Prompt hangs -> add --yes
• Wrong pane -> use pane list --json, target by id
• No daemon -> peky daemon or peky daemon start
• Can't connect -> ensure same runtime env or stop old daemon