peekaboo agent

agent hands a natural-language task to PeekabooAgentService, which in turn orchestrates the full toolset (see, click, type, menu, etc.). The command handles session caching, terminal capability detection, progress spinners, and audio capture so you can run the exact same agent loop the macOS app uses.

#Key options

#Implementation notes

• The command resolves output “modes” (minimal, compact, enhanced, quiet, verbose) using terminal detection heuristics; --simple and --no-color force minimal mode, while --quiet suppresses progress output entirely.
• Session metadata lives inside agentService (PeekabooCore). --resume grabs the most recent session, --list-sessions prints the cached list, and --no-cache disables reuse so each run starts clean.
• All agent executions run under CommandRuntime.makeDefault(), so environment variables, credentials, and logging levels match the top-level CLI state.
• When --dry-run is set the agent still reasons about the task, but tool invocations are skipped; this is useful for understanding plans without touching the UI.
• Audio flags wire into Tachikoma’s audio stack: --audio opens the microphone, --audio-file loads a WAV/CAF file, and --realtime enables low-latency streaming (OpenAI-only).
• Generation uses agent.temperature and agent.maxTokens from the shared config written by the macOS Settings UI.

Token requests are capped to model capability; unsupported temperature controls are omitted automatically.

• A run saves its session and fails when its final permitted turn still requests tools and therefore needs another

model turn to interpret their results. This avoids reporting an empty success when the step budget expires with pending work; resume the reported session to continue.

• Native ollama/<model> runs replay each assistant tool call and named tool result on the next model turn. Ollama

support is model-dependent, and native text arrives incrementally with a model-dependent chunk cadence. See the Ollama guide.

#Chat mode

Peekaboo now ships a dependency-free interactive chat loop described in detail in docs/agent-chat.md. Key behaviors:

• Running peekaboo agent without a task automatically enters chat mode when stdout is a TTY. A taskless --resume / --resume-session also enters chat so piped prompts can continue the saved session; other non-interactive invocations print the chat help menu instead of hanging.
• --chat forces the loop even when piped or redirected, making it easy for other agents to seed prompts programmatically.
• /help is available inside the loop at any time and is printed the moment the loop starts. /help is also mentioned in the initial “Type /help…” banner so operators know what to do.
• Pressing Esc during an active turn cancels the run immediately and brings you back to the prompt; Ctrl+C still works as a fallback.
• Chat sessions reuse context via the same agent session cache. Supplying --resume / --resume-session <id> before --chat hooks the loop into an existing conversation.
• Ctrl+C cancels the current turn; pressing it again (while idle) exits the loop. Ctrl+D exits when idle.

For automation flows that cannot attach to a TTY, pass both --chat and standard input (e.g., echoing prompts line-by-line). Automatic taskless session resumes also consume standard input and exit nonzero when a resumed turn fails; explicit --chat keeps the loop alive. Without --chat or a taskless resume, a non-interactive invocation simply prints the chat help instructions and exits so jobs don’t hang.

#Examples

# Let the agent sign into Slack using GPT-5.5 with verbose tracing
peekaboo agent "Check Slack mentions" --model gpt-5.5 --verbose

# Use GPT-5.6 Sol (the gpt-5.6 shortcut selects Sol)
peekaboo agent "Check the current window" --model gpt-5.6

# Use Claude Sonnet 5
peekaboo agent "Check the current window" --model claude-sonnet-5

# Keep the agent loop local through Ollama
peekaboo agent "Check the current window" --model ollama/llama3.3

# Use an OpenRouter-hosted model
peekaboo agent "Check the current window" --model openrouter/xiaomi/mimo-v2.5-pro

# Dry-run the same task without executing any tools
peekaboo agent "Install the nightly build" --dry-run

# Resume the last session with a one-shot continuation and quiet output
peekaboo agent --resume "Continue the task" --quiet

#Troubleshooting

• Verify Screen Recording + Accessibility permissions (peekaboo permissions status).
• Confirm your target (app/window/selector) with peekaboo list/peekaboo see before rerunning.
• Re-run with --json or --verbose to surface detailed errors.