modbender acpx v4.0 - Agent Orchestrator
Enhanced CLI wrapper di atas acpx dengan fitur orchestration: parallel, health check, workflows.
⚠️ Warnings & Security Notes
| Item | Status | Description |
|---|---|---|
| Required Binary | ✅ | acpx (installed via npm) |
| Optional Binaries | ℹ️ | opencode, pi, kimi, kilo, codex, claude, gemini |
| File Write | ⚠️ | Agents write files to current directory |
| Install Command | ⚠️ | npm install -g acpx — verify package on npm/GitHub first |
| Credentials | ✅ | No credentials or env vars requested |
| Persistence | ✅ | always: false, autonomous invocation allowed |
Security Considerations
- Scope: This orchestrator spawns subagents and executes arbitrary tasks via CLI
- File Access: Agents can create/modify files in the working directory
- Review Tasks: Treat task files and agent commands as untrusted input unless reviewed
- Install Risk: npm packages can execute install scripts — prefer sandboxed installs
Quick Start
# Discover agents
acpx discover
# Health check
acpx health
# Run single agent
acpx run opencode "Fix bug"
# Run workflow
acpx workflow review
Commands
| Command | Description | Example |
|---|---|---|
discover |
List installed agents | acpx discover |
health |
Test all agents | acpx health |
run |
Run single agent | acpx run opencode "task" |
parallel |
Run agents simultaneously (independent tasks only) | acpx parallel tasks.txt [cwd] |
batch |
Run agents sequentially (for dependent tasks) | acpx batch tasks.txt [cwd] |
watch |
Watch agent status | acpx watch opencode |
kill |
Kill agent sessions | acpx kill opencode |
workflow |
Run preset workflow | acpx workflow review |
json |
Run with JSON output | acpx json opencode "task" | jq |
exec |
Direct acpx passthrough | acpx exec opencode "task" |
Workflows
| Workflow | Description |
|---|---|
review |
Code review dengan JSON output |
refactor |
Safe refactoring dengan diff |
test |
Generate pytest tests |
debug |
Deep investigation (600s timeout) |
Batch File Format
# tasks.txt
opencode exec 'Fix auth.py'
pi exec 'Create tests'
kimi --print --yolo --prompt 'Review changes'
acpx parallel tasks.txt [cwd] # Run parallel (INDEPENDENT tasks only!)
acpx batch tasks.txt [cwd] # Run sequential (for dependent tasks)
⚠️ Important:
- Agents write files to current directory by default
parallel= tasks run simultaneously → use for independent tasksbatch= tasks run one-by-one → use for dependent tasks- Use full paths or specify working directory as 2nd argument
Example tasks.txt:
# Task 1: Create file
opencode exec 'Create app.js with Express server'
# Task 2: Review file (depends on task 1)
kimi --print --yolo --prompt 'Review app.js'
Run with: acpx batch tasks.txt (sequential, task 2 waits for task 1)
Spawn via OpenClaw
// Health check
sessions_spawn(
task="acpx health",
label="health-check",
runtime="subagent",
mode="run"
)
// Run workflow
sessions_spawn(
task="acpx workflow review",
label="review",
runtime="subagent",
mode="run"
)
// Parallel tasks
sessions_spawn(
task="acpx parallel tasks.txt",
label="parallel-jobs",
runtime="subagent",
mode="run"
)
// JSON output
sessions_spawn(
task="acpx json opencode 'List functions'",
label="json-task",
runtime="subagent",
mode="run"
)
Helper Scripts
acpx- Main orchestrator CLIacpx-batch- Legacy sequential runneracpx-workflow- Legacy workflow presetsacpx-discover- Legacy discovery
Changelog
- v4.0.0 - Enhanced orchestrator: parallel, health check, workflows, json output
- v3.1.0 - Simple CLI wrapper
- v3.0.0 - Generic auto-discovery
- v2.0.0 - Async multi-agent patterns
- v1.0.0 - Initial wrapper