coding-agent

编码 Agent（以后台运行为先）

对于非交互式编码工作，请使用 bash 后台模式。对于交互式编码会话，请使用 tmux 技能（始终如此，极简单次提示除外）。

模式：工作目录 + 后台运行

# Create temp space for chats/scratch work
SCRATCH=$(mktemp -d)

# Start agent in target directory ("little box" - only sees relevant files)
bash workdir:$SCRATCH background:true command:"<agent command>"
# Or for project work:
bash workdir:~/project/folder background:true command:"<agent command>"
# Returns sessionId for tracking

# Monitor progress
process action:log sessionId:XXX

# Check if done  
process action:poll sessionId:XXX

# Send input (if agent asks a question)
process action:write sessionId:XXX data:"y"

# Kill if needed
process action:kill sessionId:XXX

工作目录为何重要： Agent 会在一个明确的目录中启动，不会跑去读无关文件（比如你的 soul.md 😅）。

---

Codex CLI

模型： gpt-5.2-codex 是默认模型（在 ~/.codex/config.toml 中设置）

构建/创建（使用 --full-auto 或 --yolo）

# --full-auto: sandboxed but auto-approves in workspace
bash workdir:~/project background:true command:"codex exec --full-auto \"Build a snake game with dark theme\""

# --yolo: NO sandbox, NO approvals (fastest, most dangerous)
bash workdir:~/project background:true command:"codex --yolo \"Build a snake game with dark theme\""

# Note: --yolo is a shortcut for --dangerously-bypass-approvals-and-sandbox

审查 PR（原生模式，不加标志）

⚠️ 重要：绝不要在 Clawdbot 自己的项目文件夹中审查 PR！

• 使用提交 PR 的项目（如果它不是 ~/Projects/clawdbot）
• 或先克隆到临时文件夹

# Option 1: Review in the actual project (if NOT clawdbot)
bash workdir:~/Projects/some-other-repo background:true command:"codex review --base main"

# Option 2: Clone to temp folder for safe review (REQUIRED for clawdbot PRs!)
REVIEW_DIR=$(mktemp -d)
git clone https://github.com/clawdbot/clawdbot.git $REVIEW_DIR
cd $REVIEW_DIR && gh pr checkout 130
bash workdir:$REVIEW_DIR background:true command:"codex review --base origin/main"
# Clean up after: rm -rf $REVIEW_DIR

# Option 3: Use git worktree (keeps main intact)
git worktree add /tmp/pr-130-review pr-130-branch
bash workdir:/tmp/pr-130-review background:true command:"codex review --base main"

为什么？ 在运行中的 Clawdbot 仓库中切换分支可能会破坏正在运行的实例！

批量审查 PR（并行作战！）

# Fetch all PR refs first
git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'

# Deploy the army - one Codex per PR!
bash workdir:~/project background:true command:"codex exec \"Review PR #86. git diff origin/main...origin/pr/86\""
bash workdir:~/project background:true command:"codex exec \"Review PR #87. git diff origin/main...origin/pr/87\""
bash workdir:~/project background:true command:"codex exec \"Review PR #95. git diff origin/main...origin/pr/95\""
# ... repeat for all PRs

# Monitor all
process action:list

# Get results and post to GitHub
process action:log sessionId:XXX
gh pr comment <PR#> --body "<review content>"

PR 审查技巧

• 先获取引用： git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'
• 使用 git diff： 告诉 Codex 使用 git diff origin/main...origin/pr/XX
• 不要切换分支： 多个并行审查意味着不要让它们更改分支
• 发布结果： 使用 gh pr comment 在 GitHub 上发布审查结果

---

Claude Code

bash workdir:~/project background:true command:"claude \"Your task\""

---

OpenCode

bash workdir:~/project background:true command:"opencode run \"Your task\""

---

Pi Coding Agent

# Install: npm install -g @mariozechner/pi-coding-agent
bash workdir:~/project background:true command:"pi \"Your task\""

---

Pi 常用标志

• --print / -p：非交互式；运行提示词后退出。
• --provider <name>：选择提供方（默认：google）。
• --model <id>：选择模型（默认：gemini-2.5-flash）。
• --api-key <key>：覆盖 API 密钥（默认使用环境变量）。

示例：

# Set provider + model, non-interactive
bash workdir:~/project background:true command:"pi --provider openai --model gpt-4o-mini -p \"Summarize src/\""

---

tmux（交互式会话）

