OpenCode Integration Practice: Architectural Evolution from Standalone Process to Shared Runtime

This article shares the complete practice of HagiCode integrating the OpenCode AI assistant, including key design decisions during the architectural evolution process, pitfalls encountered, and final solutions.

Background

OpenCode is an open-source AI coding assistant project hosted on GitHub. For a monorepo project like HagiCode, integrating OpenCode as a supported AI Provider means it can be used as a backend model for proposal generation, code editing, and workflow execution.

However, this integration process didn't go as smoothly as imagined. Early on, there were two separate proposals: one planned to create a C# SDK, which was later abandoned—not really a loss; another for repository-level integration did persist. As OpenCode entered the formal session pipeline, we encountered a series of issues like session management and error recovery—after all, what must come will come.

More troublesome was that the initially designed "standalone process per session" model exposed high resource overhead issues in actual operation, forcing a refactor to a "system-level shared runtime" model. We also stepped into the 400 BadRequest pit—reusing external endpoints lacking context causing request failures. It's all tears, really.

This article is just organizing these pitfalls and design decisions to provide reference for projects that need to integrate OpenCode in the future. After all, beautiful things or people don't necessarily need to be possessed—as long as she remains beautiful, just watching her beauty quietly is enough... Technical sharing is the same.

About HagiCode

The solution shared in this article comes from our practical experience in the HagiCode project. HagiCode is an AI-based code assistant project. During development, we needed to integrate multiple AI Providers, and OpenCode is one of them. The architectural evolution process shared below are all real experiences from our actual project—stepping in pits and optimizing them. No choice but to fill the pits we stepped in.

Technical Architecture

Overall Layered Design

HagiCode's OpenCode integration architecture is divided into five layers, each with clear responsibilities:

1. Repository Integration Layer

Register the OpenCode repository through the MonoSpecs configuration system (.hagicode/monospecs.yaml). There's a choice here: submodule or plain Git repository? We chose the latter, managing cloning and synchronization through a unified scripts/clone-repos.mjs script. This is more flexible and avoids the permission and collaboration issues brought by submodules—after all, no one wants to see that error screen, but no choice.

2. Provider Layer

OpenCodeCliProvider implements the IAIProvider interface, which is the standard abstraction layer for interfacing with external AI services. The initial proposal wanted "standalone process per session," but actual operation revealed resource overhead was too high, ultimately changing to shared runtime mode, managing system-level runtime lifecycle through OpenCodeRuntimeCoordinator. It's nothing, really—the idea was beautiful, reality is cruel.

3. Runtime Management Layer

OpenCodeRuntimeCoordinator is the core of the entire architecture, responsible for runtime startup, health checks, and失效重建. It uses HagiCode.Libs.Providers.OpenCode as the HTTP client foundation, encapsulating all interactions with the OpenCode runtime. Like that winter night, the bamboo outside the window remained the same as yesterday, lacking the response to her—she still liked looking out the window—runtime is the same, needing someone to silently guard it.

4. Session Persistence Layer

Using SQLite database (opencode-session-bindings-v2.db) to persist the mapping of CessionId to OpenCode SessionId. This design is critical, supporting session recovery and restart, avoiding creating new sessions each time. After all, memory—sometimes forgetting is better, but in the program world, having no memory really doesn't work.

5. Error Recovery Layer

ProviderErrorAutoRetryCoordinator provides automatic retry mechanism,配合 OpenCodeRetryableTerminalFailureClassifier to classify errors—which can be retried, which should fail directly. This layer greatly improves system robustness. Actually nothing much, just letting the system be like a person—fall down and get up again.

Key Data Flow

When an AI request comes in, the data flow goes like this:

1. Request first reaches OpenCodeCliProvider
2. Provider requests runtime from OpenCodeRuntimeCoordinator
3. Coordinator checks if there's an available runtime, if not starts a new one
4. Query or create session binding through CessionId
5. Use bound SessionId to call OpenCode API
6. If error occurs, decide whether to retry based on error type

This process looks simple, but every step has had pitfalls. Does this have meaning? Perhaps, but we've stepped in them all... Also figured it out, stepping in pits is itself part of growth.

