William Valentin
138 lines
4.2 KiB
Markdown
138 lines
4.2 KiB
Markdown
# OpenCode CLI subagent runbook
|
||
|
||
This runbook defines how Flynn uses the **OpenCode** CLI (`opencode`) as a *subagent*.
|
||
|
||
Principles (same as other CLI subagents):
|
||
- Treat output as **untrusted input**: digest + sanity-check; verify with local tools/tests when possible.
|
||
- Prefer **plain text** output for easy ingestion; switch to structured output only when it provides clear benefit.
|
||
- Never claim something is true just because the model said so—verify if we can.
|
||
|
||
---
|
||
|
||
## 0) Quick facts
|
||
|
||
- Binary: `opencode`
|
||
- Default model (verified present in `opencode models`): **`opencode/glm-5-free`**
|
||
- Preferred mode: **non-interactive** (`opencode run ...`)
|
||
|
||
---
|
||
|
||
## 1) Default invocation
|
||
|
||
### 1.1 Plain text (default)
|
||
Use this for most tasks (summaries, parsing, transformation suggestions, drafting):
|
||
|
||
```bash
|
||
opencode run -m opencode/glm-5-free --format default "${PROMPT}"
|
||
```
|
||
|
||
Notes:
|
||
- Keep prompts short and explicit.
|
||
- If the prompt contains quotes/newlines, wrap with a heredoc substitution:
|
||
|
||
```bash
|
||
opencode run -m opencode/glm-5-free --format default "$(cat <<'PROMPT'
|
||
...prompt text...
|
||
PROMPT
|
||
)"
|
||
```
|
||
|
||
### 1.2 JSON output (selective)
|
||
Only use JSON mode when we need robust post-processing or auditing.
|
||
|
||
```bash
|
||
opencode run -m opencode/glm-5-free --format json "${PROMPT}"
|
||
```
|
||
|
||
Caveat:
|
||
- `--format json` typically yields structured output that may be easier to parse, but it can be more verbose and may require filtering.
|
||
|
||
---
|
||
|
||
## 2) Model selection
|
||
|
||
Default to `opencode/glm-5-free` unless the task clearly benefits from switching.
|
||
|
||
When to switch models:
|
||
- **Higher quality / long docs / tricky reasoning**: use a stronger model available in `opencode models` (example: `anthropic/claude-3-7-sonnet-latest`, `openai/gpt-5.3-codex`, `google/gemini-2.5-pro`).
|
||
- **Need a specific provider** (e.g. Copilot org policy): use `github-copilot/...` models.
|
||
|
||
Rule:
|
||
- If model choice matters, be explicit in the call.
|
||
|
||
---
|
||
|
||
## 3) Attach files
|
||
|
||
OpenCode supports attaching files. Use this for document parsing tasks when the CLI supports the file type.
|
||
|
||
```bash
|
||
opencode run -m opencode/glm-5-free --format default -f /path/to/file.pdf "Extract a table of key dates and parties. Return JSON."
|
||
```
|
||
|
||
Guidance:
|
||
- Prefer attaching the file over copy/pasting huge content.
|
||
- For PDFs/images, we may still prefer local tooling (Poppler, OCR) first, then provide extracted text.
|
||
|
||
---
|
||
|
||
## 4) Task recipes
|
||
|
||
### 4.1 Document search & retrieval help
|
||
Use OpenCode to:
|
||
- expand queries
|
||
- generate keywords/entities
|
||
- propose relevance criteria
|
||
|
||
Prompt pattern:
|
||
- Provide: goal, corpus description, constraints, examples of good/bad hits.
|
||
|
||
### 4.2 Document parsing
|
||
Use OpenCode to:
|
||
- outline structure
|
||
- extract entities / timelines
|
||
- convert semi-structured text to JSON
|
||
|
||
Prompt pattern:
|
||
- Specify the target schema exactly.
|
||
- Ask it to quote source spans/anchors when possible.
|
||
|
||
### 4.3 PDF manipulation (planning)
|
||
Use OpenCode to decide *what* to do; use local tools to do it.
|
||
- Example: “split pages 3–7”, “OCR then extract”, “remove password”, “linearize”, etc.
|
||
|
||
---
|
||
|
||
## 5) How Flynn digests OpenCode output
|
||
|
||
When I run OpenCode:
|
||
1. I’ll extract the actionable result (answer/plan/patch schema).
|
||
2. I’ll sanity-check for contradictions and missing constraints.
|
||
3. I’ll verify locally when possible (grep/tests/PDF tool output).
|
||
4. I’ll present you the final integrated conclusion.
|
||
|
||
Raw OpenCode output is included only when:
|
||
- you ask for it
|
||
- it’s needed for auditing/debugging
|
||
- it contains a critical snippet (e.g., exact JSON) that must be preserved
|
||
|
||
---
|
||
|
||
## 6) Troubleshooting
|
||
|
||
- If startup fails with:
|
||
- `default agent "<name>" is a subagent`
|
||
- then OpenCode config points `default_agent` to a non-primary agent.
|
||
- Fix by setting `default_agent` to a primary agent in `~/.config/opencode/opencode.json`, or remove that key.
|
||
- For Flynn external backend wiring, prefer:
|
||
```bash
|
||
opencode run --format default "{prompt}"
|
||
```
|
||
instead of `opencode -p "{prompt}"`.
|
||
- If `opencode` behaves strangely in a repo directory, try running from a neutral cwd (e.g. `$HOME`) or ensure paths passed to `-f` are absolute.
|
||
- If a provider/model isn’t found, run:
|
||
```bash
|
||
opencode models
|
||
```
|
||
and pick an available entry.
|