148 lines
3.9 KiB
Markdown
148 lines
3.9 KiB
Markdown
# 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": "/tmp/issue-1"},
|
|
{"goal": "Fix issue #2", "context": "...", "workdir": "/tmp/issue-2"},
|
|
{"goal": "Fix issue #3", "context": "...", "workdir": "/tmp/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`
|
|
|
|
### Terminal Parallel Calls
|
|
|
|
No hard cap. Fire multiple `opencode run` in parallel:
|
|
```bash
|
|
opencode run 'Fix issue #1' --workdir /tmp/issue-1 &
|
|
opencode run 'Fix issue #2' --workdir /tmp/issue-2 &
|
|
opencode run 'Fix issue #3' --workdir /tmp/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)
|