docs: add OpenCode usage & parallelization research note

docs/_index.md

@@ -0,0 +1,17 @@
+# Research Index
+
+Overview of research topics and notes.
+
+## Topics
+
+### AI Agents
+
+| Topic | Status | Last Updated |
+|-------|--------|--------------|
+| [OpenCode Usage & Parallelization](./opencode-usage.md) | Active | 2025-03-27 |
+
+### More topics...
+
+---
+
+*Auto-generated index. Update manually when adding new research notes.*

docs/opencode-usage.md

@@ -0,0 +1,147 @@
+# 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)