OpenCode CLI: Autonomous Coding Agent Orchestrated by Hermes Agent

OpenCode is an open-source, provider-agnostic AI coding agent with a terminal UI and CLI. When you need to delegate a coding task to an external agent, you can hand it off to OpenCode through Hermes Agent's terminal and process tools. This guide covers everything from one-shot commands to interactive sessions, PR reviews, and parallel work patterns.

What it does

OpenCode acts as an autonomous coding worker. You give it a task, and it writes code, refactors files, runs tests, and reports back. It works with any provider (OpenRouter, Anthropic, OpenAI, etc.) and can run in two modes: a bounded one-shot mode that exits after completing a single task, and an interactive TUI mode that lets you iterate with follow-up prompts. Hermes Agent orchestrates both modes through its terminal and process actions.

Reach for OpenCode when you want to offload a coding task to a dedicated agent, especially for long-running sessions where you want progress checks, or when you need to run multiple coding tasks in parallel in isolated directories.

Before you start

• Install OpenCode: npm i -g opencode-ai@latest or brew install anomalyco/tap/opencode
• Configure authentication: opencode auth login or set provider environment variables (e.g., OPENROUTER_API_KEY)
• Verify: opencode auth list should show at least one provider
• Have a Git repository ready for code tasks (recommended)
• For interactive TUI sessions, set pty=true in the terminal action

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="<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, 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

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="")

• 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.

When not to use it

OpenCode is a coding agent. If your task does not involve writing, reviewing, or refactoring code, another skill may be more appropriate. The source does not list specific alternatives, but the related skills section points to claude-code, codex, and hermes-agent as other options.

Limits and gotchas

• Interactive sessions require pty=true; forgetting this will cause the TUI to fail.
• The /exit command does not work as expected, it opens an agent selector instead of exiting.
• PATH resolution can pick up a different OpenCode binary than expected, especially if you have multiple installations.
• If OpenCode hangs, check its logs with process(action="log") before killing it.
• Running multiple OpenCode sessions in the same working directory can cause file conflicts.
• In the TUI, you may need to press Enter twice to submit a message.

What pairs with this

OpenCode is one of several coding-agent skills bundled with Hermes Agent. The source lists claude-code, codex, and hermes-agent as related skills. You might use OpenCode when you want a provider-agnostic agent, and switch to another skill when you need a specific model or workflow.