# 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

```bash
# Verify installation
opencode --version

# Check auth
opencode auth list
```

**Smoke test:**
```bash
opencode run 'Respond with exactly: OPENCODE_SMOKE_OK'
# Expected: OPENCODE_SMOKE_OK
```

---

## Usage Patterns

### One-Shot Tasks

```bash
# 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

```bash
# 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

```bash
opencode pr 42
```

Or in temporary clone:
```bash
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

```python
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:
```bash
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](https://opencode.ai)
- Hermes skill: `opencode` (autonomous-ai-agents/opencode/SKILL.md)