From 23a818fa2d1b841a412a70b5ec1c2f5c521acfb1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=91=A8=E8=BE=89?= Date: Sun, 26 Apr 2026 04:50:50 +0800 Subject: [PATCH] docs: enforce background mode & direct completion in coding-agent (#53585) --- skills/coding-agent/SKILL.md | 307 ++++++++++++++++++++--------------- 1 file changed, 176 insertions(+), 131 deletions(-) diff --git a/skills/coding-agent/SKILL.md b/skills/coding-agent/SKILL.md index 9d9a776f1f5..7d256e0b6f2 100644 --- a/skills/coding-agent/SKILL.md +++ b/skills/coding-agent/SKILL.md @@ -1,6 +1,6 @@ --- name: coding-agent -description: "Delegate feature work, PR review, refactors, or iterative coding to background Codex, Claude Code, or Pi agents." +description: 'Delegate coding tasks to Codex, Claude Code, OpenCode, or Pi agents via immediate background processes. Use when: (1) building or creating features/apps, (2) reviewing PRs in a temp clone/worktree, (3) refactoring large codebases, (4) iterative coding that needs file exploration. NOT for: simple one-line fixes (just edit), reading code (use read tool), thread-bound ACP harness requests in chat (use sessions_spawn with runtime:"acp"), or any work in ~/clawd workspace (never spawn agents here). All coding-agent runs start with background:true immediately. Claude Code: use --print --permission-mode bypassPermissions (no PTY). Codex/Pi/OpenCode: pty:true required. Completion notification must use openclaw message send, not system event/heartbeat.' metadata: { "openclaw": @@ -28,45 +28,44 @@ metadata: } --- -# Coding Agent (bash-first) +# Coding Agent (always backgrounded) -Use **bash** (with optional background mode) for all coding agent work. Simple and effective. +Use **bash** with **background:true** for all coding-agent work. +Do not use a foreground one-shot path here. +Start the agent, get the `sessionId`, monitor with `process`, and require the worker to notify the user directly when it finishes. ## ⚠️ PTY Mode: Codex/Pi/OpenCode yes, Claude Code no -For **Codex, Pi, and OpenCode**, PTY is still required (interactive terminal apps): +For **Codex, Pi, and OpenCode**, PTY is required: ```bash -# ✅ Correct for Codex/Pi/OpenCode -bash pty:true command:"codex exec 'Your prompt'" +# Correct for Codex/Pi/OpenCode +bash pty:true background:true command:"codex exec 'Your prompt'" ``` For **Claude Code** (`claude` CLI), use `--print --permission-mode bypassPermissions` instead. -`--dangerously-skip-permissions` with PTY can exit after the confirmation dialog. -`--print` mode keeps full tool access and avoids interactive confirmation: +Do not use PTY for Claude Code here. ```bash -# ✅ Correct for Claude Code (no PTY needed) -cd /path/to/project && claude --permission-mode bypassPermissions --print 'Your task' +# Correct for Claude Code +bash background:true command:"claude --permission-mode bypassPermissions --print 'Your task'" -# For background execution: use background:true on the exec tool - -# ❌ Wrong for Claude Code +# Wrong for Claude Code (PTY, wrong flags, no background) bash pty:true command:"claude --dangerously-skip-permissions 'task'" ``` ### Bash Tool Parameters -| Parameter | Type | Description | -| ------------ | ------- | --------------------------------------------------------------------------- | -| `command` | string | The shell command to run | -| `pty` | boolean | **Use for coding agents!** Allocates a pseudo-terminal for interactive CLIs | -| `workdir` | string | Working directory (agent sees only this folder's context) | -| `background` | boolean | Run in background, returns sessionId for monitoring | -| `timeout` | number | Timeout in seconds (kills process on expiry) | -| `elevated` | boolean | Run on host instead of sandbox (if allowed) | +| Parameter | Type | Description | +| ------------ | ------- | ---------------------------------------------------------- | +| `command` | string | The shell command to run | +| `pty` | boolean | Use for Codex/Pi/OpenCode | +| `workdir` | string | Working directory | +| `background` | boolean | **Always true for this skill** | +| `timeout` | number | Timeout in seconds | +| `elevated` | boolean | Run on host instead of sandbox (if allowed) | -### Process Tool Actions (for background sessions) +### Process Tool Actions | Action | Description | | ----------- | ---------------------------------------------------- | @@ -81,48 +80,108 @@ bash pty:true command:"claude --dangerously-skip-permissions 'task'" --- -## Quick Start: One-Shot Tasks +## Mandatory Pattern -For quick prompts/chats, create a temp git repo and run: +Every coding-agent run follows this pattern: -```bash -# Quick chat (Codex needs a git repo!) -SCRATCH=$(mktemp -d) && cd $SCRATCH && git init && codex exec "Your prompt here" +1. Capture the notification route from the current conversation before spawning: + - `notifyChannel` + - `notifyTarget` + - `notifyAccount` (if applicable) + - `notifyReplyTo` (if replying to a specific message is desired) + - `notifyThreadId` (Telegram topic / Slack thread when applicable) +2. Start the coding CLI with `background:true` immediately. +3. Include the notification route in the worker prompt and require the worker to call `openclaw message send` on completion. +4. Monitor with `process action:log` / `poll`. +5. If the worker needs input or fails before notifying, handle that explicitly yourself. Do not rely on heartbeat. -# Or in a real project - with PTY! -bash pty:true workdir:~/Projects/myproject command:"codex exec 'Add error handling to the API calls'" -``` - -**Why git init?** Codex refuses to run outside a trusted git directory. Creating a temp repo solves this for scratch work. +If you do not have a trustworthy notification route, say so and do not claim that completion will notify the user automatically. --- -## The Pattern: workdir + background + pty +## Notification Route -For longer tasks, use background mode with PTY: +Do not rely on: + +- `openclaw system event` +- `tools.exec.notifyOnExit` +- heartbeat delivery +- `HEARTBEAT.md` + +Use a direct outbound completion message instead: ```bash -# Start agent in target directory (with PTY!) -bash pty:true workdir:~/project background:true command:"codex exec --full-auto 'Build a snake game'" -# 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" - -# Submit with Enter (like typing "yes" and pressing Enter) -process action:submit sessionId:XXX data:"yes" - -# Kill if needed -process action:kill sessionId:XXX +openclaw message send --channel --target '' --message '' ``` -**Why workdir matters:** Agent wakes up in a focused directory, doesn't wander off reading unrelated files (like your soul.md 😅). +Add optional routing flags only when they are real and applicable: + +- `--account ` +- `--reply-to ` +- `--thread-id ` + +`openclaw message send` is a direct outbound send. It does not depend on heartbeat being enabled. + +### Completion Prompt Snippet + +Append something like this to every worker prompt: + +```text +Notification route for completion: +- channel: +- target: +- account: +- reply_to: +- thread_id: + +When the task is completely finished, send exactly one completion message back to the user with openclaw message send using that route. +If the task fails fatally, send exactly one failure message back to the user with openclaw message send using that route. +Do not use openclaw system event. Do not rely on heartbeat. Do not skip the completion/failure message. +``` + +### Completion Command Template + +```bash +openclaw message send \ + --channel \ + --target '' \ + --message 'Done: ' +``` + +Optional additions: + +```bash + --account \ + --reply-to \ + --thread-id +``` + +--- + +## Quick Start + +For scratch Codex work, create a temp git repo first, then start the worker in the background with the completion route injected into the prompt: + +```bash +SCRATCH=$(mktemp -d) +cd "$SCRATCH" && git init + +bash pty:true workdir:$SCRATCH background:true command:"codex exec 'Your prompt here. + +Notification route for completion: +- channel: +- target: +- account: +- reply_to: +- thread_id: + +When the task is completely finished, send exactly one completion message back to the user with openclaw message send using that route. +If the task fails fatally, send exactly one failure message back to the user with openclaw message send using that route. +Do not use openclaw system event. Do not rely on heartbeat. Do not skip the completion/failure message.'" +``` + +Codex refuses to run outside a trusted git directory. +Reuse this same notify-route injection block in every example below; only the task-specific prompt body should change. --- @@ -134,53 +193,50 @@ process action:kill sessionId:XXX | Flag | Effect | | --------------- | -------------------------------------------------- | -| `exec "prompt"` | One-shot execution, exits when done | +| `exec "prompt"` | One-shot execution inside the worker CLI | | `--full-auto` | Sandboxed but auto-approves in workspace | -| `--yolo` | NO sandbox, NO approvals (fastest, most dangerous) | +| `--yolo` | No sandbox, no approvals | ### Building/Creating ```bash -# Quick one-shot (auto-approves) - remember PTY! -bash pty:true workdir:~/project command:"codex exec --full-auto 'Build a dark mode toggle'" +# Always background immediately +bash pty:true workdir:~/project background:true command:"codex exec --full-auto 'Build a dark mode toggle'" -# Background for longer work +# More autonomy bash pty:true workdir:~/project background:true command:"codex --yolo 'Refactor the auth module'" ``` ### Reviewing PRs -**⚠️ CRITICAL: Never review PRs in OpenClaw's own project folder!** -Clone to temp folder or use git worktree. +**Never review PRs in OpenClaw's own project folder.** +Clone to a temp folder or use a worktree. ```bash -# Clone to temp for safe review REVIEW_DIR=$(mktemp -d) git clone https://github.com/user/repo.git $REVIEW_DIR cd $REVIEW_DIR && gh pr checkout 130 -bash pty:true workdir:$REVIEW_DIR command:"codex review --base origin/main" -# Clean up after: trash $REVIEW_DIR -# Or use git worktree (keeps main intact) -git worktree add /tmp/pr-130-review pr-130-branch -bash pty:true workdir:/tmp/pr-130-review command:"codex review --base main" +bash pty:true workdir:$REVIEW_DIR background:true command:"codex review --base origin/main" ``` -### Batch PR Reviews (parallel army!) +Or: + +```bash +git worktree add /tmp/pr-130-review pr-130-branch +bash pty:true workdir:/tmp/pr-130-review background:true command:"codex review --base main" +``` + +### Batch PR Reviews ```bash -# Fetch all PR refs first git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*' -# Deploy the army - one Codex per PR (all with PTY!) bash pty:true workdir:~/project background:true command:"codex exec 'Review PR #86. git diff origin/main...origin/pr/86'" bash pty:true workdir:~/project background:true command:"codex exec 'Review PR #87. git diff origin/main...origin/pr/87'" -# Monitor all process action:list - -# Post results to GitHub -gh pr comment --body "" +process action:log sessionId:XXX ``` --- @@ -188,10 +244,6 @@ gh pr comment --body "" ## Claude Code ```bash -# Foreground -bash workdir:~/project command:"claude --permission-mode bypassPermissions --print 'Your task'" - -# Background bash workdir:~/project background:true command:"claude --permission-mode bypassPermissions --print 'Your task'" ``` @@ -200,7 +252,7 @@ bash workdir:~/project background:true command:"claude --permission-mode bypassP ## OpenCode ```bash -bash pty:true workdir:~/project command:"opencode run 'Your task'" +bash pty:true workdir:~/project background:true command:"opencode run 'Your task'" ``` --- @@ -209,43 +261,28 @@ bash pty:true workdir:~/project command:"opencode run 'Your task'" ```bash # Install: npm install -g @mariozechner/pi-coding-agent -bash pty:true workdir:~/project command:"pi 'Your task'" +bash pty:true workdir:~/project background:true command:"pi 'Your task'" -# Non-interactive mode (PTY still recommended) -bash pty:true command:"pi -p 'Summarize src/'" +# Non-interactive mode +bash pty:true workdir:~/project background:true command:"pi -p 'Summarize src/'" # Different provider/model -bash pty:true command:"pi --provider openai --model gpt-4o-mini -p 'Your task'" +bash pty:true workdir:~/project background:true command:"pi --provider openai --model gpt-4o-mini -p 'Your task'" ``` -**Note:** Pi now has Anthropic prompt caching enabled (PR #584, merged Jan 2026)! - --- ## Parallel Issue Fixing with git worktrees -For fixing multiple issues in parallel, use git worktrees: - ```bash -# 1. Create worktrees for each issue git worktree add -b fix/issue-78 /tmp/issue-78 main git worktree add -b fix/issue-99 /tmp/issue-99 main -# 2. Launch Codex in each (background + PTY!) -bash pty:true workdir:/tmp/issue-78 background:true command:"pnpm install && codex --yolo 'Fix issue #78: . Commit and push.'" -bash pty:true workdir:/tmp/issue-99 background:true command:"pnpm install && codex --yolo 'Fix issue #99 from the approved ticket summary. Implement only the in-scope edits and commit after review.'" +bash pty:true workdir:/tmp/issue-78 background:true command:"pnpm install && codex --yolo 'Fix issue #78: . Commit and push after review. Send the completion message with openclaw message send using the provided notify route.'" +bash pty:true workdir:/tmp/issue-99 background:true command:"pnpm install && codex --yolo 'Fix issue #99 from the approved ticket summary. Implement only the in-scope edits. Send the completion message with openclaw message send using the provided notify route.'" -# 3. Monitor progress process action:list process action:log sessionId:XXX - -# 4. 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 "..." - -# 5. Cleanup -git worktree remove /tmp/issue-78 -git worktree remove /tmp/issue-99 ``` --- @@ -265,52 +302,60 @@ git worktree remove /tmp/issue-99 7. **Parallel is OK** - run many Codex processes at once for batch work 8. **NEVER start Codex inside your OpenClaw state directory** (`$OPENCLAW_STATE_DIR`, default `~/.openclaw`) - it'll read your soul docs and get weird ideas about the org chart! 9. **NEVER checkout branches in ~/Projects/openclaw/** - that's the LIVE OpenClaw instance! +10. **Always inject the Completion Prompt Snippet** into the worker prompt before spawning. The simplified examples below omit it for brevity — never spawn a worker without it. --- ## Progress Updates (Critical) -When you spawn coding agents in the background, keep the user in the loop. +When you spawn a coding agent in the background, keep the user in the loop. -- Send 1 short message when you start (what's running + where). -- Then only update again when something changes: - - a milestone completes (build finished, tests passed) - - the agent asks a question / needs input +- Send 1 short message when you start: what is running and where. +- Update only when something changes: + - a milestone completes + - the worker asks a question - you hit an error or need user action - - the agent finishes (include what changed + where) + - the worker finishes - If you kill a session, immediately say you killed it and why. +- If you are expecting the worker to self-notify with `openclaw message send`, say that clearly in your start update. -This prevents the user from seeing only "Agent failed before reply" and having no idea what happened. +This prevents the user from seeing only a missing reply and having no idea what happened. --- -## Auto-Notify on Completion +## Rules -For long-running background tasks, append a wake trigger to your prompt so OpenClaw gets notified immediately when the agent finishes (instead of waiting for the next heartbeat): - -``` -... your task here. - -When completely finished, run this command to notify me: -openclaw system event --text "Done: [brief summary of what was built]" --mode now -``` - -**Example:** - -```bash -bash pty:true workdir:~/project background:true command:"codex --yolo exec 'Build a REST API for todos. - -When completely finished, run: openclaw system event --text \"Done: Built todos REST API with CRUD endpoints\" --mode now'" -``` - -This triggers an immediate wake event — Skippy gets pinged in seconds, not 10 minutes. +1. **Always background immediately.** + - Use `background:true` for every coding-agent launch. + - Do not use the foreground one-shot path in this skill. +2. **Use the right execution mode per agent.** + - Codex/Pi/OpenCode: `pty:true` + - Claude Code: `--print --permission-mode bypassPermissions` +3. **Respect tool choice.** + - If the user asked for Codex, use Codex. + - Orchestrator mode: do not hand-code the patch yourself instead of using the requested coding agent. +4. **Capture notify routing before spawn.** + - Completion messaging must have a real route. +5. **Use direct completion messaging.** + - Require `openclaw message send`. + - Do not rely on `openclaw system event` or heartbeat. +6. **Do not silently take over.** + - If a worker fails or hangs, respawn it or ask for direction. Do not quietly switch to hand-editing. +7. **Monitor with `process`.** + - `process action:log` is the default low-friction check. +8. **Be patient.** + - Do not kill sessions just because they are slow. +9. **Parallel is OK.** + - Many background Codex sessions can run at once. +10. **Never start Codex in `~/.openclaw/`.** +11. **Never checkout branches in `~/Projects/openclaw/`.** --- -## Learnings (Jan 2026) +## Learnings -- **PTY is essential:** Coding agents are interactive terminal apps. Without `pty:true`, output breaks or agent hangs. -- **Git repo required:** Codex won't run outside a git directory. Use `mktemp -d && git init` for scratch work. -- **exec is your friend:** `codex exec "prompt"` runs and exits cleanly - perfect for one-shots. -- **submit vs write:** Use `submit` to send input + Enter, `write` for raw data without newline. -- **Sass works:** Codex responds well to playful prompts. Asked it to write a haiku about being second fiddle to a space lobster, got: _"Second chair, I code / Space lobster sets the tempo / Keys glow, I follow"_ 🦞 +- **PTY is essential** for Codex/Pi/OpenCode. +- **Git repo required**: Codex needs a trusted git directory. +- **Use `exec` under background orchestration**: short and long tasks follow the same path now. +- **`submit` vs `write`**: use `submit` to send input plus Enter. +- **Direct message send beats heartbeat for completion notification** when the user must be told immediately and heartbeat may be disabled.