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 for bounded, non-interactive tasks:

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="", data="Implement OAuth refresh flow and add tests")
Monitor progress

process(action="poll", session_id="")
process(action="log", session_id="")
Send follow-up input

process(action="submit", session_id="", data="Now add error handling for token expiry")
Exit cleanly — Ctrl+C

process(action="write", session_id="", data="\x03")
Or just kill the process

process(action="kill", session_id="")

Important: Do NOT use /exit — it is not a valid OpenCode command and will open an agent selector dialog instead. Use Ctrl+C (\x03) or process(action="kill") to exit.

TUI Keybindings

| Key | Action |
|-----|--------|
| Enter | Submit message (press twice if needed) |
| Tab | Switch between agents (build/plan) |
| Ctrl+P | Open command palette |
| Ctrl+X L | Switch session |
| Ctrl+X M | Switch model |
| Ctrl+X N | New session |
| Ctrl+X E | Open editor |
| Ctrl+C | Exit OpenCode |

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

| Flag | Use |
|------|-----|
| run 'prompt' | One-shot execution and exit |
| --continue / -c | Continue the last OpenCode session |
| --session / -s | Continue a specific session |
| --agent | Choose OpenCode agent (build or plan) |
| --model provider/model | Force specific model |
| --format json | Machine-readable output/events |
| --file / -f | Attach file(s) to the message |
| --thinking | Show model thinking blocks |
| --variant | Reasoning effort (high, max, minimal) |
| --title | Name the session |
| --attach | Connect to a running opencode server |

Procedure

• Verify tool readiness:

• For bounded tasks, use opencode run '...' (no pty needed).
• For iterative tasks, start opencode with background=true, pty=true.
• Monitor long tasks with process(action="poll"|"log").
• If OpenCode asks for input, respond via process(action="submit", ...).
• Exit with process(action="write", data="\x03") or process(action="kill").
• 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")

oh-my-openagent (오마이오픈코드) 동시성 리밋

oh-my-openagent는 에이전트를 병렬로 실행하는데, 이로 인해 오후에 ZAI/GLM 모델 동시성 리밋에 걸려 사용 불가해지는 문제가 발생할 수 있습니다.

원인

• oh-my-openagent가 background_task로 병렬 에이전트를 실행하면 모델 API 동시성이 초과됨
• Claude Code는 병렬 에이전트를 사용하지 않아 같은 문제가 발생하지 않음

해결책

• oh-my-openagent 설정에서 병렬 에이전트 수 제한 — background_task 관련 설정 확인
• 프로바이더 분산 — geminicli2api 등을 사용해 ZAI 단일 의존에서 벗어나기
• 오후에는 Claude Code로 전환 — 리밋 시간대만 우회
• 모델 다변화 — GLM 5.1/5/4.5/4.6v를 골고루 사용하도록 설정 (이미 적용 중)

참고

• geminicli2api 포스팅: sigco.tistory.com/51
• 주인님이 오후 리밋 문제를 겪은 시기: 2026-04-11부터 (3주간 oh-my-openagent 사용 후)

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:

• 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).
• oh-my-openagent 동시성 리밋: 오후에 ZAI 모델 리밋 걸리면 병렬 에이전트 수를 줄이거나 프로바이더를 분산하세요.

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

• Prefer opencode run for one-shot automation — it's simpler and doesn't need pty.
• Use interactive background mode only when iteration is needed.
• Always scope OpenCode sessions to a single repo/workdir.
• For long tasks, provide progress updates from process logs.
• Report concrete outcomes (files changed, tests, remaining risks).
• Exit interactive sessions with Ctrl+C or kill, never /exit.