Coding Agent Backup

Delegate coding tasks to Codex, Claude Code, or Pi agents via background process. Use when: (1) building/creating new features or apps, (2) reviewing PRs (sp...

Security Scan

The skill's description claims to orchestrate local coding CLIs (Codex/Claude/Pi) but the shipped files include code that calls Google's Generative Language API with a hard-coded API key and a default workdir — these artifacts don't match the declared requirements and raise data-exfiltration and credential-management concerns.

Purpose & Capability

The SKILL.md and metadata describe delegating to local/CLI coding agents (claude, codex, opencode, pi) and declare anyBins for those CLIs. However the included index.js implements an entirely different approach: it calls the Google Generative Language (Gemini) REST API using a hard-coded API key and a network endpoint. That behavior is not declared in requires.env or the SKILL.md and is inconsistent with the stated purpose of orchestrating local CLIs.

Instruction Scope

SKILL.md instructs the agent to spawn background processes in arbitrary workdirs, clone repositories to temp dirs, run agents with elevated/no-sandbox flags (e.g. codex --yolo), and post PR comments via gh. Those instructions legitimately need filesystem and network access for reviews/builds, but the docs do not disclose that bundled code will send user-provided prompts/code to an external API (generativelanguage.googleapis.com). The instructions also allow running in broad host workdirs and elevated mode, increasing the risk of accidental exposure.

Install Mechanism

There is no external install step (instruction-only style), which is lower risk, but the package includes index.js and config.json. index.js contains outbound HTTPS calls to a public ML endpoint and a hard-coded API key. While no remote download/extract occurs at install, the included code itself will make network requests if executed — this is a runtime risk even without an installer.

Credentials

requires.env lists none, yet index.js embeds an apparent Google API key and uses it in requests. This is a mismatch: a network-capable key is present but not declared as a required credential. config.json sets workdir to '/home/admin/code' and enabled:true, implying access to a broad host directory by default. The skill requests broad filesystem and network access (via SKILL.md instructions) without proportional transparency or explicit env var handling.

Persistence & Privilege

always:false (not force-included), which is fine. However config.json sets enabled:true, priority:10 and a default workdir under /home/admin/code — this may cause the skill to be active and operate in a high-privilege area of the host unless the platform overrides it. The skill does not request to modify other skills' configs, but the default config and background/pty patterns mean it could access large parts of the user's codebase if run.

Scan Findings in Context

[hardcoded_api_key] unexpected: index.js contains a hard-coded API key string (assigned to this.apiKey) and appends it to requests to generativelanguage.googleapis.com. The SKILL.md and requires.env do not declare any Google API key requirement: credentials are not exposed as a required env var but are embedded in code, which is not appropriate for a skill whose declared purpose is to orchestrate local CLIs.

[external_network_request] unexpected: index.js makes direct HTTPS POST requests to a third-party generative model endpoint. The skill documentation focuses on running local CLIs and background processes; it does not disclose that user-provided prompts or repository contents may be transmitted to an external API provider.

[default_sensitive_workdir] unexpected: config.json sets workdir to '/home/admin/code' and enabled:true. The SKILL.md warns not to run agents in a particular workspace, but the default workdir is broad and could cause the skill to operate on sensitive files by default. This default is not declared in the skill metadata 'requires' fields.

What to consider before installing

Do not install or run this skill without changes. The package contains an index.js that will send prompts (potentially including code) to an external Google Generative Language endpoint using a hard-coded API key — the key is embedded in the file rather than provided explicitly via a declared environment variable. This is inconsistent with the skill's docs (which claim to orchestrate local CLI agents) and risks leaking repository contents and secrets. If you consider using it, ask the author to: (1) remove any hard-coded credentials and require a declared environment variable (e.g., GOOGLE_API_KEY) instead; (2) document and require any external API usage in SKILL.md and requires.env; (3) avoid defaulting to broad host workdirs (do not set /home/admin/code) and make workdir explicit at run-time; (4) remove or clearly flag 'no sandbox' / --yolo behaviors and any elevated-host instructions; (5) provide a verifiable homepage/origin and justification for why a remote model is necessary. If you already ran this skill, assume the embedded API key may be compromised — rotate/disable the key and audit any external requests or data that may have been sent.

Coding Agent (bash-first)

Use bash (with optional background mode) for all coding agent work. Simple and effective.

⚠️ PTY Mode Required!

Coding agents (Codex, Claude Code, Pi) are interactive terminal applications that need a pseudo-terminal (PTY) to work correctly. Without PTY, you'll get broken output, missing colors, or the agent may hang.

Always use pty:true when running coding agents:

# ✅ Correct - with PTY
bash pty:true command:"codex exec 'Your prompt'"

# ❌ Wrong - no PTY, agent may break
bash command:"codex exec 'Your prompt'"

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)

Process Tool Actions (for background sessions)

Action	Description
list	List all running/recent sessions
poll	Check if session is still running
log	Get session output (with optional offset/limit)
write	Send raw data to stdin
submit	Send data + newline (like typing and pressing Enter)
send-keys	Send key tokens or hex bytes
paste	Paste text (with optional bracketed mode)
kill	Terminate the session

---

Quick Start: One-Shot Tasks

For quick prompts/chats, create a temp git repo and run:

# Quick chat (Codex needs a git repo!)
SCRATCH=$(mktemp -d) && cd $SCRATCH && git init && codex exec "Your prompt here"

# 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.

---

The Pattern: workdir + background + pty

For longer tasks, use background mode with PTY:

# 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

Why workdir matters: Agent wakes up in a focused directory, doesn't wander off reading unrelated files (like your soul.md 😅).

---

Codex CLI

Model: gpt-5.2-codex is the default (set in ~/.codex/config.toml)

Flags

Flag	Effect
exec "prompt"	One-shot execution, exits when done
--full-auto	Sandboxed but auto-approves in workspace
--yolo	NO sandbox, NO approvals (fastest, most dangerous)

Building/Creating

# Quick one-shot (auto-approves) - remember PTY!
bash pty:true workdir:~/project command:"codex exec --full-auto 'Build a dark mode toggle'"

# Background for longer work
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.

# 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"

Batch PR Reviews (parallel army!)

# 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>"

---

Claude Code

# With PTY for proper terminal output
bash pty:true workdir:~/project command:"claude 'Your task'"

# Background
bash pty:true workdir:~/project background:true command:"claude 'Your task'"

---

OpenCode

bash pty:true workdir:~/project command:"opencode run 'Your task'"

---

Pi Coding Agent

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

# Non-interactive mode (PTY still recommended)
bash pty:true command:"pi -p 'Summarize src/'"

# Different provider/model
bash pty: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:

# 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.'"

# 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

---

⚠️ Rules

1. Always use pty:true - coding agents need a terminal!
2. Respect tool choice - if user asks for Codex, use Codex.
   • Orchestrator mode: do NOT hand-code patches yourself.
   • If an agent fails/hangs, respawn it or ask the user for direction, but don't silently take over.
3. Be patient - don't kill sessions because they're "slow"
4. Monitor with process:log - check progress without interfering
5. --full-auto for building - auto-approves changes
6. vanilla for reviewing - no special flags needed
7. Parallel is OK - run many Codex processes at once for batch work
8. NEVER start Codex in ~/.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!

---

Progress Updates (Critical)

When you spawn coding agents 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
  • you hit an error or need user action
  • the agent finishes (include what changed + where)
• If you kill a session, immediately say you killed it and why.

This prevents the user from seeing only "Agent failed before reply" and having no idea what happened.

---

Auto-Notify on Completion

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 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.

---

Learnings (Jan 2026)

• 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" 🦞