kugetsu/docs/opencode-usage.md

OpenCode Usage & Parallelization

Date: 2025-03-27 Status: Active Topic: AI Agents / OpenCode

Overview

OpenCode is an open-source, provider-agnostic AI coding agent with a CLI/TUI. This note covers installation verification, usage patterns, and Hermes's parallelization capabilities with OpenCode.

---

Installation & Verification

Binary location: /home/shoko/.opencode/bin/opencode (v1.3.3)

Auth provider: MiniMax Coding Plan

# Verify installation
opencode --version

# Check auth
opencode auth list

Smoke test:

opencode run 'Respond with exactly: OPENCODE_SMOKE_OK'
# Expected: OPENCODE_SMOKE_OK

---

Usage Patterns

One-Shot Tasks

# Basic task with output
opencode run 'Add retry logic to API calls and update tests'

# Attach context files
opencode run 'Review this config for security issues' -f config.yaml -f .env.example

# Show model thinking
opencode run 'Debug why tests fail in CI' --thinking

# Force specific model
opencode run 'Refactor auth module' --model openrouter/anthropic/claude-sonnet-4

Interactive TUI Sessions

# Start background TUI
terminal(command="opencode", workdir="~/project", background=true, pty=true)

# Send prompt
process(action="submit", session_id="<id>", data="Implement OAuth refresh flow and add tests")

# Monitor progress
process(action="poll", session_id="<id>")
process(action="log", session_id="<id>")

# Exit (Ctrl+C)
process(action="write", session_id="<id>", data="\x03")
# Or kill
process(action="kill", session_id="<id>")

PR Review

opencode pr 42

Or in temporary clone:

REVIEW=$(mktemp -d) && git clone https://github.com/user/repo.git $REVIEW && \
cd $REVIEW && opencode run 'Review this PR vs main...'

---

Hermes Parallelization

Available Methods

Method	Max Parallel	Context Sharing	Best For
delegate_task	3 (schema hard limit)	No	Bounded independent tasks
terminal() calls	No hard cap	No	Fire-and-forget background work
process management	No hard cap	Via parent session	Long-running interactive sessions

delegate_task

delegate_task(tasks=[
  {"goal": "Fix issue #1", "context": "...", "workdir": "${KUGETSU_TEMP_DIR}/issue-1"},
  {"goal": "Fix issue #2", "context": "...", "workdir": "${KUGETSU_TEMP_DIR}/issue-2"},
  {"goal": "Fix issue #3", "context": "...", "workdir": "${KUGETSU_TEMP_DIR}/issue-3"},
], max_iterations=50)

Constraints:

• Cannot use: delegate_task, clarify, memory, send_message within subagents
• Tasks must be fully self-contained
• Exit with Ctrl+C or process(action="kill"), NOT /exit
• Note: Use KUGETSU_TEMP_DIR instead of /tmp since opencode blocks /tmp in headless mode

Terminal Parallel Calls

No hard cap. Fire multiple opencode run in parallel:

opencode run 'Fix issue #1' --workdir ${KUGETSU_TEMP_DIR}/issue-1 &
opencode run 'Fix issue #2' --workdir ${KUGETSU_TEMP_DIR}/issue-2 &
opencode run 'Fix issue #3' --workdir ${KUGETSU_TEMP_DIR}/issue-3 &

Schema Constraint

The 3-task limit on delegate_task is a hard constraint in the tool schema (maxItems: 3 on the tasks array). It cannot be changed at runtime. Workarounds:

1. Multiple sequential delegate_task calls — batch into groups of 3
2. Use terminal() with parallel opencode run — no schema cap
3. Request schema change — would need Hermes source modification

---

Tradeoffs at Scale

For N issues (e.g., 10):

Approach	Parallelism	Merge Conflict Risk	Coherence
Sequential opencode run xN	1x	Low	Easy
3x delegate_task batches	3x	Medium	Medium
Nx parallel terminal() calls	Nx	High	Low

Recommendation: Batch into 3-4 parallel streams using delegate_task or parallel terminal() calls. Each stream works in isolated workdir. Final review/merge phase required.

---

References

• OpenCode Official
• Hermes skill: opencode (autonomous-ai-agents/opencode/SKILL.md)