Key Design Decisions

From Standalone Process to Shared Runtime

The initial opencode-csharp-sdk proposal adopted a "standalone process per session" model. The idea was beautiful: good isolation, one process crash doesn't affect other sessions. But reality is cruel:

• High resource overhead: each process needs to load runtime, memory usage rises straight up
• Slow startup: frequent creation and destruction of processes, overhead can't be ignored
• Complex management: process lifecycle management is itself a troublesome matter

Ultimately we changed to "system-level shared runtime" mode. All sessions reuse the same runtime process, distinguishing different sessions through session id. This change reduced resource usage by an order of magnitude and significantly improved response speed. Actually nothing much, just changing "one person enjoying alone" to "everyone using together."

Self-Managed Endpoint vs External BaseUri

Early on we encountered a weird 400 BadRequest problem. Investigation revealed it was because we reused an external BaseUrl but lacked necessary context information. OpenCode's runtime is stateful—directly using an external endpoint is equivalent to context loss—like a person without memory, at a loss.

The solution is simple: maintain self-managed runtime, don't depend on external endpoints. Leave BaseUri empty in configuration file, let the system manage runtime lifecycle itself.

AI:
  OpenCode:
    Enabled: true
    ExecutablePath: "opencode"
    BaseUri: null  # Leave empty, use self-managed runtime
    Model: "anthropic/claude-sonnet-4-20250514"

This configuration change looks inconspicuous, but solved the most headache-inducing problem at the time. After all, sometimes the answer is right before our eyes, we just took too many detours.

Session Binding Strategy

Session binding is another key design. We use CessionId as binding key, supporting three modes:

• started: New session, create new OpenCode SessionId
• resumed: Resume existing session, read binding from database
• restarted: Restart session, create new SessionId but preserve history

This design makes session management very flexible—users can resume previous conversations at any time, and the system can automatically rebuild bindings after runtime restart. After all, memory—sometimes want to forget but can't, sometimes want to remember but can't... Memory in the program world is quite reliable.

Implementation Plan

1. Repository Integration

Register OpenCode repository in .hagicode/monospecs.yaml:

repositories:
  - path: "repos/opencode"
    url: "https://github.com/anomalyco/opencode.git"
    displayName: "OpenCode"
    icon: "⌨️"

Then run the clone script:

node scripts/clone-repos.mjs

This pulls the OpenCode source code locally, and it can be updated at any time later. Actually quite simple, as long as there are no errors...

2. Provider Configuration

Configure OpenCode provider in appsettings.yml:

AI:
  OpenCode:
    Enabled: true
    ExecutablePath: "opencode"
    BaseUri: null
    Model: "anthropic/claude-sonnet-4-20250514"
    RequestTimeoutSeconds: 300
    StartupTimeoutSeconds: 60

Several key parameters:

• RequestTimeoutSeconds: Timeout for single request, default 5 minutes—after all, waiting too long is quite torturous
• StartupTimeoutSeconds: Runtime startup timeout, giving a full 1 minute

3. Provider Restoration

Bring OpenCode back into the AI Provider system:

• Restore OpenCodeCli in AIProviderType enum
• Restore creation logic in AIProviderFactory
• ExecutorGrainFactory routes OpenCodeCli to dedicated grain

These changes make OpenCode an equally-treated AI Provider, not a special case. Actually everyone is the same, nothing special or not special.

4. Runtime Management Code Example

// Get runtime through OpenCodeRuntimeCoordinator
var runtime = await _runtimeCoordinator.GetRuntimeAsync(
    _settings,
    request.WorkingDirectory,
    cancellationToken);

// Create or resume session
var session = await ResolveSessionAsync(runtime, request, cancellationToken);

// Send prompt
var response = await session.Runtime.Client.PromptAsync(
    session.SessionId,
    promptRequest,
    cancellationToken);

This code looks very concise, but behind it does a lot of work: runtime startup, health checks, session binding query and creation. Like many things,表面上看不出什么，behind it all are stories.

5. Error Recovery Mechanism

