---
name: conduxt-b36d33a47054
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 <session> "<instruction>"` | Send prompt (creates session if new, appends if existing) |
| `acpx prompt -s <session> --no-wait "<msg>"` | Fire-and-forget (returns immediately) |
| `acpx prompt -s <session> --format json "<msg>"` | Structured ndjson output |
| `acpx sessions list` | List all active sessions |
| `acpx sessions show -s <session>` | Show session details |
| `acpx cancel -s <session>` | Cooperative cancel of current task |
| `acpx prompt -s <session> --approve-all "<msg>"` | 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 <session> "<instruction>"` 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 <session> "<text>" 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 <N> --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/<task_id> -b <branch> main

4. Start Coding Agent

   ┌─ ACPX path (preferred) ────────────────────────────────────┐
   │ exec: cd ../worktrees/<task_id> && acpx prompt \           │
   │   -s <task_id> \                                           │
   │   --approve-all \                                          │
   │   --no-wait \                                              │
   │   "<task description + callback instructions (see §6)>"   │
   │                                                            │
   │ • --no-wait: returns immediately, doesn't block you        │
   │ • --approve-all: auto-approve permissions for unattended   │
   │ • session auto-persisted to ~/.acpx/sessions/<task_id>.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 <task_id> -c ../worktrees/<id>  │
   │    tmux send-keys -t <task_id> "claude" Enter              │
   │    tmux send-keys -t <task_id> "<prompt + callback>" Enter │
   └────────────────────────────────────────────────────────────┘

5. Write MEMORY.md task entry (see §7)

6. Inform user
   → "Session <task_id> 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 <session> to do Y" / "Change <session>'s direction"

```
ACPX (no timing issues, protocol-level isolation):
  Append instruction:  acpx prompt -s <session> --no-wait "Focus on interface definitions, skip DB layer"
  Cancel current:      acpx cancel -s <session>

tmux (watch for timing):
  Append instruction:  tmux send-keys -t <session> "Focus on interface definitions" Enter
  Interrupt current:   tmux send-keys -t <session> Escape
  Force stop:          tmux send-keys -t <session> C-c
```

### Scenario D: Check Progress

**Trigger**: "How is <session> doing?" / "status"

```
ACPX:
  exec: acpx sessions show -s <session>
  → Structured session state, no ANSI stripping needed
  → Or use --format json for recent ndjson events

tmux:
  exec: tmux capture-pane -p -t <session> -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 <worktree> && <auto-detect test runner>

2. Push branch
   → git push -u origin <branch>

3. Create PR
   → gh pr create --title "fix: <title>" --body "..." --base main --head <branch>

4. Update MEMORY.md: status=completed, add PR link

5. Notify user
```

### Scenario G: Cleanup

```
ACPX:
  End session (history preserved in ~/.acpx/sessions/)
  → No need to kill processes, ACPX manages lifecycle

tmux:
  tmux kill-session -t <session>

Common:
  git worktree remove <dir> --force
  git branch -d <branch> (optional)
  Edit MEMORY.md: status → abandoned or completed
```

---

## 6. Structured Callback Protocol

### ACPX Path

ACPX ndjson stream natively provides `[done]` signals, but we still inject the
Callback JSON instruction for unified processing logic. The JSON can be extracted
directly from the ndjson stream — **no regex matching against terminal output**.

### tmux Path

Requires injection and detection of `callback-json` keyword via capture-pane.

### Injection Content (Shared by Both Paths)

Append to the end of the agent prompt:

```
When you complete this task, you MUST output the following JSON block
wrapped in triple backticks with language tag "callback-json":

{
  "task_id": "<task_id>",
  "status": "completed|failed|need_clarification",
  "branch": "<branch>",
  "files_changed": ["file1.go", "file2_test.go"],
  "test_results": { "passed": 42, "failed": 0, "skipped": 1 },
  "duration_minutes": 12,
  "summary": "Brief description of what was done"
}

Commit your code and run tests BEFORE outputting this JSON. This is mandatory.
```

### Routing Rules

