OpenCode Configuration Loop with Hermes Autonomous Agent

Hermes handles long-running autonomous tasks well, but its output often needs review, cleanup, and reconfiguration. OpenCode excels at configuration, multi-provider switching, and code review — but has no autonomous agent mode.

This pattern creates an iterative loop: OpenCode configures Hermes → Hermes runs autonomously → OpenCode reviews the output → adjusts the configuration → repeats.

Overview

The loop has four phases:

1. Configure — OpenCode writes or updates Hermes' task configuration (instructions, tools, constraints)
2. Run — Hermes executes the task autonomously, producing a result
3. Review — OpenCode examines the output for correctness, completeness, and quality
4. Adjust — OpenCode updates the configuration based on what went wrong, then the loop repeats

The key insight: Hermes is the worker, OpenCode is the manager. The manager doesn't do the work — it configures, reviews, and improves the worker's setup.

Key Features

• Separates configuration (OpenCode) from execution (Hermes) — each tool does what it's best at
• OpenCode's multi-provider capability means you can use different models for configuration vs review (e.g. Claude for review, DeepSeek for generating config updates)
• The iterative loop improves output quality across runs — later runs have better configuration
• Works for any task Hermes can handle: code generation, data processing, research, documentation
• The loop naturally converges: each iteration produces fewer issues for OpenCode to fix

Installation & Setup

Prerequisites

OpenCode:

npm install -g opencode-ai
opencode auth login

Run opencode auth login once for each provider you want to configure, such as Anthropic and DeepSeek.

Hermes Agent:

pip install hermes-agent
hermes setup

hermes setup runs the full configuration wizard. Use hermes model later to change the provider or model.

Task Configuration

OpenCode writes the task brief that Hermes receives. Keep it as a Markdown prompt file so both agents can read and revise it:

hermes-task.md

# Task: Refactor authentication module

Refactor the auth module to use JWT instead of session tokens.

## Constraints
- Maintain backward compatibility with the existing API.
- Add tests for all new code paths.
- Document any breaking changes.

## Tools
Use read_file, write_file, execute_command, and search_codebase.

## Review policy
Stop and report before committing. Do not push.

Run it as a one-shot task with hermes -z "$(cat hermes-task.md)". Hermes keeps its full toolset; -z only strips the interactive UI and returns the final response.

Available Tools/Resources

Configuration Example

OpenCode session: Review and Reconfigure

OpenCode reviews Hermes' output and updates the task brief for the next run:

# 1. Run the task and capture the final response
hermes -z "$(cat hermes-task.md)" > hermes-output.md

# 2. Analyze what went wrong (Claude model for high-quality review)
# OpenCode reads hermes-output.md and identifies issues:
# - JWT token refresh not implemented
# - Missing edge case tests
# - Documentation incomplete

# 3. Update the task brief (switch to DeepSeek for cheap brief generation)
# OpenCode edits hermes-task.md with new constraints:
# - Add token refresh implementation
# - Add edge case test templates
# - Add documentation sections needed

# 4. Re-run Hermes with the updated brief
hermes -z "$(cat hermes-task.md)" > hermes-output.md

When to use

• Tasks that need multiple iterations to get right
• When autonomous execution quality depends on good initial configuration
• When you want to optimize across cost tiers (Claude for review, DeepSeek for config)
• Tasks that are too complex for a single autonomous run but too repetitive to do manually

Common Use Cases

Code Generation & Refactoring

Hermes generates the initial implementation. OpenCode reviews for correctness, style, and edge cases. The config is updated and Hermes re-runs. Usually 2-3 iterations to completion.

Bug Fixing with Root Cause Analysis

OpenCode configures Hermes with bug reproduction steps and the codebase context. Hermes searches, identifies the root cause, and proposes a fix. OpenCode reviews the proposed fix for unintended side effects. Repeat until the fix is clean.

Documentation Generation

Hermes generates documentation from the codebase. OpenCode reviews for accuracy, completeness, and tone. The config is updated with examples of what good documentation looks like. Hermes re-generates. Converges in 1-2 iterations.

Best Practices

Security Considerations

• Hermes runs with the same shell permissions as the user. Limit its tool access with hermes tools to only what's needed.
• OpenCode should never share API keys or secrets with Hermes via config files.
• Review Hermes' file writes before committing — the loop improves quality but never fully trust autonomous output.

Performance Optimization

• Start with a narrow scope and expand. Hermes works better on focused tasks.
• Keep each one-shot run focused; split broad jobs into separate runs so a stalled run doesn't consume the whole budget.
• Use DeepSeek (OpenCode) for generating task-brief updates — it's 95% cheaper than Claude and the brief is simple enough.

Troubleshooting

Hermes gets stuck or loops

A one-shot run exits with code 2 when it fails or stops partway, including when it hits its iteration budget. If that happens repeatedly, the task is too broad — break it into smaller sub-tasks and narrow the brief.

OpenCode review finds the same issue across iterations

Update the constraints section in the config to explicitly forbid the recurring issue. Be specific — "avoid nested callbacks" works better than "write clean code."

Task brief changes don't improve output

The review pass isn't specific enough. Instead of "improve error handling," write "add try/catch blocks around all database operations with specific error messages."

Related Integrations

• Driving Gemini with Ralph Loops — Alternative pattern using Claude + Gemini instead of OpenCode + Hermes
• Claude Hooks + DeepSeek API — For automated sub-task generation using Claude hooks
• OpenCode Multi-Provider — The provider switching strategy that makes this pattern cost-effective

Sources

• OpenCode documentation
• OpenCode CLI
• hermes-agent on PyPI
• Hermes CLI commands