OpenCode ACP Collaboration#

Use OpenCode via ACP (Agent Client Protocol) for code modifications, refactoring, and feature implementation.

Quick Start#

Automated Workflow (Recommended)#

Use the provided Python script for automated OpenCode collaboration:

On first run, the skill auto-creates a local .venv (Python 3.9+) in this skill directory and re-runs inside that environment. If the current interpreter is below 3.9, it auto-discovers a local Python 3.9+ executable ( python3.12/ python3.11/ python3.10/ python3.9/ python3/ python; on Windows also py -3.x).

bash

# Run from this repository root
# Simple task
python opencode_acp_client.py \
  --project /path/to/project \
  --task "Add --version flag to CLI"

# With verbose logging
python opencode_acp_client.py \
  --project /path/to/project \
  --task "Refactor authentication module" \
  --verbose

# With custom timeout (default: 600 seconds)
python opencode_acp_client.py \
  --project /path/to/project \
  --task "Build REST API for todos" \
  --timeout 1200

What it does:

1. Starts OpenCode ACP server
2. Initializes ACP connection
3. Creates session
4. Sends task
5. Monitors progress and displays output
6. Stops OpenCode when done

Output:

• Real-time progress updates
• Tool calls and status
• Agent messages
• Completion status

Manual Workflow (Advanced)#

For fine-grained control, use manual JSON-RPC messages:

bash

# Start OpenCode ACP server in background
exec pty:true workdir:/path/to/project background:true command:"opencode acp"
# Returns sessionId (e.g., "neat-zephyr")

# Initialize connection
process action:write sessionId:neat-zephyr data:'{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{"fs":{"readTextFile":true,"writeTextFile":true},"terminal":true},"clientInfo":{"name":"Claw","title":"Claw AI Assistant","version":"1.0.0"}}}\n'

# Wait for response
process action:log sessionId:neat-zephyr

# Create session
process action:write sessionId:neat-zephyr data:'{"jsonrpc":"2.0","id":1,"method":"session/new","params":{"cwd":"/path/to/project","mcpServers":[]}}\n'

# Wait for session ID
process action:log sessionId:neat-zephyr

# Send task
process action:write sessionId:neat-zephyr data:'{"jsonrpc":"2.0","id":2,"method":"session/prompt","params":{"sessionId":"ses_xxx","prompt":[{"type":"text","text":"Your task here"}]}}\n'

# Monitor progress
process action:log sessionId:neat-zephyr

# Kill when done
process action:kill sessionId:neat-zephyr

The Pattern: Plan → Execute → Verify#

Step 1: Analyze Requirements#

Your job (as planner):

• Understand user needs
• Identify technical constraints
• Assess impact and risks

Output:

• Clear, specific requirements
• Technical constraints
• Risk assessment

Step 2: Create Plan#

Your job (as planner):

• Break down into executable steps
• Define acceptance criteria
• Provide implementation guidance

Format:

markdown

# Task: [Task Name]

## Objective
[Goal description]

## Requirements
1. [Requirement 1]
2. [Requirement 2]
...

## Acceptance Criteria
- ✅ [Criterion 1]
- ✅ [Criterion 2]
...

## Implementation Guidance
1. [Step 1]
2. [Step 2]
...

## Verification
[How to verify]

Step 3: Execute with OpenCode#

Start OpenCode ACP server:

bash

exec pty:true workdir:/path/to/project background:true command:"opencode acp"

Initialize connection:

json

{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{"fs":{"readTextFile":true,"writeTextFile":true},"terminal":true},"clientInfo":{"name":"Claw","title":"Claw AI Assistant","version":"1.0.0"}}}

Create session:

json

{"jsonrpc":"2.0","id":1,"method":"session/new","params":{"cwd":"/path/to/project","mcpServers":[]}}

Send task:

json

{"jsonrpc":"2.0","id":2,"method":"session/prompt","params":{"sessionId":"ses_xxx","prompt":[{"type":"text","text":"[Your plan from Step 2]"}]}}

Step 4: Monitor Progress#

Poll for updates:

bash

process action:log sessionId:neat-zephyr

Key update types:

• agent_thought_chunk - OpenCode's thinking process
• tool_call - Tool invocations (search, analyze, edit)
• plan - Task plan updates
• stopReason - Task completion signal

