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

bash
1peky session list

2. Focus the session you intend to operate on

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

3. Send to a specific pane (recommended)

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

4. Send to the whole session or project

bash
1peky pane send --scope session --text "hello session" --yes
2peky pane send --scope project --text "hello project" --yes
3peky 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:

bash
1# Run a shell command (executes immediately)
2peky pane run --pane-id "<pane-id>" --command "ls -la" --yes
3
4# Run on the currently focused pane (no lookup needed)
5peky pane run --pane-id @focused --command "ls -la" --yes
6
7# Type into a prompt without submitting yet
8peky pane send --pane-id "<pane-id>" --text "draft message" --yes
9peky pane key --pane-id "<pane-id>" --key enter --yes
10
11# Target only Codex panes in a broadcast
12peky pane run --scope all --command "hello" --tool codex --yes
13
14# Send raw bytes (no tool formatting)
15peky 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.

bash
1peky pane add --yes
2peky pane add --session "<session>" --index 3 --orientation horizontal --yes
3peky 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:

bash
1peky --fresh-config ...
2peky --temporary-run ...

Daemon Management

bash
1peky daemon            # foreground
2peky daemon stop --yes
3peky daemon restart --yes
4peky daemon --pprof    # requires profiler build

JSON + Automation

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

bash
1peky pane list --json
2peky events watch --json
3peky pane tail --json --lines 50

Stress + E2E (local + self-hosted)

Use the built-in stress battery for regression protection:

bash
1scripts/cli-stress.sh

Enable tool loops during stress (Codex/Claude):

bash
1RUN_TOOLS=1 scripts/cli-stress.sh

Tip: when using a local binary alias, always call $PP, not PP:

bash
1PP=./bin/peky
2$PP version

Logs (macOS default)

If you need daemon logs:

bash
1tail -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