OpenCode CLI

Use OpenCode as an autonomous coding worker orchestrated by Hermes terminal/process tools. OpenCode is a provider-agnostic, open-source AI coding agent with a TUI and CLI.

When to Use

• User explicitly asks to use OpenCode
• You want an external coding agent to implement/refactor/review code
• You need long-running coding sessions with progress checks
• You want parallel task execution in isolated workdirs/worktrees

Prerequisites

• OpenCode installed:

  npm i -g opencode-ai@latest

  or

  brew install anomalyco/tap/opencode

• Auth configured:

  opencode auth login

  or set provider env vars (OPENROUTER_API_KEY, etc.)
• Verify:

  opencode auth list

  should show at least one provider
• Git repository for code tasks (recommended)

• pty=true

  for interactive TUI sessions

Binary Resolution (Important)

Shell environments may resolve different OpenCode binaries. If behavior differs between your terminal and Hermes, check:

terminal(command="which -a opencode")
terminal(command="opencode --version")

If needed, pin an explicit binary path:

terminal(command="$HOME/.opencode/bin/opencode run '...'", workdir="~/project", pty=true)

One-Shot Tasks

Use

opencode run

terminal(command="opencode run 'Add retry logic to API calls and update tests'", workdir="~/project")

Attach context files with

-f

terminal(command="opencode run 'Review this config for security issues' -f config.yaml -f .env.example", workdir="~/project")

Show model thinking with

--thinking

terminal(command="opencode run 'Debug why tests fail in CI' --thinking", workdir="~/project")

Force a specific model:

terminal(command="opencode run 'Refactor auth module' --model openrouter/anthropic/claude-sonnet-4", workdir="~/project")

Interactive Sessions (Background)

For iterative work requiring multiple exchanges, start the TUI in background:

terminal(command="opencode", workdir="~/project", background=true, pty=true)
# Returns session_id

# Send a 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>")

# Send follow-up input
process(action="submit", session_id="<id>", data="Now add error handling for token expiry")

# Exit cleanly — Ctrl+C
process(action="write", session_id="<id>", data="\x03")
# Or just kill the process
process(action="kill", session_id="<id>")

Important: Do NOT use

/exit

\x03

process(action="kill")

TUI Keybindings

Enter

Tab

Ctrl+P

Ctrl+X L

Ctrl+X M

Ctrl+X N

Ctrl+X E

Ctrl+C

Resuming Sessions

After exiting, OpenCode prints a session ID. Resume with:

terminal(command="opencode -c", workdir="~/project", background=true, pty=true)  # Continue last session
terminal(command="opencode -s ses_abc123", workdir="~/project", background=true, pty=true)  # Specific session

Common Flags

run 'prompt'

--continue

-c

--session <id>

-s

--agent <name>

--model provider/model

--format json

--file <path>

-f

--thinking

--variant <level>

--title <name>

--attach <url>

Procedure

1. Verify tool readiness:

   • terminal(command="opencode --version")

   • terminal(command="opencode auth list")

2. For bounded tasks, use

   opencode run '...'

   (no pty needed).
3. For iterative tasks, start

   opencode

   with

   background=true, pty=true

   .
4. Monitor long tasks with

   process(action="poll"|"log")

   .
5. If OpenCode asks for input, respond via

   process(action="submit", ...)

   .
6. Exit with

   process(action="write", data="\x03")

   or

   process(action="kill")

   .
7. Summarize file changes, test results, and next steps back to user.

PR Review Workflow

OpenCode has a built-in PR command:

terminal(command="opencode pr 42", workdir="~/project", pty=true)

Or review in a temporary clone for isolation:

terminal(command="REVIEW=$(mktemp -d) && git clone https://github.com/user/repo.git $REVIEW && cd $REVIEW && opencode run 'Review this PR vs main. Report bugs, security risks, test gaps, and style issues.' -f $(git diff origin/main --name-only | head -20 | tr '\n' ' ')", pty=true)

Parallel Work Pattern

Use separate workdirs/worktrees to avoid collisions:

terminal(command="opencode run 'Fix issue #101 and commit'", workdir="/tmp/issue-101", background=true, pty=true)
terminal(command="opencode run 'Add parser regression tests and commit'", workdir="/tmp/issue-102", background=true, pty=true)
process(action="list")

Session & Cost Management

List past sessions:

terminal(command="opencode session list")

Check token usage and costs:

terminal(command="opencode stats")
terminal(command="opencode stats --days 7 --models anthropic/claude-sonnet-4")

Pitfalls

• Interactive

  opencode

  (TUI) sessions require

  pty=true

  . The

  opencode run

  command does NOT need pty.

• /exit

  is NOT a valid command — it opens an agent selector. Use Ctrl+C to exit the TUI.
• PATH mismatch can select the wrong OpenCode binary/model config.
• If OpenCode appears stuck, inspect logs before killing:

  • process(action="log", session_id="<id>")

• Avoid sharing one working directory across parallel OpenCode sessions.
• Enter may need to be pressed twice to submit in the TUI (once to finalize text, once to send).

Verification

Smoke test:

terminal(command="opencode run 'Respond with exactly: OPENCODE_SMOKE_OK'")

Success criteria:

• Output includes

  OPENCODE_SMOKE_OK

• Command exits without provider/model errors
• For code tasks: expected files changed and tests pass

Rules

1. Prefer

   opencode run

   for one-shot automation — it's simpler and doesn't need pty.
2. Use interactive background mode only when iteration is needed.
3. Always scope OpenCode sessions to a single repo/workdir.
4. For long tasks, provide progress updates from

   process

   logs.
5. Report concrete outcomes (files changed, tests, remaining risks).
6. Exit interactive sessions with Ctrl+C or kill, never

   /exit

   .