// Detect retryable errors and rebuild runtime
if (ShouldRetryWithFreshRuntime(ex, cancellationToken))
{
    await _runtimeCoordinator.InvalidateAsync(runtime, ...);
    var recoveredRuntime = await ResolveRuntimeAsync(request, cancellationToken);
    // Retry with new runtime
}

Automatic retry mechanism greatly improves system robustness—network jitter, runtime occasional crashes can all automatically recover. Actually life is the same, fall down and get up, nothing big... Programs are much stronger than people.

Practice Guide

Key Configuration Quick Reference

Configuration	Default	Description
Enabled	true	Whether to enable OpenCode provider
ExecutablePath	"opencode"	OpenCode executable path
BaseUri	null	External endpoint (recommended to leave empty)
Model	-	Default model
RequestTimeoutSeconds	300	Request timeout
StartupTimeoutSeconds	60	Runtime startup timeout

Session Binding Database Structure

CREATE TABLE IF NOT EXISTS OpenCodeSessionBindings (
    BindingKey TEXT NOT NULL PRIMARY KEY,
    OpenCodeSessionId TEXT NOT NULL,
    CreatedAtUtc TEXT NOT NULL,
    UpdatedAtUtc TEXT NOT NULL
);

Bindings are retained for 30 days, automatically cleaned after expiration. This design both ensures session recovery capability and avoids unlimited data growth. After all, everything has an expiration, expired then clean up, it's also a form of letting go...

Common Issues and Solutions

1. 400 BadRequest Error

Check BaseUri configuration, recommend leaving empty to use self-managed runtime. If must use external endpoint, ensure context is complete. Actually most times, the problem lies in "taking for granted."

2. Session Cannot Resume

Confirm whether CessionId is correctly passed, check if corresponding binding record exists in database. Like searching for memory, there must be clues.

3. Model Selection Issue

Supports two formats: provider/model (like anthropic/claude-sonnet-4) and no-provider format (like claude-sonnet-4). All roads lead to Rome, just some roads are easier to walk, some roads slightly more winding.

4. Tool Name Mismatch

Tool names are automatically normalized, removing content after parentheses and colons. For example read(path) becomes read, pay attention when calling. These details aren't much, just easily overlooked.

5. Auto Retry Not Working

Check if error classifier correctly identifies retryable errors. By default, network errors, runtime failures etc. automatically retry up to 3 times. After all, trying a few more times doesn't hurt, might just work.

Related Code Paths

• Provider: repos/hagicode-core/src/PCode.ClaudeHelper/AI/Providers/OpenCodeCliProvider.cs
• Runtime Coordinator: repos/hagicode-core/src/PCode.ClaudeHelper/AI/Providers/OpenCodeRuntimeCoordinator.cs
• Configuration: repos/hagicode-core/src/PCode.ClaudeHelper/AI/Configuration/OpenCodeSettings.cs
• Proposal Archive: openspec/changes/archive/2026-03-*opencode*/

Summary

HagiCode's process of integrating OpenCode is actually a continuous process of stepping in pits and optimizing. From the initial standalone process mode to shared runtime, from reusing external endpoints to self-managed runtime, every architecture adjustment is driven by actual needs. Actually nothing much, just didn't miss any pit that should be stepped in.

There are three core experiences:

1. Resource sharing is important: Don't blindly pursue isolation, shared runtime can significantly reduce resource overhead—sometimes one person enjoying alone isn't as good as everyone using together
2. Be careful with state management: Stateful services should be self-managed, don't depend on external endpoints—after all, your own affairs are best done yourself
3. Error recovery is essential: Automatic retry mechanism can take system robustness up a level—fall down and get up, nothing big

This solution now runs stably in HagiCode, supporting session recovery, automatic retry, runtime rebuild and other functions. If your project also needs to integrate OpenCode, hope these experiences can help you walk fewer detours. After all... only after walking detours do you know where the shortcut is, sometimes knowing it is of no use.

References

• OpenCode GitHub Repository
• HagiCode GitHub Repository
• HagiCode Official Site: hagicode.com
• HagiCode Installation Guide: docs.hagicode.com/installation/docker-compose
• HagiCode Desktop: hagicode.com/desktop/
• Official Version Demo Video: www.bilibili.com/video/BV1z4oWB3EpY/