Back to Details

paseo

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Paseo CLI Commands

Paseo CLI 命令

Use these CLI commands to manage agents:
bash
undefined
使用以下CLI命令管理Agent：
bash
undefined

List agents (directory-scoped by default)

列出Agent（默认按目录范围）

paseo ls # Only shows agents for current directory paseo ls -g # All agents across all projects (global) paseo ls --json # JSON output for parsing
paseo ls # 仅显示当前目录下的Agent paseo ls -g # 所有项目中的全部Agent（全局） paseo ls --json # 输出JSON格式用于解析

Create and run an agent (blocks until completion by default, no timeout)

创建并运行Agent（默认阻塞直到完成，无超时）

paseo run --mode bypass "<prompt>" paseo run --mode bypass --name "Task Name" "<prompt>" paseo run --mode bypass --model opus "<prompt>" paseo run --mode full-access --provider codex "<prompt>"
paseo run --mode bypass "<prompt>" paseo run --mode bypass --name "Task Name" "<prompt>" paseo run --mode bypass --model opus "<prompt>" paseo run --mode full-access --provider codex "<prompt>"

Wait timeout - limit how long run blocks (default: no limit)

等待超时 - 限制运行阻塞的时长（默认：无限制）

paseo run --wait-timeout 30m "<prompt>" # Wait up to 30 minutes paseo run --wait-timeout 1h "<prompt>" # Wait up to 1 hour paseo run --wait-timeout 3600 "<prompt>" # Plain number = seconds
paseo run --wait-timeout 30m "<prompt>" # 最多等待30分钟 paseo run --wait-timeout 1h "<prompt>" # 最多等待1小时 paseo run --wait-timeout 3600 "<prompt>" # 纯数字表示秒数

Detached mode - runs in background, returns agent ID immediately

分离模式 - 在后台运行，立即返回Agent ID

paseo run --detach "<prompt>" paseo run -d "<prompt>" # Short form
paseo run --detach "<prompt>" paseo run -d "<prompt>" # 简写形式

Structured output - agent returns only matching JSON

结构化输出 - Agent仅返回匹配的JSON

paseo run --output-schema '{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"]}' "<prompt>" paseo run --output-schema schema.json "<prompt>" # Or from a file
paseo run --output-schema '{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"]}' "<prompt>" paseo run --output-schema schema.json "<prompt>" # 或从文件读取

NOTE: --output-schema blocks until completion (cannot be used with --detach)

注意：--output-schema会阻塞直到完成（不能与--detach一起使用）

NOTE: --wait-timeout applies to --output-schema runs too

注意：--wait-timeout同样适用于--output-schema的运行

Worktrees - isolated git worktree for parallel feature development

工作树 - 用于并行功能开发的独立Git工作树

paseo run --worktree feature-x "<prompt>"
paseo run --worktree feature-x "<prompt>"

Check agent logs/output

查看Agent日志/输出

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
paseo logs <agent-id> paseo logs <agent-id> -f # 实时跟踪（流式输出） paseo logs <agent-id> --tail 10 # 最后10条记录 paseo logs <agent-id> --filter tools # 仅显示工具调用

Wait for agent to complete or need permission

等待Agent完成或等待权限审批

paseo wait <agent-id> paseo wait <agent-id> --timeout 60 # 60 second timeout
paseo wait <agent-id> paseo wait <agent-id> --timeout 60 # 60秒超时

Send follow-up prompt to running agent

向运行中的Agent发送后续提示

paseo send <agent-id> "<prompt>" paseo send <agent-id> --image screenshot.png "<prompt>" # With image paseo send <agent-id> --no-wait "<prompt>" # Queue without waiting
paseo send <agent-id> "<prompt>" paseo send <agent-id> --image screenshot.png "<prompt>" # 附带图片 paseo send <agent-id> --no-wait "<prompt>" # 加入队列不等待

Inspect agent details

查看Agent详情

paseo inspect <agent-id>
paseo inspect <agent-id>

Interrupt an agent's current run

中断Agent当前运行

paseo stop <agent-id>
paseo stop <agent-id>

Hard-delete an agent (interrupts first if needed)

硬删除Agent（必要时先中断运行）

paseo delete <agent-id>
paseo delete <agent-id>

Attach to agent output stream (Ctrl+C to detach without stopping)

附加到Agent输出流（按Ctrl+C可分离但不停止Agent）

