opencode-acp

Collaborate with OpenCode via ACP protocol for code modifications, refactoring, and feature implementation.

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).

# 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:

# 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:

# 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:

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

Initialize connection:

{"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:

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

Send task:

{"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:

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:

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):

   cd /path/to/project
   opencode
   

2. Run initialization:

   /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:

# 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:

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:

   cd /path/to/project
   opencode
   

2. Run initialization:

   /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:

... your task here.

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

Example:

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