| Condition | Your Action |
|-----------|-------------|
| `completed` + `failed=0` | Independently verify tests → create PR → notify user |
| `completed` + `failed>0` | Append instruction: "N tests failing, please fix and re-output callback" |
| `failed` | Update MEMORY.md → notify user of failure reason |
| `need_clarification` | Forward `summary` to user, wait for reply, then send to agent |

Pure if/else — no LLM interpretation of natural language needed.

### Completion Detection Comparison

| Method | ACPX | tmux |
|--------|------|------|
| Primary | ndjson `[done]` signal | `coding-agent` Skill built-in Callback |
| Fallback | Extract callback-json from ndjson | `capture-pane` regex matching |
| Background | N/A (stream is continuous) | `scripts/watchdog.sh` |

---

## 7. State Persistence

### MEMORY.md Task Entry

```markdown
## In-Flight Tasks

### add-pagination: Implement pagination for /api/users
- **Status**: in-progress
- **Branch**: feat/add-pagination
- **Session**: add-pagination
- **Backend**: ACPX | tmux
- **Agent**: Claude Code | Gemini CLI
- **Started**: 2026-03-10T14:30:00Z
- **Latest Milestone**: 14:42 - Running tests
- **Callback**: pending
```

### When to Write

| Event | Action |
|-------|--------|
| Task created | Add entry, status=pending |
| Agent started | status → in-progress, record backend type |
| User asks for progress | Update Latest Milestone |
| Completion signal received | status → completed/failed |
| PR created | Add PR link |
| Cleanup | status → completed/abandoned |

> **MEMORY.md must be written under any backend** — it is the only shared state
> across sessions and agents. ACPX session history is per-agent and does not
> share across sessions.

---

## 8. Crash Detection

### ACPX Path

ACPX has built-in crash recovery — auto-restarts agent and loads serialized session.
You only need to check if the session is still active:

```bash
acpx sessions list              # check if session exists
acpx sessions show -s <session> # check detailed status
```

If session disappeared (ACPX itself crashed), recover context from MEMORY.md and recreate.

### tmux Path

tmux session survives but agent may have died:

```bash
tmux has-session -t <session> 2>/dev/null  # is session alive
tmux capture-pane -p -t <session> -S -1    # any output
```

Optional: `scripts/watchdog.sh` background loop (zero token).

---

## 9. Optional Helper Scripts

Three scripts in `scripts/` with dual-backend support. You **can use them but don't have to**:

| Script | Purpose |
|--------|---------|
| `setup.sh <task_id> <branch> <worktree_dir> [task_desc] [backend]` | Create branch + worktree + initialize MEMORY.md |
| `launch.sh <task_id> <worktree_dir> <prompt_file> [backend] [agent]` | ACPX-first agent launch with auto tmux fallback |
| `watchdog.sh [task_id]` | Background zero-token monitoring (ACPX/tmux aware) |

Parameters:
- `backend`: `acpx` (default if available) | `tmux` | `auto`
- `agent`: `claude` | `gemini` | `codex` | `aider` | `auto`

---

## 10. Command Reference

### ACPX Commands

| Action | Command |
|--------|---------|
| Send prompt | `acpx prompt -s <name> "<text>"` |
| Fire-and-forget | `acpx prompt -s <name> --no-wait "<text>"` |
| Structured output | `acpx prompt -s <name> --format json "<text>"` |
| Auto-approve perms | `acpx prompt -s <name> --approve-all "<text>"` |
| List sessions | `acpx sessions list` |
| Show session | `acpx sessions show -s <name>` |
| Cancel task | `acpx cancel -s <name>` |

### tmux Commands

| Action | Command |
|--------|---------|
| Create session | `tmux new-session -d -s <name> -c <dir>` |
| Send instruction | `tmux send-keys -t <name> "<text>" Enter` |
| Read output | `tmux capture-pane -p -t <name> -S -30` |
| List sessions | `tmux list-sessions` |
| Send interrupt | `tmux send-keys -t <name> C-c` |
| Kill session | `tmux kill-session -t <name>` |

### Common Commands