paseo attach <agent-id>
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
paseo permit ls # 列出待处理的权限请求 paseo permit allow <agent-id> # 批准该Agent的所有待处理请求 paseo permit deny <agent-id> --all # 拒绝该Agent的所有待处理请求

Agent mode switching

Agent模式切换

paseo agent mode <agent-id> --list # Show available modes paseo agent mode <agent-id> bypass # Set bypass mode
paseo agent mode <agent-id> --list # 显示可用模式 paseo agent mode <agent-id> bypass # 设置为bypass模式

Output formats

输出格式

paseo ls --json # JSON output paseo ls -q # IDs only (quiet mode, useful for scripting)
undefined
paseo ls --json # JSON格式输出 paseo ls -q # 仅显示ID（静默模式，适用于脚本）
undefined

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
Claude（默认提供商） - 使用别名，CLI会自动解析为最新版本：
  • --model haiku
    - 快速/低成本，仅用于测试（不适合实际工作）
  • --model sonnet
    - 默认选项，适合大多数任务
  • --model opus
    - 用于复杂推理、复杂调试场景
Codex（使用
--provider codex
）：
  • --model gpt-5.4
    - 最新前沿Agent化编码模型（默认，推荐用于所有工程任务）
  • --model gpt-5.1-codex-mini
    - 更便宜、更快，但能力较弱

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。对于Claude使用
--mode bypass
，对于Codex使用
--mode full-access
。通过严格的提示词而非权限模式来控制行为。

Agent Use Cases

Agent 使用场景

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
你可以运行Agent来：
  • 实现任务 - 启动Agent编写代码并实现功能
  • 进行设计讨论 - 使用Codex开展架构讨论
  • 测试功能 - 运行测试并验证功能
  • 开展调查 - 研究并探索代码库
  • 审核变更 - 使用Codex进行全面的代码审核

Clarifying Ambiguous Requests

明确模糊的请求

CRITICAL: When user requests are ambiguous or unclear:
  1. Research first - Spawn an investigation agent to understand the current state
  2. Ask clarifying questions - After research, ask the user specific questions about what they want
  3. Present options - Offer multiple approaches with trade-offs
  4. Get explicit confirmation - Never assume what the user wants
关键提示： 当用户的请求模糊或不明确时：
  1. 先调研 - 启动一个调查Agent来了解当前状态
  2. 提出明确问题 - 调研后，向用户询问关于需求的具体问题
  3. 提供选项 - 提供多种方案并说明各自的权衡
  4. 获取明确确认 - 永远不要假设用户的需求

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
关键提示： 当被要求进行调查时：
  • 调查Agent绝对不能修复问题 - 它们只能识别、记录并报告问题
  • 始终请求确认 - 调查完成后，呈现结果并询问："我是否应该继续进行修复？"
  • 仅在明确要求时才实现 - 未经用户批准，不要自动修复问题

Rigorous Agent Interrogation

严格的Agent质询

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:
关键提示： Agent初始时对你的任务没有任何上下文。你必须在初始提示词中提供完整的上下文。
与Agent协作时，你必须深入挖掘并严格质询它们：

For Implementation Agents

对于实现型Agent

  • Don't accept surface-level completion: Check their logs with 
    paseo logs <id>
  • Trace the implementation: Ask them to walk through the code flow step by step
  • Uncover gaps: Send follow-up prompts with 
    paseo send <id> "<question>"
    • "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"
  • 不接受表面化的完成结果：使用
    paseo logs <id>
    查看它们的日志
  • 跟踪实现过程：要求它们逐步讲解代码流程
  • 发现漏洞：使用
    paseo send <id> "<问题>"
    发送后续提示
    • "向我展示你处理错误场景X的具体位置"
    • "如果用户在Z之前执行Y会发生什么？"
    • "带我走一遍从输入到输出的数据流"

For Investigation/Debugging Agents

对于调查/调试型Agent

  • 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)

对于审核型Agent（推荐使用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?"
  • 安全审核："有哪些安全隐患？是否存在OWASP漏洞？"
  • 边缘场景："哪些边缘场景没有被处理？"
  • 性能："性能瓶颈在哪里？"
  • 可维护性："这段代码的可维护性如何？"

Waiting for Agents

等待Agent

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 <id>
     — 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.
