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

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

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

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

# 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": "..." }

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

# 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

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

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

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

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

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

... your task here.

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