| Action | Command |
|--------|---------|
| Fetch issue | `gh issue view <N> --json title,body,labels` |
| Create worktree | `git worktree add <dir> -b <branch> main` |
| Remove worktree | `git worktree remove <dir>` |
| Push branch | `git push -u origin <branch>` |
| Create PR | `gh pr create --title "..." --body "..." --base main --head <branch>` |

---

## 11. Relationship with Existing Skills

| Skill | Backend | Your Usage |
|-------|---------|------------|
| `coding-agent` | tmux | Preferred agent launch for tmux fallback |
| `tmux` | tmux | Low-level operations (custom socket, wait-for-text) |
| `tmux-agents` | tmux | Multi-agent types (Codex, Gemini, local models) |
| `gemini` | tmux | Gemini CLI for long-context tasks |
| `resilient-coding-agent` | tmux | Gateway restart recovery |

> When using ACPX backend, these tmux-based Skills don't apply. Use `acpx` commands directly.
> When ACPX is unavailable, fall back to these Skills.

---

## 12. Evolution Roadmap

```
Phase 1 (Current): ACPX and tmux in parallel
  • New tasks prefer ACPX
  • ACPX instability → tmux fallback
  • Validate ACPX session persistence and crash recovery

Phase 2: High-value migration
  • Migrate half-duplex and context-pollution-heavy scenarios to ACPX
  • tmux demoted to visual monitoring only

Phase 3 (End state): ACPX as primary path
  • tmux optional (visual only)
  • ACPX becomes the standard interface for all agent communication
```

---

## 13. Important Notes

1. **ACPX stability**: ACPX is still early-stage and may have breaking changes. Fall back to tmux immediately on issues.
2. **No PTY nesting**: Do NOT start tmux inside `exec pty:true` (double PTY allocation)
3. **tmux send-keys timing**: When agent is busy, send `Escape` first and wait for idle before appending
4. **Don't pull full logs**: Use capture-pane `-S -20`, ACPX use `--format json` pipe
5. **Security**: Never pass API keys or secrets via send-keys or acpx prompt
6. **ACPX permissions**: Use `--approve-all` for unattended; `--approve-reads` when security matters
7. **Context pollution**: ACPX ndjson can pipe to external monitoring without entering Context; tmux capture-pane is zero-token

---

## 14. User Command Mapping

| User Says | What You Do |
|-----------|-------------|
| "Implement feature X for project Y" | Scenario A: understand requirement → create task → start agent |
| "Investigate this performance issue" | Scenario A: analyze problem → create investigation task |
| "Do these three tasks in parallel" | Scenario A × N (parallel named sessions) |
| "Fix issue #78" (optional) | Scenario A: fetch issue description |
| "Start a session for X" | Scenario B: interactive |
| "Tell <session> to do Y" | Scenario C: acpx prompt / tmux send-keys |
| "How is <session> doing?" | Scenario D: acpx sessions show / capture-pane |
| "Use Gemini for this task" | Scenario E: acpx --agent gemini / gemini Skill |
| "Create PR" | Scenario F |
| "Stop <session>" / "cleanup" | Scenario G |
| "status" | List all sessions + MEMORY.md in-flight tasks |
| "retry <task>" | Scenario G cleanup + Scenario A restart |


---
Source attribution: LeoYeAI
Original project: https://github.com/LeoYeAI/openclaw-master-skills/blob/e5199b56ae1ff72e141586c17695563486c46702/skills/conduxt/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2026 MyClaw.ai (LeoYeAI)

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: LeoYeAI
Original project: https://github.com/LeoYeAI/openclaw-master-skills/blob/e5199b56ae1ff72e141586c17695563486c46702/skills/conduxt/SKILL.md
Attribution basis: Source repository record

Fields of work: Development & Engineering, Product Management
Roles: Backend Developer, DevOps / SRE, ML / AI Engineer, Product Manager, Technical Product Manager
Specialties: API, Backend
Tools: Acpx, Tmux
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 06b3889508bd6814e072a8c8087f6abb1a3de4e6accc4bfb8a5b8ab83810f238