Ahelpa

ahelpa — Agent Help Agent

What is ahelpa

ahelpa lets you spawn, manage, and communicate with persistent helper agents running in tmux. Use it to delegate long-running tasks, fan out work across multiple parallel agents, or get a second opinion from a fresh context without polluting your own conversation.

Packaged releases include the runtime bundle. Source checkouts can build it with bun run package:skill.

Public documentation is available in English and Simplified Chinese:

• README.md / README.zh-CN.md
• docs/ / docs/zh-CN/

Installation

which ahelpa || {
  mkdir -p ~/.ahelpa/bin
  tar xzf <skill-dir>/bundle/ahelpa-darwin-arm64.tar.gz -C ~/.ahelpa/bin/
  export PATH="$HOME/.ahelpa/bin:$PATH"
}

Replace <skill-dir> with the absolute path to this skill's directory. The binary installs to ~/.ahelpa/bin/. Run ahelpa version to verify. If the bundle is missing in a source checkout, run bun run package:skill first.

Quick Start

result=$(ahelpa launch claude-code --task "Refactor the auth module")
session_id=$(echo $result | jq -r .sessionId)
token=$(echo $result | jq -r .ownerToken)
ahelpa wait "$session_id"
cat ".ahelpa/$session_id/summary.md"

Helper type to CLI binary mapping:

• claude-code → claude CLI on PATH
• codex → codex CLI on PATH

Verify prerequisites with command -v claude or command -v codex, not command -v claude-code.

Key Rules

1. File handoff is the protocol. Exchange tasks and results through files. Do not rely on capture to parse terminal output. 2. `wait` blocks until completion or timeout. Default 500 seconds. If it returns still_running, re-wait — this is normal, not an error. 3. Wait on multiple helpers at once. Use ahelpa wait id1 id2 id3, not one-at-a-time waits. 4. Ownership is non-transitive. You can only manage sessions you launched. Your helper's helpers are not yours to control. 5. Results land in files. After completion: .ahelpa/<session-id>/summary.md for the summary, .ahelpa/<session-id>/artifacts/ for supporting files. 6. Use `task` for long instructions. ahelpa task <id> --file <path> avoids tmux keystroke limits. 7. `capture` is for debugging only. Not a communication channel. 8. Tidy up. After reading results, move useful outputs to the project tree and keep .ahelpa/ clean. 9. Helpers have full permissions. They run as the local user. Use --project to scope working directories, or git worktrees for isolation. 10. Inline refresh works without daemon. wait, check, and status refresh session state even if the daemon isn't running. 11. Don't re-derive the CLI. Follow this document for normal helper delegation. Only inspect src/ or tests/ when debugging ahelpa itself. 12. Trust prompt handling is automatic. The codex driver handles directory trust prompts by sending Enter. No manual intervention needed during normal use.

Timing and Patience

Helpers are full coding agents. A meaningful task typically takes 2–10 minutes.

• Wait first, ask questions later. The 500-second default is generous.
• `still_running` is normal. Re-wait. The helper is working.
• Don't capture early. It adds no information in the first few minutes.
• Don't poll every 30 seconds. One wait, then one re-wait if needed.
• Escalate after 8–10 minutes of silence. Use capture once to see what's happening, then send to nudge or kill and retry.

Command Reference

Sentinel Protocol

Helpers signal completion by printing sentinel strings to stdout:

• [AHELPA:DONE] — task finished; results written to .ahelpa/<session-id>/
• [AHELPA:NEED_HELP] — helper is stuck and needs input from the host

The daemon (or inline refresh) detects these and transitions session state: DONE → idle, NEED_HELP → error. A wait returning error means the helper asked for help — use capture or logs to see what it needs, then send to intervene.

Messenger Pattern

For long tasks or multiple parallel helpers, spawn a cheap background subagent to poll rather than blocking with wait.

Messenger prompt template:

You are a messenger. Your only job is:
1. Periodically run: ahelpa check
2. When a session shows idle/error/dead, inspect its .ahelpa/<session-id>/ result directory
3. Report the status and summarize summary.md plus any artifacts
4. Do NOT do any work yourself — no analysis, no coding, no modifications
5. Be patient. No results is normal. Keep checking.

See references/claude-code.md and references/codex.md for platform-specific messenger setup.

Troubleshooting

ahelpa is a thin layer over tmux. Every helper is a plain tmux session:

tmux ls                                # list all sessions
tmux attach -t <session-id>            # attach and see live output
tmux capture-pane -t <session-id> -p   # dump pane content without attaching

Manual tmux intervention is an allowed escape hatch, not a protocol violation. After manual intervention, the sentinel protocol still works.

Closure Gate

For development/testing of ahelpa itself:

bun run closure:gate

Verifies the full launch → wait → capture → kill cycle across both drivers. If codex returns an authentication error, fix the local codex CLI login state before running the gate.

ahelpa on Claude Code

Platform-specific guidance for using ahelpa inside Claude Code.

Binary Mapping

• ahelpa launch claude-code ... uses the claude CLI
• ahelpa launch codex ... uses the codex CLI

Verify with command -v claude or command -v codex, not command -v claude-code.

Typical Workflow

# 1. Launch a helper
result=$(ahelpa launch claude-code --task "Add unit tests for auth.ts" --project /path/to/project)
session_id=$(echo $result | jq -r .sessionId)
token=$(echo $result | jq -r .ownerToken)

# 2a. Short task: wait inline
ahelpa wait "$session_id"

# 2b. Long task: spawn a messenger (see below)

# 3. Pick up results
cat ".ahelpa/$session_id/summary.md"
ls ".ahelpa/$session_id/artifacts/"

Cross-agent launch:

result=$(ahelpa launch codex --task "Migrate the database schema" --project /path/to/project)
session_id=$(echo "$result" | jq -r .sessionId)
ahelpa wait "$session_id"

Spawning a Messenger

Use the Agent tool with run_in_background: true and a cheap model:

{
  "tool": "Agent",
  "input": {
    "model": "haiku",
    "run_in_background": true,
    "prompt": "You are a messenger. Your only job is:\n1. Periodically run: ahelpa check\n2. When a session shows idle/error/dead, inspect .ahelpa/<session-id>/\n3. Report the status and summarize summary.md plus any artifacts\n4. Do NOT do any work yourself — no analysis, no coding, no modifications\n5. Be patient. No results is normal. Keep checking."
  }
}

PostToolUse Hook

You can configure a hook to automatically check helper status after every Bash call:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "ahelpa check --parent 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

This gives passive status notifications without manual polling.

Timeout

ahelpa wait defaults to 500 seconds, fitting within Claude Code's 600-second Bash tool timeout. Never set --timeout above 580 to preserve teardown headroom.

Codex Helper Note

In some directories, codex shows a one-time trust prompt. The launch flow handles this automatically by sending Enter. If codex still looks idle, run ahelpa check to re-read session state.

Usage Discipline

For normal helper delegation, follow the SKILL.md workflow directly. Only inspect src/ or tests/ when debugging ahelpa itself.

ahelpa on Codex

Platform-specific guidance for using ahelpa inside the Codex CLI.

Runtime Constraints

Codex operates in persistent interactive mode only — there is no background agent or subagent tool. All ahelpa operations happen inline in your conversation loop.

Codex is launched with --dangerously-bypass-approvals-and-sandbox, so helper agents also run with full permissions. Be deliberate about --project and working directory isolation.

Binary Mapping

• ahelpa launch codex ... uses the codex CLI
• ahelpa launch claude-code ... uses the claude CLI

Verify with command -v codex or command -v claude, not command -v claude-code.

Trust Prompts

In some directories, codex shows a one-time trust prompt (Do you trust the contents of this directory?). The launch flow handles this automatically by sending Enter, then proceeds to task delivery. If a task appears idle for an unusually long time, run ahelpa check to re-read session state.

Typical Workflow

# 1. Launch a helper
result=$(ahelpa launch codex --task "Migrate DB schema" --project /path/to/project)
session_id=$(echo $result | jq -r .sessionId)

# 2. Wait (500s default fits Codex interactive limits)
ahelpa wait "$session_id"

# 3. Pick up results
cat ".ahelpa/$session_id/summary.md"
ls ".ahelpa/$session_id/artifacts/"

Cross-agent launch:

result=$(ahelpa launch claude-code --task "Review the API contracts" --project /path/to/project)
session_id=$(echo "$result" | jq -r .sessionId)
ahelpa wait "$session_id"

Messenger Pattern

Codex has no background agent tool, so the messenger pattern works differently: you must poll inline rather than delegating to a subagent.

while true; do
  result=$(ahelpa check)
  echo "$result" | jq '.[] | select(.status == "idle" or .status == "error" or .status == "dead")'
  sleep 30
done

Prefer ahelpa wait for single short tasks. Structure multi-helper work so you can checkpoint and poll between steps.

Notes

• No PostToolUse hooks in Codex — manual ahelpa check is required.
• capture is available for debugging but should not be part of normal flow.
• wait, check, and status perform inline refresh even without the daemon running.
• Keep .ahelpa/ tidy: move useful outputs to the project tree when done.

Usage Discipline

For normal helper delegation, follow the SKILL.md workflow directly. Only inspect src/ or tests/ when debugging ahelpa itself.