对于交互式编码会话，请使用 tmux 技能（始终如此，极简单次提示除外）。对于非交互式运行，优先使用 bash 后台模式。

---

使用 git worktrees + tmux 并行修复问题

若要并行修复多个问题，请使用 git worktrees（隔离分支）+ tmux 会话：

# 1. Clone repo to temp location
cd /tmp && git clone [email protected]:user/repo.git repo-worktrees
cd repo-worktrees

# 2. Create worktrees for each issue (isolated branches!)
git worktree add -b fix/issue-78 /tmp/issue-78 main
git worktree add -b fix/issue-99 /tmp/issue-99 main

# 3. Set up tmux sessions
SOCKET="${TMPDIR:-/tmp}/codex-fixes.sock"
tmux -S "$SOCKET" new-session -d -s fix-78
tmux -S "$SOCKET" new-session -d -s fix-99

# 4. Launch Codex in each (after pnpm install!)
tmux -S "$SOCKET" send-keys -t fix-78 "cd /tmp/issue-78 && pnpm install && codex --yolo 'Fix issue #78: <description>. Commit and push.'" Enter
tmux -S "$SOCKET" send-keys -t fix-99 "cd /tmp/issue-99 && pnpm install && codex --yolo 'Fix issue #99: <description>. Commit and push.'" Enter

# 5. Monitor progress
tmux -S "$SOCKET" capture-pane -p -t fix-78 -S -30
tmux -S "$SOCKET" capture-pane -p -t fix-99 -S -30

# 6. Check if done (prompt returned)
tmux -S "$SOCKET" capture-pane -p -t fix-78 -S -3 | grep -q "❯" && echo "Done!"

# 7. Create PRs after fixes
cd /tmp/issue-78 && git push -u origin fix/issue-78
gh pr create --repo user/repo --head fix/issue-78 --title "fix: ..." --body "..."

# 8. Cleanup
tmux -S "$SOCKET" kill-server
git worktree remove /tmp/issue-78
git worktree remove /tmp/issue-99

为什么使用 worktrees？ 每个 Codex 都在隔离分支中工作，不会发生冲突。可以并行运行 5 个以上的修复任务！

为什么选择 tmux 而非 bash 后台？ Codex 是交互式的，需要 TTY 才能正常输出。tmux 提供持久会话，并可完整捕获历史记录。

---

⚠️ 规则

1. 遵守工具选择——如果用户要求使用 Codex，就使用 Codex。绝不要主动提出自己来构建！
2. 保持耐心——不要因为会话“很慢”就终止它
3. 通过 process:log 监控——检查进度，但不要干扰
4. 构建时使用 --full-auto——自动批准更改
5. 审查时使用原生模式——无需特殊标志
6. 可以并行运行——批量处理时可同时运行多个 Codex 进程
7. 绝不要在 ~/clawd/ 中启动 Codex——它会读取你的灵魂文档，还会对组织架构产生奇怪的想法！请使用目标项目目录，或用 /tmp 开启空白会话
8. 绝不要在 ~/Projects/clawdbot/ 中切换分支——那是正在运行的 Clawdbot 实例！审查 PR 时请克隆到 /tmp，或使用 git worktree

---

PR 模板（The Razor Standard）

向外部仓库提交 PR 时，请使用此格式，以确保质量并方便维护者处理：

## Original Prompt
[Exact request/problem statement]

## What this does
[High-level description]

**Features:**
- [Key feature 1]
- [Key feature 2]

**Example usage:**
```bash
# Example
command example
```

## Feature intent (maintainer-friendly)
[Why useful, how it fits, workflows it enables]

## Prompt history (timestamped)
- YYYY-MM-DD HH:MM UTC: [Step 1]
- YYYY-MM-DD HH:MM UTC: [Step 2]

## How I tested
**Manual verification:**
1. [Test step] - Output: `[result]`
2. [Test step] - Result: [result]

**Files tested:**
- [Detail]
- [Edge cases]

## Session logs (implementation)
- [What was researched]
- [What was discovered]
- [Time spent]

## Implementation details
**New files:**
- `path/file.ts` - [description]

**Modified files:**
- `path/file.ts` - [change]

**Technical notes:**
- [Detail 1]
- [Detail 2]

---
*Submitted by Razor 🥷 - Mariano's AI agent*

关键原则：

1. 由人撰写的描述（不要有 AI 垃圾内容）
2. 说明功能对维护者的意义
3. 带时间戳的提示词历史
4. 使用 Codex/Agent 时附上会话日志

示例： https://github.com/steipete/bird/pull/22