conduxt

---

name: conduxt description: > Orchestrate full-duplex coding agent sessions via ACPX (preferred) or tmux (fallback), composing OpenClaw native tools and community Skills. Handles any coding task: requirements, bug fixes, refactoring, investigations. Use when: "implement feature X", "fix this bug", "refactor the API layer", "start agent", "open a session", "code this", "fix issue #N". user-invocable: true homepage: https://github.com/xuezhouyang/conduxt metadata: {"openclaw": {"emoji": "🎛️", "requires": {"bins": ["git", "jq"], "anyBins": ["acpx", "tmux"]}, "os": ["darwin", "linux"]}}

---

CLI Coding Orchestrator

> You are the orchestrator. Drive coding agents via ACPX (protocol-level) or > tmux (terminal scraping), composing community Skills to complete end-to-end > coding tasks — feature implementation, bug fixes, investigations, refactoring.

---

1. Your Role

You are the OpenClaw Main model. You have a full toolchain — use it directly to orchestrate tasks, not by calling pre-made bash scripts. Scripts in the scripts/ directory exist only as optional helpers.

2. Dual-Backend Architecture: ACPX vs tmux

This Skill supports two agent communication backends. Prefer ACPX, use tmux as fallback.

Why ACPX First

| Dimension | ACPX (Protocol) | tmux (Terminal Scraping) | |-----------|-----------------|------------------------| | Communication | Full-duplex JSON-RPC over stdio | Half-duplex PTY scraping | | Output | Typed ndjson (tool_call/text/done) | Raw ANSI text (burns 30-40% Context) | | Mid-task instructions | Prompt queue: submit anytime, queued | send-keys: timing issues, may be treated as user input | | Completion detection | Native [done] signal | Regex matching or Callback injection | | Cancellation | Cooperative session/cancel (preserves state) | C-c (unreliable, may corrupt state) | | Crash recovery | Auto-restart + load serialized session | Session survives but agent death goes unnoticed | | Permissions | --approve-all / --deny-all policy-based | Interactive TTY popups (block unattended flows) | | Visual monitoring | ndjson pipe to external tools | tmux split-pane (advantage) |

ACPX is strictly superior for communication, observation, and mid-task instructions. tmux only wins on maturity and visual monitoring.

When to Use Which

| Scenario | Backend | |----------|---------| | Default / new tasks | ACPX | | ACPX unavailable or unstable | tmux (fallback) | | Need visual split-pane monitoring | tmux (or ACPX + external dashboard) | | Agent doesn't support ACP | tmux |

---

3. Toolbox

Native Tools

| Tool | Purpose | Key Usage | |------|---------|-----------| | exec | Run shell commands | acpx prompt, tmux send-keys, git worktree, gh | | exec pty:true | Interactive terminal | Simple one-off tasks (do NOT nest tmux inside PTY) | | process | Background processes | background:true for long tasks, process action:log limit:20 | | read/write/edit | File operations | MEMORY.md, active-tasks.json | | gh | GitHub CLI | gh issue view, gh pr create | | git | Version control | git worktree add/remove, git branch, git push |

ACPX Commands

| Command | Purpose | |---------|---------| | acpx prompt -s "" | Send prompt (creates session if new, appends if existing) | | acpx prompt -s --no-wait "" | Fire-and-forget (returns immediately) | | acpx prompt -s --format json "" | Structured ndjson output | | acpx sessions list | List all active sessions | | acpx sessions show -s | Show session details | | acpx cancel -s | Cooperative cancel of current task | | acpx prompt -s --approve-all "" | Auto-approve all permission requests |

Community Skills (Composable)

| Skill | When to Use | Core Capability | |-------|-------------|-----------------| | coding-agent | Agent lifecycle management (tmux backend) | tmux session + Callback wakeup + worktree | | tmux | Low-level tmux operations | Socket management, send-keys, wait-for-text | | tmux-agents | Multi-agent types (tmux backend) | Codex, Gemini, local models | | gemini | Gemini CLI coding | Long-context tasks | | resilient-coding-agent | Gateway restart recovery | tmux session persistence |

> Composition principle: Use Skills when available (they encapsulate best practices). > Fall back to native tools when Skills don't cover your needs. > coding-agent / tmux-agents use tmux backend — if using ACPX backend, use acpx commands directly.

---

4. Full-Duplex Communication Model

ACPX Path (Preferred)

