OpenCode ACP Skill v2.0

Control OpenCode directly via the Agent Client Protocol (ACP) with automatic recovery and stuck detection.

🆕 What's New in v2.0

Feature	Description
Auto-retry	Automatically retries on failure (max 3 attempts)
Stuck detection

Detects when OpenCode is not responding | | Lock cleanup | Automatically removes stale lock files | | Adaptive polling | Polls faster at start, slower when stable | | Health checks | Periodic checks that OpenCode is alive | | Configurable timeouts | Shorter timeouts with escalation | | Session recovery | Can recover from crashes mid-task |

---

Quick Reference

Action	How
Start OpenCode	INLINECODE0
Send message

process.write(sessionId, data: "<json-rpc>\n") | | Read response | process.poll(sessionId) - adaptive polling | | Health check | process.poll(sessionId, timeout: 5000) - only when no output >60s | | Stop OpenCode | process.kill(sessionId) + cleanup locks | | Clean locks | exec(command: "rm -f ~/.openclaw/agents/*/sessions/*.lock") | | List sessions | exec(command: "opencode session list", workdir: "...") | | Resume session | List sessions → session/load |

---

🚀 Quick Start (Simple)

For most use cases, use this simple workflow:

CODEBLOCK0

---

📁 Skill Files

File	Purpose
INLINECODE8	This file - main documentation
INLINECODE9

Default configuration (copy to config.json to customize) |
| templates.md | Prompt templates for common tasks |

---

⚙️ Configuration

Option 1: Use defaults

All defaults are built-in. No config file needed.

Option 2: Customize

Copy config.default.json to config.json in the same folder and modify:

CODEBLOCK1

Config structure:

{
  "timeouts": { "initialize": 10000, "prompt": {...} },
  "retry": { "maxAttempts": 3, "initialDelay": 2000 },
  "polling": { "initial": 1000, "active": 2000 },
  "healthCheck": { "noOutputThreshold": 60000 },
  "recovery": { "autoRecover": true },
  "mcpServers": { "default": [], "supabase": ["supabase"] }
}

---

Timeouts (Configurable)

Operation	Default	Max	When to increase
Initialize	10s	30s	Slow machine
Session new

10s | 30s | Large project |
| Prompt (simple) | 60s | 120s | Complex query |
| Prompt (complex) | 120s | 300s | Refactor, code gen |
| Health check | 5s | 10s | Network issues |

Retry Configuration

Setting	Default	Description
Max retries	3	How many times to retry on failure
Retry delay

2s | Initial delay between retries | | Backoff multiplier | 2 | Delay doubles each retry | | Max retry delay | 10s | Maximum delay between retries |

Adaptive Polling

Phase	Interval	Duration
Initial	1s	First 10s
Active

2s | 10s - 60s | | Stable | 3s | 60s - 120s | | Slow | 5s | 120s+ |

---

🔄 Automatic Recovery

Stuck Detection

OpenCode is considered "stuck" when:

• - No response after 2x expected timeout
• Health check fails 3 times in a row
• Process is still running but not responding to polls

Recovery Steps

When stuck is detected:

CODEBLOCK3

Lock Cleanup

Lock files can become stale when OpenCode crashes. Always clean up:

CODEBLOCK4

---

📋 Step-by-Step Workflow

Step 1: Pre-flight Check

Before starting, verify environment:

CODEBLOCK5

Step 2: Start OpenCode

CODEBLOCK6

Step 3: Initialize (with retry)

CODEBLOCK7

Retry logic:
CODEBLOCK8

Step 4: Create Session (with retry)

CODEBLOCK9

Same retry logic as initialize.

Step 5: Send Prompts (with adaptive polling)

CODEBLOCK10

Adaptive polling:
CODEBLOCK11

Step 6: Health Check (Smart - No Token Waste)

⚠️ Don't poll constantly - wastes tokens!

Only do health checks when:

1. 1. No output for >60s (possible stuck)
2. Approaching timeout (verify before declaring stuck)
3. Something looks wrong (partial errors, etc.)

DO NOT health check when:

• - OpenCode is actively generating output
• <60s since last output

CODEBLOCK12

Step 7: Cleanup

When done, always clean up:

CODEBLOCK13

---

🛠️ Error Handling

Common Errors and Solutions

Error	Detection	Solution
Process died	INLINECODE14 returns "No active session"	Restart OpenCode, resume session
Stuck (no response)

