vultr/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-05-06 05:50:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: enforce background mode & direct completion in coding-agent (#53585)

Browse Source
This commit is contained in:
周辉
2026-04-26 04:50:50 +08:00
committed by GitHub
parent 70d1871db7
commit 23a818fa2d
1 changed files with 176 additions and 131 deletions
Download Patch File Download Diff File Expand all files Collapse all files

307
skills/coding-agent/SKILL.md
View File

@@ -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 <channel> --target '<target>' --message '<text>'
```
**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 <id>`
- `--reply-to <messageId>`
- `--thread-id <threadId>`
`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: <notifyChannel>
- target: <notifyTarget>
- account: <notifyAccount or omit>
- reply_to: <notifyReplyTo or omit>
- thread_id: <notifyThreadId or omit>
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 <notifyChannel> \
--target '<notifyTarget>' \
--message 'Done: <brief summary>'
```
Optional additions:
```bash
--account <notifyAccount> \
--reply-to <notifyReplyTo> \
--thread-id <notifyThreadId>
```
---
## 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: <notifyChannel>
- target: <notifyTarget>
- account: <notifyAccount or omit>
- reply_to: <notifyReplyTo or omit>
- thread_id: <notifyThreadId or omit>
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 <PR#> --body "<review content>"
process action:log sessionId:XXX
```
---
@@ -188,10 +244,6 @@ gh pr comment <PR#> --body "<review content>"
## 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: <description>. 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: <description>. 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.