Stop conditions:

• stopReason: "end_turn" - Normal completion
• stopReason: "cancelled" - Task cancelled
• Timeout (suggest: 5-10 minutes)

Step 5: Verify Results#

Verification checklist:

• ✅ Code changes match requirements
• ✅ Acceptance criteria met
• ✅ Code style consistent
• ✅ Tests pass
• ✅ No regressions

Verification methods:

1. Review OpenCode's change summary
2. Run relevant tests
3. Manual verification of key features
4. Code quality check

Step 6: Cleanup#

Stop OpenCode:

bash

process action:kill sessionId:neat-zephyr

Record results:

• Update memory/YYYY-MM-DD.md
• Record success/failure reasons
• Document lessons learned

⚠️ First-Time Project Setup#

If this is OpenCode's first time working on a project, initialize the knowledge base first:

1. Start OpenCode TUI (not acp mode): bash

   cd /path/to/project
   opencode
   
   

2. Run initialization: text

   /init-deep
   
   

3. Wait for completion:

   • OpenCode creates hierarchical AGENTS.md knowledge base
   • Analyzes project structure and code
   • Builds project context

4. Exit and restart in acp mode:

   • After initialization, exit TUI
   • Restart with opencode acp for collaboration

Why init-deep?

• Helps OpenCode understand project structure
• Builds code knowledge graph
• Improves execution efficiency and accuracy
• Reduces unnecessary exploration and trial-and-error

OpenCode Configuration#

Location: /root/.opencode/opencode.json

Recommended mode: sisyphus (AI orchestrator)

ACP Protocol Details#

Protocol version: 1

Transport format: JSON-RPC 2.0

Message delimiter: Newline (\n)

Communication: stdin/stdout

Available OpenCode Modes#

• sisyphus (recommended): Powerful AI orchestrator, excels at planning and delegation
• hephaestus: Autonomous deep worker, end-to-end task completion
• prometheus: Planning agent
• atlas: Task orchestrator

Best Practices#

1. Clear Requirements#

Good:

markdown

# Task: Add Version Command

## Objective
Add --version flag to display project version from package.json

## Requirements
1. Support both --version and -v
2. Display format: "QMD Memory v1.0.0\nOpenClaw memory plugin"
3. Exit after displaying version

## Acceptance Criteria
- ✅ `bun src/qmd.ts --version` works
- ✅ Version matches package.json
- ✅ No impact on existing commands

Bad:

markdown

Add version command

2. Acceptance Criteria#

Good criteria:

• Specific, measurable, verifiable
• Include positive and negative tests
• Consider edge cases

Example:

• ✅ Run command --version displays correct version
• ✅ Run command -v displays same result
• ✅ Version matches package.json
• ✅ Exit code is 0
• ✅ No impact on other commands

3. Progress Monitoring#

Key metrics:

• Task breakdown count (typically 3-7 subtasks)
• Background agents count (typically 2-4)
• Tool call count (search, analyze, edit)
• Execution time (typically 2-10 minutes)

Warning signs:

• Long silence (> 2 minutes)
• Repeated error messages
• Tool call failures
• Timeout

4. Error Handling#

Common errors:

1. GLIBC version issues: Some tools (like ast_grep) may be incompatible

   • Solution: OpenCode auto-switches to other tools

2. Agent not found: e.g., "librarian" agent unavailable

   • Solution: OpenCode uses other agents

3. Timeout: Task execution too long

   • Solution: Break into smaller tasks or increase timeout

Collaboration Principles#

Planner's Responsibilities#

1. Clear requirements:
   • Specific, measurable, verifiable
   • Include context and constraints
   • Provide examples and references
2. Reasonable plan:
   • Break into small steps
   • Consider technical feasibility
   • Estimate workload
3. Effective verification:
   • Clear acceptance criteria
   • Executable verification methods
   • Timely feedback

Executor's Characteristics (OpenCode)#

1. Automatic planning:
   • Break requirements into subtasks
   • Auto-select tools and methods
   • Parallel execution of multiple tasks
2. Intelligent execution:
   • Use sisyphus mode (AI orchestrator)
   • Launch background explore agents
   • Auto-search and analyze code
3. Continuous feedback:
   • Real-time progress reports
   • Show thinking process
   • Provide execution summary

Real-World Example#