bash
undefined
关键提示： 
paseo run
和
paseo wait
都会阻塞直到Agent完成。请信任它们。
  • paseo run
    默认会永久等待（无超时）。使用
    --wait-timeout
    设置限制。
  • paseo wait
    默认也会永久等待。使用
    --timeout
    设置限制。
  • Agent任务可能需要10、20甚至30多分钟，这是正常的。
  • 当等待超时后，只需重新运行
    paseo wait <id>
     — 不要惊慌，不要查看日志，不要检查状态。Agent仍在运行。
  • 不要循环使用
    paseo ls
    、
    paseo inspect
    或
    paseo logs
    来“检查”Agent。这会浪费你的上下文窗口，毫无意义。
  • 只有当你有特定理由认为出现问题时（例如，发送提示词后收到意外错误），才查看日志/详情。
  • 永远不要因为等待超时就启动重复的Agent。原Agent仍在运行。
bash
undefined

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
paseo wait <id> # 超时了？再运行一次： paseo wait <id> # 还在运行？继续等待： paseo wait <id> --timeout 300 # 或者设置更长的超时时间

For long-running tasks, set a generous timeout on run itself:

对于长时间运行的任务，在启动时就设置充足的超时时间：

paseo run --wait-timeout 1h --output-schema '...' "<prompt>"
paseo run --wait-timeout 1h --output-schema '...' "<prompt>"

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!!
paseo wait <id> # 超时 paseo ls # 它还在运行吗？ paseo inspect <id> # 它在做什么？ paseo logs <id> # 让我看看日志！

^ Don't do this. Trust the wait.

^ 不要这么做。请信任wait命令。

undefined
undefined

Agent Management Principles

Agent 管理原则

  • Keep agents focused - Each agent should have a clear, specific responsibility
  • You can talk to them - Use 
    paseo send <id> "<prompt>"
    to guide them
  • Monitor progress - Use 
    paseo logs <id> -f
    to stream output
  • Always provide context - Remember: agents start with zero knowledge of your task
  • Verify work rigorously - Don't trust, verify. Ask agents to prove their work
  • Commit frequently - Ensure each agent commits their changes before moving on
  • Plan for quality gates - Use Codex review agents as checkpoints
  • Run in parallel when possible - Use 
    -d
    flag to run multiple agents concurrently
  • 保持Agent专注 - 每个Agent都应该有明确、具体的职责
  • 你可以与它们交互 - 使用
    paseo send <id> "<prompt>"
    来引导它们
  • 监控进度 - 使用
    paseo logs <id> -f
    来流式查看输出
  • 始终提供上下文 - 记住：Agent初始时对你的任务一无所知
  • 严格验证工作成果 - 不要轻信，要验证。要求Agent证明它们的工作
  • 频繁提交 - 确保每个Agent在推进前提交它们的更改
  • 规划质量关卡 - 使用Codex审核Agent作为检查点
  • 尽可能并行运行 - 使用
    -d
    标志同时运行多个Agent

Common Patterns

常见模式

Committee

委员会模式

When stuck or planning something hard, use the 
/committee
skill. It launches two high-reasoning agents (Opus 4.6 + GPT 5.4) in parallel to do root cause analysis and produce a plan, then stays alive to review the implementation afterward.
当遇到难题或进行规划时，使用
/committee
技能。它会并行启动两个高推理能力的Agent（Opus 4.6 + GPT 5.4）进行根本原因分析并生成方案，之后会保持运行状态以审核后续的实现。

Composing Agents in Bash Scripts

在Bash脚本中组合使用Agent

paseo run
blocks by default and 
--output-schema
returns structured JSON, making it easy to compose agents in bash loops and pipelines.
Implement-and-verify loop:
bash
while true; do
  paseo run --provider codex "make the tests pass" >/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:
bash
undefined
paseo run
默认会阻塞，
--output-schema
会返回结构化JSON，因此可以轻松在Bash循环和管道中组合使用Agent。
实现与验证循环：
bash
while true; do
  paseo run --provider codex "make the tests pass" >/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
分离+等待的并行工作模式：
bash
undefined

Kick off parallel agents

启动并行Agent

api_id=$(paseo run -d --name "API impl" "implement the API" -q) ui_id=$(paseo run -d --name "UI impl" "implement the UI" -q)
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"
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."
undefined
paseo run --provider codex "review the API and UI implementations. DO NOT edit."
undefined