No response after 2x timeout | Cancel, kill, clean locks, restart | | Lock file exists | .lock file from previous run | Remove stale locks (>30min old) | | JSON parse error | Malformed response | Skip line, continue polling | | Timeout | elapsed >= maxWait | Check if stuck, retry or escalate | | Rate limited | HTTP 429 from OpenCode | Exponential backoff, max 10s |

Recovery Function

CODEBLOCK14

---

🔌 Session Management

Multiple Sessions

OpenCode supports multiple concurrent sessions. Track them:

CODEBLOCK15

Session Recovery

If OpenCode crashes mid-task:

CODEBLOCK16

---

📊 Monitoring

Health Metrics

Track these to detect problems early:

Metric	Healthy	Warning	Critical
Response time	<5s	5-15s	>15s
Polls without data

<10 | 10-30 | >30 |
| Lock file age | <5min | 5-30min | >30min |
| Consecutive errors | 0 | 1-2 | ≥3 |

Logging

Log important events for debugging:

CODEBLOCK17

---

🎯 Best Practices

DO:

• - ✅ Always clean up locks before starting
• ✅ Use adaptive polling (saves tokens)
• ✅ Implement retry logic (makes it robust)
• ✅ Track session state (enables recovery)
• ✅ Set appropriate timeouts per task type
• ✅ Kill and restart if stuck >2x timeout

DON'T:

• - ❌ Poll every 2s for 5 minutes (wastes tokens)
• ❌ Health check every 30s when output is active (wastes tokens)
• ❌ Ignore stuck processes (blocks future work)
• ❌ Leave lock files after crashes
• ❌ Use same timeout for all operations
• ❌ Skip health checks when no output for >60s (misses stuck detection)

---

📝 Example: Robust Implementation

CODEBLOCK18

---

🔧 Utility Functions

cleanupStaleLocks()

CODEBLOCK19

isStuck(sessionId)

CODEBLOCK20

getAdaptiveInterval(elapsedMs)

CODEBLOCK21

---

📝 Prompt Templates

---

📝 Prompt Templates

See templates.md for pre-built prompts for common tasks:

Category	Templates
Refactoring	Extract function, convert to TS, improve readability
Features

Add endpoint, add component, implement feature |
| Bug fixes | Debug and fix, TypeScript errors |
| Testing | Unit tests, integration tests |
| Documentation | JSDoc/TSDoc, README updates |
| Database | Migrations, RLS policies |
| Performance | Query optimization, bundle size |
| Security | Security audit |

Usage:

1. Read templates.md
2. Find appropriate template
3. Replace placeholders with your specifics
4. Send as prompt

---

📊 Metrics & Monitoring

Track these for health monitoring:

Metric	How to track	Healthy	Warning	Critical
Avg response time	Log timestamps	<30s	30-60s	>60s
Polls per request

Counter | <20 | 20-50 | >50 | | Retry rate | Retries/requests | <5% | 5-15% | >15% | | Stuck rate | Stucks/sessions | <1% | 1-5% | >5% | | Success rate | Completed/started | >95% | 85-95% | <85% |

Logging format:

CODEBLOCK23

Log levels:

• - ERROR - Failures, exceptions, stuck detected
• INLINECODE19 - Retries, slow responses, near-timeout
• INLINECODE20 - Start, complete, cleanup
• INLINECODE21 - Detailed output, updates received

---

📦 Skill Files

CODEBLOCK24

---

🚀 Helper Script (Recommended)

Use opencode-session.sh for automatic workflow:

CODEBLOCK25

Script options:

Option	Description
INLINECODE23	Project directory (required)
INLINECODE24

Prompt to send (required if no template) | | --template NAME | Use template from templates.md | | --timeout TYPE | simple (60s) \| medium (120s) \| complex (300s) | | --mcp SERVERS | MCP servers as JSON array | | --verbose | Enable debug logging | | --dry-run | Show JSON-RPC without executing | | --help | Show help |

What the script provides:

The script outputs a complete workflow with:

• - ✅ Pre-flight cleanup
• ✅ Exact JSON-RPC messages to send
• ✅ Retry logic hints
• ✅ Adaptive polling intervals
• ✅ Health check thresholds
• ✅ Cleanup commands

CYPHER should:

1. 1. Execute the script with options
2. Parse the output
3. Execute the steps in order
4. Log metrics at the end

---

Version 2.2.0 - Released 2026-03-05
Changes: Added opencode-session.sh helper script