flynn/docs/runbooks/OPENCODE_CLI_SUBAGENT.md

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):

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:

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.

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.

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:

  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:

  opencode models
  

  and pick an available entry.