Documentation
¶
Overview ¶
Package opencode implements a genai provider backed by the OpenCode CLI.
Instead of making HTTP requests directly, it launches `opencode acp` as a subprocess and communicates over stdin/stdout using the ACP (Agent Client Protocol) JSON-RPC 2.0 protocol.
See https://opencode.ai for OpenCode documentation and https://agentclientprotocol.com for the ACP specification.
Protocol ¶
The provider performs a JSON-RPC handshake (initialize → session/new) on each call, then sends a session/prompt request and reads session/update notifications until the session/prompt response arrives.
Session / multi-turn ¶
Each GenSync or GenStream call launches a fresh subprocess. The session ID is always returned inside Reply.Opaque["session_id"]. When the message history contains a previous session ID, it is automatically picked up: session/load is used instead of session/new and only the last user message is sent.
Example ¶
package main
import (
"context"
"fmt"
"log"
"github.com/maruel/genai"
"github.com/maruel/genai/providers/opencode"
)
func main() {
c, err := opencode.New(context.Background(), genai.ProviderOptionModel("opencode/big-pickle"))
if c != nil {
defer func() {
if err := c.Close(); err != nil {
log.Printf("Close: %v", err)
}
}()
}
if err != nil {
log.Print(err)
return
}
res, err := c.GenSync(
context.Background(),
genai.Messages{genai.NewTextMessage("Say hello")},
genai.EffortXHigh,
)
if err != nil {
log.Print(err)
return
}
fmt.Println(res.Replies[0].Text)
}
Output:
Index ¶
- Constants
- func Scoreboard() scoreboard.Score
- type Client
- func (c *Client) Capabilities() genai.ProviderCapabilities
- func (c *Client) Close() error
- func (c *Client) GenStream(ctx context.Context, msgs genai.Messages, opts ...genai.GenOption) (iter.Seq[genai.Reply], func() (genai.Result, error))
- func (c *Client) GenSync(ctx context.Context, msgs genai.Messages, opts ...genai.GenOption) (r genai.Result, err error)
- func (c *Client) HTTPClient() *http.Client
- func (c *Client) ListModels(ctx context.Context) ([]genai.Model, error)
- func (c *Client) ModelID() string
- func (c *Client) Name() string
- func (c *Client) OutputModalities() genai.Modalities
- func (c *Client) Ping(ctx context.Context) error
- func (c *Client) Scoreboard() scoreboard.Score
- type Effort
- type GenOption
- type Mode
- type ProviderOption
Examples ¶
Constants ¶
const ( ConfigOptionEffort = acp.ConfigOptionID("effort") ConfigOptionMode = acp.ConfigOptionID("mode") )
Session configuration option IDs exposed by OpenCode.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Client ¶
type Client struct {
base.NotImplemented
// contains filtered or unexported fields
}
Client is a genai provider that delegates to the local `opencode` CLI.
func New ¶
New creates a Client for the `opencode` CLI.
The binary is located lazily on the first call to GenSync, GenStream, or Ping, so New succeeds even when the CLI is not installed.
Supported ProviderOptions:
- genai.ProviderOptionModel — model ID (e.g. "opencode/big-pickle"). genai.ModelCheap, genai.ModelGood, and genai.ModelSOTA are rejected.
- *ProviderOption — process settings.
- genai.ProviderOptionStarterWrapper — intercepts subprocess creation.
func (*Client) Capabilities ¶
func (c *Client) Capabilities() genai.ProviderCapabilities
Capabilities implements genai.Provider.
func (*Client) GenStream ¶
func (c *Client) GenStream(ctx context.Context, msgs genai.Messages, opts ...genai.GenOption) (iter.Seq[genai.Reply], func() (genai.Result, error))
GenStream implements genai.Provider.
func (*Client) GenSync ¶
func (c *Client) GenSync(ctx context.Context, msgs genai.Messages, opts ...genai.GenOption) (r genai.Result, err error)
GenSync implements genai.Provider.
func (*Client) HTTPClient ¶
HTTPClient implements genai.Provider. The CLI provider does not use HTTP.
func (*Client) ListModels ¶
ListModels implements genai.Provider by querying the OpenCode ACP server's available models. It launches a subprocess, performs the handshake, and returns the model list from session/new.
func (*Client) OutputModalities ¶
func (c *Client) OutputModalities() genai.Modalities
OutputModalities implements genai.Provider.
func (*Client) Scoreboard ¶
func (c *Client) Scoreboard() scoreboard.Score
Scoreboard implements genai.Provider.
type Effort ¶ added in v0.7.1
type Effort string
Effort is an OpenCode reasoning-effort value serialized in the ACP effort configuration option.
Availability is provider- and model-specific. The provider validates it against the effort values returned by the ACP session.
const ( EffortDefault Effort = "default" EffortNone Effort = "none" EffortMinimal Effort = "minimal" EffortLow Effort = "low" EffortMedium Effort = "medium" EffortHigh Effort = "high" EffortXHigh Effort = "xhigh" EffortMax Effort = "max" )
Reasoning effort levels supported by OpenCode model variants.
type GenOption ¶ added in v0.7.1
type GenOption struct {
// Mode selects an OpenCode session mode returned by ACP. An empty value
// leaves OpenCode's current mode intact.
Mode Mode
// contains filtered or unexported fields
}
GenOption configures one prompt of a running opencode session.
type Mode ¶ added in v0.7.1
type Mode string
Mode is an OpenCode session-mode value serialized in the ACP mode configuration option.
type ProviderOption ¶ added in v0.9.0
type ProviderOption struct {
// DangerouslySkipPermissions approves every permission request the agent
// makes, such as file edits and shell commands.
DangerouslySkipPermissions bool
// ExtraArgs are appended to the `opencode acp` command line.
ExtraArgs []string
// contains filtered or unexported fields
}
ProviderOption configures the opencode process. It implements genai.ProviderOption.
All fields are opt-in. By default the provider rejects every permission request the agent makes.
func (*ProviderOption) Validate ¶ added in v0.9.0
func (p *ProviderOption) Validate() error
Validate implements genai.ProviderOption.
Source Files