Skip to content

Executor V2 — Persistent Context Agent Architecture

Problem

The current executor (v1) runs Claude Code in one-shot headless mode (claude -p "prompt"). This means:

  • No ability to ask questions mid-task
  • No follow-up on PR review comments
  • No monitoring of CI/build results
  • No iteration when things fail
  • Creates duplicate PRs on failure/retry
  • Each retry starts from scratch (no context)

Vision

A single Claude Code session that stays alive for the entire task lifecycle:

Pick issue → Explore code → Ask questions on Discord → Implement →
Create PR → Respond to review → Wait for CI → Fix if needed →
Wait for merge → Wait for cloud build → Done → Clear context

The agent should work like a human developer: persistent context, interactive communication, iterative improvement.

Technical Research

Available Tools

1. Claude Code --continue / --resume

Sessions persist in ~/.claude/history.jsonl and can be resumed:

# Start a named session
claude -n "star-rewards-516"

# Continue most recent session
claude --continue

# Resume specific session
claude --resume "star-rewards-516"

# Resume from a PR
claude --from-pr 517

Sessions restore full message history, tool results, and conversation context.

Limitation: --continue and --resume are interactive (require TTY). Can't be used with -p (headless mode). Need to figure out how to automate turn-by-turn interaction.

2. OpenClaw acpx (Agent Client Protocol)

acpx is a headless CLI client for stateful ACP sessions:

  • Persistent sessions that survive across invocations
  • Named sessions scoped per repo
  • Prompt queueing — submit prompts while one is running
  • Cooperative cancel — cancel without destroying session state
  • Supports Claude Code, Codex, and other ACP-compatible agents

This is the most promising approach for our use case. acpx can send prompts to a running agent session and get responses back programmatically.

# Start a session
acpx session start --name "issue-516" --agent claude

# Send a prompt
acpx prompt "Explore the codebase and fix issue #516"

# Send follow-up (same session)
acpx prompt "The reviewer asked to add tests. Add them."

# Check status
acpx session status

3. Claude Code /loop Command

Built-in scheduled task runner. Could be used for monitoring:

# Inside a Claude session:
/loop 5m check if PR #517 has been reviewed

But requires an active interactive session.

4. Multi-Turn Headless via stdin Piping

Chain multiple headless calls with --continue:

# Turn 1: Explore and plan
claude -p "Explore star-rewards and plan fix for #516" --output-format json > /tmp/turn1.json

# Turn 2: Implement (continues same session)
claude -p "Implement the plan" --continue --output-format json > /tmp/turn2.json

# Turn 3: Respond to review
claude -p "Address review comment: add tests" --continue --output-format json > /tmp/turn3.json

Note: Need to verify if --continue works with -p in the latest Claude Code version.

Proposed Architecture

Use OpenClaw acpx for stateful session management:

executor.sh (orchestrator)
    │
    ├── find_next_issue()          # Poll for agent-ready issues
    ├── start_session()            # acpx session start --name "repo-issue-N"
    │
    ├── PHASE 1: Understand        # acpx prompt "Read issue, explore code, plan"
    │   └── check_questions()      # Parse output for Discord questions
    │
    ├── PHASE 2: Implement         # acpx prompt "Implement the plan"
    │   └── check_build()          # acpx prompt "Run xcodebuild, fix errors"
    │
    ├── PHASE 3: PR                # acpx prompt "Create PR with conventional commits"
    │   └── monitor_review()       # Poll for Copilot/Review-E comments
    │       └── address_review()   # acpx prompt "Address review: {comments}"
    │
    ├── PHASE 4: Merge             # Wait for auto-merge or manual merge
    │   └── monitor_ci()           # Poll for CI status
    │       └── fix_ci()           # acpx prompt "CI failed: {error}. Fix it."
    │
    ├── PHASE 5: Cloud Build       # Wait for Xcode Cloud build (if applicable)
    │   └── monitor_build()        # Poll ASC for build status
    │       └── fix_build()        # acpx prompt "Cloud build failed: {error}"
    │
    └── end_session()              # acpx session end

Option B: Interactive Claude with tmux

Run Claude Code interactively in a tmux session, send keystrokes:

# Start tmux session
tmux new-session -d -s "executor"

# Send prompt via tmux
tmux send-keys -t executor "Fix issue #516 in star-rewards" Enter

