Coding Agent (acpx-first)

Use acpx for all coding agent work. It communicates over the Agent Client Protocol (ACP) — no PTY scraping, structured output, persistent sessions.

# Install (already global on this system)
npm i -g acpx

✅ Primary: acpx (preferred for all agents)

# One-shot (exec) — no session state saved
acpx codex exec "summarize this repo"
acpx claude exec "refactor the auth module"

# Persistent session (prompt) — reuses session per cwd
acpx codex "fix the failing tests"
acpx claude "add error handling to API calls"

# Named parallel sessions
acpx codex -s backend "refactor the API layer"
acpx codex -s frontend "update the React components"

# Auto-approve permissions
acpx --approve-all codex exec "run and fix failing tests"

# Fire-and-forget (background)
acpx --no-wait codex "long refactor task"

# Read prompt from file or stdin
acpx codex -f prompt.txt
cat prompt.md | acpx codex

# With working directory
acpx --cwd ~/Projects/myproject codex "fix the auth bug"

Built-in agent registry

Default agent is codex.

Session management

acpx sessions                          # list sessions
acpx sessions new                      # create new session for current cwd
acpx sessions new --name backend       # named session
acpx sessions close backend            # close named session
acpx sessions history --limit 20       # turn history
acpx codex status                      # check if agent process is alive
acpx codex cancel                      # cancel in-flight turn

⚠️ Fallback: raw exec (only when acpx unavailable or unsupported)

For Claude Code (claude CLI), if acpx isn't working:

# ✅ Fallback for Claude Code (no PTY needed)
cd /path/to/project && claude --permission-mode bypassPermissions --print 'Your task'

# ❌ Wrong for Claude Code
bash pty:true command:"claude --dangerously-skip-permissions 'task'"

For Codex/Pi/OpenCode raw fallback (PTY required):

bash pty:true command:"codex exec 'Your prompt'"

MCP Servers — Available in All Claude Code Sessions

Both MCP servers are pre-configured system-wide and connect automatically when running claude from any workspace directory.

jcodemunch-mcp — Code Exploration

When to use:

• Exploring an unfamiliar codebase before making changes
• Looking up function/class/symbol definitions
• Getting a file outline without reading the whole file
• Tracing call chains or finding symbol usage
• Any code task where you'd otherwise open and read multiple files

Workflow:

# 1. Index the project once (idempotent — safe to re-run)
# In Claude Code prompt: "Use jcodemunch to index this project first"

# Tools available inside Claude Code:
jcodemunch: index_codebase { "path": "/path/to/project" }
jcodemunch: list_projects {}
jcodemunch: get_file_outline { "path": "src/server.js" }
jcodemunch: search_symbols { "query": "handleAuth" }
jcodemunch: get_symbol { "symbol_id": "..." }

Prompt pattern for Claude Code tasks:

cd ~/project && claude --permission-mode bypassPermissions --print \
  'First index this project with jcodemunch, then use symbol search and outlines
   to explore the codebase. Do NOT read full files — use targeted retrieval.
   Task: <your task here>'

Rules:

• Always index before exploring a new project
• Use get_file_outline + search_symbols before reaching for read
• Re-index after major refactors; skip for routine work
• list_projects to avoid re-indexing already-indexed repos

jdocmunch-mcp — Documentation Exploration

When to use:

• Exploring library/framework/API docs before implementing
• Finding config options, installation steps, API reference sections
• Onboarding to an unfamiliar tool
• Any task where you'd otherwise open and skim large README or doc files

Workflow:

# Tools available inside Claude Code:
jdocmunch: list_repos {}                                           # check indexed
jdocmunch: index_local { "path": "/path/to/docs" }                # index local docs
jdocmunch: index_repo { "url": "owner/repo" }                     # index GitHub repo
jdocmunch: get_toc_tree { "repo": "owner/repo" }                  # browse structure
jdocmunch: search_sections { "repo": "...", "query": "auth" }     # find sections
jdocmunch: get_section { "repo": "...", "section_id": "..." }     # read one section
jdocmunch: get_section_context { "repo": "...", "section_id": "..." } # section + context

Pre-indexed docs (already available — no need to re-index):

• OpenClaw docs: index with index_local { "path": "/home/sean/.npm-global/lib/node_modules/openclaw/docs" }

Prompt pattern:

claude --permission-mode bypassPermissions --print \
  'Use jdocmunch to index and explore the docs at <path/repo>.
   Use search_sections and get_section — do NOT read full doc files.
   Task: <your task here>'

Rules:

• Always list_repos before indexing — avoid duplicate indexes
• Pattern: search_sections → get_section (never open full files)
• Use get_section_context when you need surrounding structure
• GITHUB_TOKEN, GOOGLE_API_KEY, OPENAI_API_KEY are pre-configured for summaries + private repos

Installed CLIs

Bash Tool Parameters

Process Tool Actions (for background sessions)

Quick Start: One-Shot Tasks

# One-shot with acpx (preferred)
acpx --cwd ~/project codex exec "Your task"
acpx --cwd ~/project claude exec "Your task"

# With auto-approve
acpx --approve-all --cwd ~/project codex exec "Add error handling to the API calls"

The Pattern: persistent sessions + background

For longer tasks, use persistent sessions or --no-wait:

# Create a named session and start work
cd ~/project
acpx codex sessions new --name myfeature
acpx codex -s myfeature "Build a snake game"

# Check status
acpx codex status -s myfeature
acpx codex sessions history myfeature --limit 10

# Fire-and-forget (returns immediately)
acpx --no-wait --cwd ~/project codex "Long refactor task"

Reviewing PRs

⚠️ CRITICAL: Never review PRs in OpenClaw's own project folder!

# Clone to temp for safe review
REVIEW_DIR=$(mktemp -d)
git clone https://github.com/user/repo.git $REVIEW_DIR
acpx --approve-reads --cwd $REVIEW_DIR codex exec "Review this PR vs main branch and summarize issues"

Parallel Sessions with git worktrees

git worktree add -b fix/issue-78 /tmp/issue-78 main
git worktree add -b fix/issue-99 /tmp/issue-99 main

acpx --approve-all --no-wait --cwd /tmp/issue-78 codex "Fix issue #78"
acpx --approve-all --no-wait --cwd /tmp/issue-99 codex "Fix issue #99"

acpx codex sessions list

Auto-Notify on Completion

Append to your prompt so OpenClaw gets notified when the agent finishes:

... your task here.

When completely finished, run:
openclaw system event --text "Done: [brief summary]" --mode now

⚠️ Rules

1. Use acpx first: Always prefer acpx over raw PTY/exec for coding agent delegation. Fall back to raw exec only if acpx is unavailable or the agent doesn't support ACP.
2. Use MCP servers: Always prompt Claude Code to use jcodemunch for code exploration and jdocmunch for doc exploration — never brute-force read files
3. Respect tool choice — if user asks for Codex, use Codex
4. Be patient — don't kill sessions because they're "slow"
5. Monitor with process:log — check progress without interfering
6. Parallel is OK — run many agents at once for batch work
7. NEVER start Codex in ~/.openclaw/ — it'll read soul docs and get weird ideas about the org chart!
8. NEVER checkout branches in ~/Projects/openclaw/ — that's the LIVE OpenClaw instance!

Progress Updates

• Send 1 short message when you start (what's running + where)
• Update again only when: milestone completes, agent asks a question, error occurs, or agent finishes
• If you kill a session, immediately say why