Paseo CLI Commands Use these CLI commands to manage agents:
List agents (directory-scoped by default)
paseo ls
Only shows agents for current directory
paseo ls -g
All agents across all projects (global)
paseo ls --json
JSON output for parsing
Create and run an agent (blocks until completion by default, no timeout)
paseo run
--mode
bypass
"
Wait timeout - limit how long run blocks (default: no limit)
paseo run --wait-timeout 30m
"
Wait up to 30 minutes
paseo run --wait-timeout 1h
"
Wait up to 1 hour
paseo run --wait-timeout
3600
"
Plain number = seconds
Detached mode - runs in background, returns agent ID immediately
paseo run
--detach
"
Short form
Structured output - agent returns only matching JSON
paseo run --output-schema
'{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"]}'
"
Or from a file
NOTE: --output-schema blocks until completion (cannot be used with --detach)
NOTE: --wait-timeout applies to --output-schema runs too
Worktrees - isolated git worktree for parallel feature development
paseo run
--worktree
feature-x
"
Check agent logs/output
paseo logs < agent-id
paseo logs < agent-id
-f
Follow (stream)
paseo logs < agent-id
--tail 10
Last 10 entries
paseo logs < agent-id
--filter tools
Only tool calls
Wait for agent to complete or need permission
paseo wait < agent-id
paseo wait < agent-id
--timeout 60
60 second timeout
Send follow-up prompt to running agent
paseo send < agent-id
"
" paseo send < agent-id --image screenshot.png "
"
With image
paseo send < agent-id
--no-wait "
"
Queue without waiting
Inspect agent details
paseo inspect < agent-id
Interrupt an agent's current run
paseo stop < agent-id
Hard-delete an agent (interrupts first if needed)
paseo delete < agent-id
Attach to agent output stream (Ctrl+C to detach without stopping)
paseo attach < agent-id
Permissions management
paseo permit ls
List pending permission requests
paseo permit allow < agent-id
Allow all pending for agent
paseo permit deny < agent-id
--all
Deny all pending
Agent mode switching
paseo agent mode < agent-id
--list
Show available modes
paseo agent mode < agent-id
bypass
Set bypass mode
Output formats
paseo ls --json
JSON output
paseo ls -q
IDs only (quiet mode, useful for scripting)
- Available Models
- Claude (default provider)
- - use aliases, CLI resolves to latest version:
- --model haiku
- - Fast/cheap, ONLY for tests (not for real work)
- --model sonnet
- - Default, good for most tasks
- --model opus
- - For harder reasoning, complex debugging
- Codex
- (
- --provider codex
- ):
- --model gpt-5.4
- - Latest frontier agentic coding model (default, preferred for all engineering tasks)
- --model gpt-5.1-codex-mini
- - Cheaper, faster, but less capable
- Permissions
- Always launch agents fully permissioned. Use
- --mode bypass
- for Claude and
- --mode full-access
- for Codex. Control behavior through
- strict prompting
- , not permission modes.
- Agent Use Cases
- You can run agents to:
- Implement a task
- - Spawn an agent to write code and implement features
- Have a design discussion
- - Use Codex for architecture discussions
- Test some feature
- - Run tests and verify functionality
- Do investigation
- - Research and explore the codebase
- Review changes
- - Use Codex for thorough code reviews
- Clarifying Ambiguous Requests
- CRITICAL:
- When user requests are ambiguous or unclear:
- Research first
- - Spawn an investigation agent to understand the current state
- Ask clarifying questions
- - After research, ask the user specific questions about what they want
- Present options
- - Offer multiple approaches with trade-offs
- Get explicit confirmation
- - Never assume what the user wants
- Investigation vs Implementation
- CRITICAL:
- When asked to investigate:
- Investigation agents MUST NOT fix issues
- - They should only identify, document, and report problems
- Always ask for confirmation
- - After investigation, present findings and ask: "Should I proceed with implementing fixes?"
- Only implement if explicitly requested
- - Don't auto-fix without user approval
- Rigorous Agent Interrogation
- CRITICAL:
- Agents start with ZERO context about your task. You must always provide complete context in your initial prompt.
- When working with agents, you must dig deep and challenge them rigorously:
- For Implementation Agents
- Don't accept surface-level completion
-
- Check their logs with
- paseo logs
- Trace the implementation
-
- Ask them to walk through the code flow step by step
- Uncover gaps
-
- Send follow-up prompts with
- paseo send
" " - "Show me exactly where you handle error case X"
- "What happens if the user does Y before Z?"
- "Walk me through the data flow from input to output"
- For Investigation/Debugging Agents
- Don't stop at the first answer
-
- Keep digging deeper
- Explore different angles
-
- "What are 3 other possible causes?"
- Request proof
-
- "Show me the specific code that proves this hypothesis"
- Challenge assumptions
-
- "How do you know that's the root cause?"
- For Review Agents (prefer Codex)
- Security review
-
- "What are the security implications? Any OWASP vulnerabilities?"
- Edge cases
-
- "What edge cases are not handled?"
- Performance
-
- "Where are the performance bottlenecks?"
- Maintainability
- "How maintainable is this code?"
Waiting for Agents
CRITICAL:
Both
paseo run
and
paseo wait
block until the agent completes. Trust them.
paseo run
waits
forever
by default (no timeout). Use
--wait-timeout
to set a limit.
paseo wait
also waits forever by default. Use
--timeout
to set a limit.
Agent tasks can legitimately take 10, 20, or even 30+ minutes. This is normal.
When a wait times out,
just re-run
paseo wait
— don't panic, don't start checking logs, don't inspect status. The agent is still working. Do NOT poll with paseo ls , paseo inspect , or paseo logs in a loop to "check on" the agent. This wastes your context window and accomplishes nothing. Only check logs/inspect if you have a specific reason to believe something is wrong (e.g., you sent a prompt and got an unexpected error back). Never launch a duplicate agent because a wait timed out. The original is still running.
Correct: just keep waiting
paseo wait < id
timed out? just run it again:
paseo wait < id
still going? keep waiting:
paseo wait < id
--timeout 300
or use a longer timeout
For long-running tasks, set a generous timeout on run itself:
paseo run --wait-timeout 1h --output-schema
'...'
"
Wrong: anxious polling loop
paseo wait < id
timed out
paseo ls
is it still running??
paseo inspect < id
what's it doing??
paseo logs < id
let me check the logs!!
^ Don't do this. Trust the wait.
Agent Management Principles
Keep agents focused
- Each agent should have a clear, specific responsibility
You can talk to them
- Use
paseo send
/dev/null verdict = $( paseo run --provider claude --output-schema '{"type":"object","properties":{"criteria_met":{"type":"boolean"}},"required":["criteria_met"],"additionalProperties":false}' "ensure tests all pass" ) if echo " $verdict " | jq -e '.criteria_met == true'
/dev/null ; then echo "criteria met" break fi done Detach + wait pattern for parallel work:
Kick off parallel agents
api_id
$( paseo run -d --name "API impl" "implement the API" -q ) ui_id = $( paseo run -d --name "UI impl" "implement the UI" -q )
Wait for both to finish
paseo wait " $api_id " paseo wait " $ui_id "
Review the combined result
paseo run --provider codex "review the API and UI implementations. DO NOT edit."