# Read output
tmux capture-pane -t executor -p

Pros: Full interactive mode, all features available Cons: Fragile (parsing terminal output), hard to detect completion

Option C: Hybrid (Current executor + resume)

Keep current executor for initial implementation, then resume for follow-up:

# Phase 1: Initial implementation (current approach)
claude -p "Fix issue #516" --output-format stream-json -n "issue-516"

# Phase 2: Address review (new)
claude -p "Address PR review comments: ..." --continue -n "issue-516"

# Phase 3: Fix CI (new)
claude -p "CI failed with: ... Fix it." --continue -n "issue-516"

Pros: Incremental improvement, less risky Cons: Still headless, can't ask questions mid-task, each turn is a separate process

Phase 1 (Now): Option C — Hybrid. Add --continue support to current executor for review/CI follow-up. Minimal changes.

Phase 2 (Next): Option A — acpx. Full persistent context with prompt queueing. Requires acpx installation and session management logic.

Executor V2 Lifecycle

┌─────────────────────────────────────────────────┐
│                  IDLE (polling)                  │
└───────────┬─────────────────────────────────────┘
            │ agent-ready issue found
            ▼
┌─────────────────────────────────────────────────┐
│  PHASE 1: UNDERSTAND                            │
│  - Read issue, explore code                     │
│  - Recall memory (learnings, decisions)         │
│  - Plan approach                                │
│  - Post plan to Discord                         │
│  - ASK questions if unclear → wait for answer   │
└───────────┬─────────────────────────────────────┘
            ▼
┌─────────────────────────────────────────────────┐
│  PHASE 2: IMPLEMENT                             │
│  - Write code                                   │
│  - Build & test locally                         │
│  - Fix errors (up to 3 retries)                 │
│  - Post progress to Discord                     │
│  - ASK for help if stuck → wait for answer      │
└───────────┬─────────────────────────────────────┘
            ▼
┌─────────────────────────────────────────────────┐
│  PHASE 3: PR & REVIEW                           │
│  - Create PR                                    │
│  - Wait for Copilot review (2-5 min)            │
│  - Address review comments                      │
│  - Push fixes                                   │
│  - Repeat until approved                        │
└───────────┬─────────────────────────────────────┘
            ▼
┌─────────────────────────────────────────────────┐
│  PHASE 4: MERGE & CI                            │
│  - Wait for auto-merge                          │
│  - If CI fails: fix, push, new PR               │
│  - Post result to Discord                       │
└───────────┬─────────────────────────────────────┘
            ▼
┌─────────────────────────────────────────────────┐
│  PHASE 5: CLOUD BUILD (optional)                │
│  - Wait for Xcode Cloud build                   │
│  - If build fails: investigate, create fix PR   │
│  - Post TestFlight link when ready              │
└───────────┬─────────────────────────────────────┘
            ▼
┌─────────────────────────────────────────────────┐
│  COMPLETE                                       │
│  - Save learnings to memory                     │
│  - Clear context                                │
│  - Return to IDLE                               │
└─────────────────────────────────────────────────┘

Discord Communication

Throughout all phases, the agent should:

Event Action
Starting work Post "Starting work on {repo}#{issue}"
Plan ready Post plan summary
Question Post question, wait for reply (check every 60s, timeout after 5 min)
Stuck Post error + what was tried, continue trying
PR created Post PR link
Review received Post "Addressing N review comments"
CI failed Post error, working on fix
Merged Post "Merged to main"
Build status Post TestFlight link or build failure
Complete Post summary (time, tokens, files changed)

Context Management

Concern Strategy
Context window Opus 4.6 has 1M tokens. Most tasks use <200K. Safe for full lifecycle.
Compaction OpenClaw has safeguard mode with 40K reserve floor. Sufficient.
Memory Use MCP memory tools to persist learnings across tasks.
Session naming {repo}-{issue-number} (e.g., star-rewards-516)
Cleanup Delete session after successful completion. Keep on failure for debugging.

Open Questions

  1. Does --continue work with -p in current Claude Code? Need to test.
  2. acpx availability — is it packaged for macOS ARM64? Need to check.
  3. Rate limits — long-running sessions on Max subscription: any limits?
  4. Concurrent agents — can iBuild-E and iClaw-E share the same Mac Mini without session conflicts?
  5. Timeout — maximum session duration before auto-cleanup?

References