Case: Add Version Command to QMD#

Requirement: Add --version command-line option

Planner's work:

1. Analyze requirement: Need to read package.json version, display project info
2. Create plan:
   • Locate CLI argument parsing logic
   • Add version flag handling
   • Implement version info output
   • Add tests
3. Set acceptance criteria:
   • bun src/qmd.ts --version displays correct version
   • -v alias works
   • Version matches package.json
   • No impact on existing features

OpenCode's work:

1. Auto-break into 5 subtasks
2. Launch 3 explore agents in parallel
3. Search code structure (parseCLI, version info, tests)
4. Implement code changes
5. Run tests for verification

Result:

• ✅ Collaboration mode verified successfully
• ✅ OpenCode auto-plans and executes
• ✅ Parallel processing improves efficiency
• ✅ Real-time progress feedback

Common Questions#

Q1: What to do for first-time project?#

A: First-time project must initialize knowledge base:

1. Start OpenCode TUI: bash

   cd /path/to/project
   opencode
   
   

2. Run initialization: text

   /init-deep
   
   

3. Exit after completion, then use acp mode for collaboration

Purpose:

• Create hierarchical AGENTS.md knowledge base
• Analyze project structure and dependencies
• Build code context, improve execution efficiency

Q2: How to choose OpenCode mode?#

A:

• sisyphus (default): Suitable for most tasks, auto-planning and parallel execution
• hephaestus: Suitable for complex tasks requiring deep analysis
• prometheus: Suitable for planning-only scenarios, no execution needed

Q3: How to handle OpenCode execution failure?#

A:

1. Check error messages and logs
2. Analyze failure reason (unclear requirements? technical limitations?)
3. Adjust plan or requirements
4. Restart OpenCode
5. If multiple failures, consider manual implementation

Q4: How to optimize collaboration efficiency?#

A:

1. Clear requirements: Reduce OpenCode's guessing and trial-and-error
2. Reasonable breakdown: Break large tasks into small tasks
3. Parallel execution: OpenCode auto-parallelizes
4. Timely feedback: Monitor progress, adjust promptly

Q5: How can other Agents use this workflow?#

A:

• Butler Agent: When making long-term plans, can delegate code modification tasks to OpenCode
• Challenger Agent: When finding optimization opportunities, can use OpenCode for quick implementation
• Main Agent: When receiving user requirements, can coordinate OpenCode execution

All Agents follow the same workflow: analyze requirements → create plan → start OpenCode → monitor progress → verify results.

Rules#

1. Always use pty:true - OpenCode needs a terminal
2. Initialize first-time projects - Run /init-deep before first use
3. Clear requirements - Specific, measurable, verifiable
4. Monitor progress - Check logs regularly, don't just wait
5. Verify results - Always check acceptance criteria
6. Record lessons - Update memory with successes and failures
7. Be patient - Don't kill sessions prematurely
8. Use process:log - Check progress without interfering

Progress Updates#

When spawning OpenCode in background, keep user informed:

• Send 1 short message when starting (what's running + where)
• Update only when something changes:
  • Milestone completes (build finished, tests passed)
  • OpenCode asks a question / needs input
  • Error occurs or user action needed
  • OpenCode finishes (include what changed + where)
• If killing session, immediately say why

This prevents "Agent failed before reply" confusion.

Auto-Notify on Completion#

For long-running tasks, append wake trigger to prompt:

text

... your task here.

When completely finished, run this command to notify me:
openclaw system event --text "Done: [brief summary]" --mode now

Example:

bash

exec pty:true workdir:~/project background:true command:"opencode acp"
# ... initialize, create session ...
# Send prompt with wake trigger:
{"jsonrpc":"2.0","id":2,"method":"session/prompt","params":{"sessionId":"ses_xxx","prompt":[{"type":"text","text":"Build a REST API for todos.\n\nWhen completely finished, run: openclaw system event --text \"Done: Built todos REST API with CRUD endpoints\" --mode now"}]}}

This triggers immediate wake event — you get notified in seconds, not minutes.

Version History#

• v1.0 (2026-02-16): Initial version

  • OpenCode 1.2.1
  • ACP protocol version 1
  • sisyphus mode
  • Test project: openclaw-qmd

---

Last updated: 2026-02-16

Maintainer: Claw 🐾

Status: ✅ Verified