User ←→ You (Main) ←→ acpx ←→ ACP Adapter ←→ Coding Agent
          ↕              ↕
       MEMORY.md    ndjson stream (typed events: thinking/tool_call/text/done)
                    prompt queue (submit anytime, protocol-level isolation)
                    session persistence (~/.acpx/sessions/*.json)

User → Agent: acpx prompt -s "" enters the prompt queue

Agent → User: [done] event in ndjson stream → you are woken up → notify user

True full-duplex: Submit new instructions while previous task is running, queued without timing issues

tmux Path (Fallback)

User ←→ You (Main) ←→ tmux session ←→ Coding Agent
          ↕                ↕
       MEMORY.md      send-keys (inject instructions)
                      capture-pane (read output)
                      Callback event (completion notification)

User → Agent: tmux send-keys -t "" Enter

Agent → User: Callback JSON or capture-pane polling

Timing caveat: When agent is busy, send-keys may be treated as user input. Send Escape first and wait for idle.

---

5. Scenario Playbook

Each scenario provides both ACPX (preferred) and tmux (fallback) paths.

Scenario A: Execute Coding Task

Triggers (task source is flexible):

"Implement pagination for the users API"

"Investigate this performance issue"

"Refactor the API layer to RESTful"

"Fix issue #78" (optional, low priority)

1. Understand the Task
   Task sources are diverse — handle flexibly:
   • User describes requirement → use description text as prompt directly
   • Link to external doc/wiki → fetch content and extract requirements
   • GitHub issue → exec: gh issue view  --json title,body
   • Code review comments → extract action items
2. Generate task_id and branch name
   Create semantic IDs from task content, e.g.:
   • "add pagination" → task_id: add-pagination, branch: feat/add-pagination
   • "perf issue"     → task_id: perf-analysis,  branch: fix/perf-analysis
   • issue #78        → task_id: issue-78,        branch: fix/issue-78
3. Create isolated workspace
   → exec: git worktree add ../worktrees/ -b  main
4. Start Coding Agent
   ┌─ ACPX path (preferred) ────────────────────────────────────┐
   │ exec: cd ../worktrees/ && acpx prompt \           │
   │   -s  \                                           │
   │   --approve-all \                                          │
   │   --no-wait \                                              │
   │   ""   │
   │                                                            │
   │ • --no-wait: returns immediately, doesn't block you        │
   │ • --approve-all: auto-approve permissions for unattended   │
   │ • session auto-persisted to ~/.acpx/sessions/.json│
   └────────────────────────────────────────────────────────────┘
   ┌─ tmux path (fallback) ─────────────────────────────────────┐
   │ a) Use coding-agent Skill (recommended)                    │
   │ b) Use tmux-agents Skill (for Gemini/Codex)                │
   │ c) Direct exec:                                            │
   │    tmux new-session -d -s  -c ../worktrees/  │
   │    tmux send-keys -t  "claude" Enter              │
   │    tmux send-keys -t  "" Enter │
   └────────────────────────────────────────────────────────────┘
5. Write MEMORY.md task entry (see §7)
6. Inform user
   → "Session  started, agent is working. Will notify on completion."
7. Wait for completion
   ACPX: [done] in ndjson stream → read result → route
   tmux: Callback arrives or 30min timeout → capture-pane → notify

Parallel tasks: Repeat the above for each task. ACPX natively supports named parallel sessions. Before creating PRs, check for file conflicts between branches with git diff --name-only.

Scenario B: Interactive Session (Human-in-the-Loop)

Trigger: "Start a session for API refactoring"

ACPX:
  exec: acpx prompt -s api-refactor "You are my coding assistant, await instructions."
  → Creates named session, agent enters wait state
tmux:
  exec: tmux new-session -d -s api-refactor -c /path/to/repo
  exec: tmux send-keys -t api-refactor "claude" Enter
Report to user:
  "Session api-refactor started. You can:
   • 'Tell api-refactor to start with interface definitions'
   • 'How is api-refactor doing?'
   • 'Stop api-refactor'"

Scenario C: Mid-Task Intervention (Full-Duplex Core)

Trigger: "Tell to do Y" / "Change 's direction"

ACPX (no timing issues, protocol-level isolation):
  Append instruction:  acpx prompt -s  --no-wait "Focus on interface definitions, skip DB layer"
  Cancel current:      acpx cancel -s 
tmux (watch for timing):
  Append instruction:  tmux send-keys -t  "Focus on interface definitions" Enter
  Interrupt current:   tmux send-keys -t  Escape
  Force stop:          tmux send-keys -t  C-c

Scenario D: Check Progress

Trigger: "How is doing?" / "status"

ACPX:
  exec: acpx sessions show -s 
  → Structured session state, no ANSI stripping needed
  → Or use --format json for recent ndjson events
tmux:
  exec: tmux capture-pane -p -t  -S -20
  → Strip ANSI: sed 's/\x1b\[[0-9;]*[a-zA-Z]//g'
  → Summarize for user (don't paste raw terminal output)
List all sessions:
  ACPX: acpx sessions list
  tmux: tmux list-sessions

Scenario E: Agent Selection

| Condition | Recommended Agent | ACPX Launch | tmux Launch | |-----------|------------------|-------------|-------------| | Default / best coding | Claude Code | acpx prompt -s X --agent claude | coding-agent Skill | | Long context needed | Gemini CLI | acpx prompt -s X --agent gemini | gemini Skill | | Need Codex | Codex CLI | acpx prompt -s X --agent codex | tmux-agents Skill | | Simple one-off | Direct exec | No session needed | exec pty:true |

ACPX-supported agent adapters:

Claude Code: npx @zed-industries/claude-agent-acp (adapter)

Codex CLI: npx @zed-industries/codex-acp (adapter)

Gemini CLI: gemini --experimental-acp (native support)

Scenario F: PR Creation

Trigger: [done] signal or Callback shows completed + tests pass

1. Independently verify tests (don't trust agent's self-report)
   → cd  && 
2. Push branch
   → git push -u origin 
3. Create PR
   → gh pr create --title "fix: