opencodeclient

README

opencode-client

Go client library for the opencode-serve HTTP REST API.

import "github.com/kirill-scherba/opencode-client"

Documentation

• docs/CONTEXT.md — project overview and API reference
• docs/DESIGN.md — architecture decisions
• docs/STATUS.md — progress and known issues

Usage

package main

import (
    "log"

    opencodeclient "github.com/kirill-scherba/opencode-client"
)

func main() {
    c := opencodeclient.New("http://127.0.0.1:7709", 120*time.Second)

    sess, err := c.CreateSession("my-session", "svetik", "deepseek/deepseek-v4-flash", "/tmp", nil)
    if err != nil {
        log.Fatal(err)
    }

    // Agent and model are inherited from the session.
    reply, err := c.SendMessage(sess, "Hello, opencode!")
    if err != nil {
        log.Fatal(err)
    }
    log.Println(reply)

    // Override agent for this specific message.
    reply, err = c.SendMessage(sess, "Review this code", opencodeclient.MessageOptions{Agent: "guard"})
    if err != nil {
        log.Fatal(err)
    }
    log.Println(reply)

    _ = c.CloseSession(sess)
}

API

The Client type wraps the opencode-serve HTTP API:

• New(baseURL string, timeout time.Duration) *Client
• CreateSession(name, agent, model, workDir string, permissions []PermissionRule) (*Session, error)
• SendMessage(sess *Session, text string, opts ...MessageOptions) (string, error)
• SendMessageAsync(sess *Session, text string, opts ...MessageOptions) error
• GetLastResponse(sessionID string) (string, bool, error)
• CloseSession(sess *Session) error
• CloseSessionID(sessionID string) error

Session holds the session ID and the agent/model defaults:

type Session struct {
    ID    string
    Agent string
    Model string
}

MessageOptions allows per-call overrides:

type MessageOptions struct {
    Agent string
    Model string
}

When Agent or Model is empty in the options, the session-level value is used.

PermissionRule describes a single MCP permission:

type PermissionRule struct {
    Permission string `json:"permission"`
    Pattern    string `json:"pattern,omitempty"`
    Action     string `json:"action,omitempty"`
}

License

BSD

Documentation

Overview

Package opencodeclient provides a shared Go client for the opencode-serve HTTP REST API.

Index

• Constants
• type Client
  • func New(baseURL string, timeout time.Duration) *Client
  • func (c *Client) BaseURL() string
  • func (c *Client) CloseSession(sess *Session) error
  • func (c *Client) CloseSessionID(sessionID string) error
  • func (c *Client) CreateSession(name, agent, model, workDir string, permissions []PermissionRule) (*Session, error)
  • func (c *Client) GetLastResponse(sessionID string) (string, bool, error)
  • func (c *Client) SendMessage(sess *Session, text string, opts ...MessageOptions) (string, error)
  • func (c *Client) SendMessageAsync(sess *Session, text string, opts ...MessageOptions) error
  • func (c *Client) SetBasicAuth(username, password string)
  • func (c *Client) Timeout() time.Duration
• type MessageOptions
• type PermissionRule
• type Session
• type SessionInfo

Examples

• Client.SendMessage

Constants

const DefaultBaseURL = "http://127.0.0.1:7709"

DefaultBaseURL is the default address for a local opencode-serve instance.

const DefaultTimeout = 120 * time.Second

DefaultTimeout is the default timeout for blocking message requests.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client calls the opencode-serve HTTP API.

func New

func New(baseURL string, timeout time.Duration) *Client

New creates a client for the opencode-serve HTTP API. If baseURL is empty, DefaultBaseURL is used. If timeout is zero, DefaultTimeout is used.

func (*Client) BaseURL

func (c *Client) BaseURL() string

BaseURL returns the configured server address.

func (*Client) CloseSession

func (c *Client) CloseSession(sess *Session) error

CloseSession sends DELETE /session/{id} to release the session.

func (*Client) CloseSessionID

func (c *Client) CloseSessionID(sessionID string) error

CloseSessionID sends DELETE /session/{id} using a raw session ID.

func (*Client) CreateSession

func (c *Client) CreateSession(name, agent, model, workDir string, permissions []PermissionRule) (*Session, error)

CreateSession calls POST /session and returns a Session with the allocated session ID and the agent/model that will be used as defaults for subsequent calls.

func (*Client) GetLastResponse

func (c *Client) GetLastResponse(sessionID string) (string, bool, error)

GetLastResponse fetches the latest assistant message from a session. It returns the text and found=true if a completed assistant response exists.

func (*Client) SendMessage

func (c *Client) SendMessage(sess *Session, text string, opts ...MessageOptions) (string, error)

SendMessage calls POST /session/{id}/message and returns the assistant text response. Agent and model are taken from the session unless overridden via opts.

Example

// This example uses a local mock server to demonstrate the API shape.
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	json.NewEncoder(w).Encode(map[string]any{
		"info":  map[string]string{"id": "m1", "sessionID": "s1"},
		"parts": []map[string]string{{"type": "text", "text": "hello"}},
	})
}))
defer srv.Close()

c := New(srv.URL, 5*time.Second)
sess := &Session{ID: "s1"}
resp, err := c.SendMessage(sess, "hi")
if err != nil {
	fmt.Println("error:", err)
	return
}
fmt.Println(strings.Contains(resp, "hello"))

Output:
true

func (*Client) SendMessageAsync

func (c *Client) SendMessageAsync(sess *Session, text string, opts ...MessageOptions) error

SendMessageAsync sends a message without waiting for the response. Agent and model are taken from the session unless overridden via opts.

func (*Client) SetBasicAuth

func (c *Client) SetBasicAuth(username, password string)

SetBasicAuth configures HTTP Basic Authentication for all requests. Use this when connecting to a remote opencode-serve instance behind an nginx proxy with auth_basic.

func (*Client) Timeout

func (c *Client) Timeout() time.Duration

Timeout returns the configured blocking request timeout.

type MessageOptions

type MessageOptions struct {
	Agent string
	Model string
}

MessageOptions carries optional overrides for a single message. When a field is left empty, the session-level default is used.

type PermissionRule

type PermissionRule struct {
	Permission string `json:"permission"`
	Pattern    string `json:"pattern,omitempty"`
	Action     string `json:"action,omitempty"`
}

PermissionRule controls a single MCP permission for a session.

type Session

type Session struct {
	ID    string
	Agent string
	Model string
}

Session holds the opencode-serve session identifier and the agent/model used at creation time. These are used as defaults in SendMessage when the caller does not provide explicit overrides.

type SessionInfo

type SessionInfo struct {
	ID        string `json:"id"`
	Slug      string `json:"slug,omitempty"`
	ProjectID string `json:"projectID,omitempty"`
	Directory string `json:"directory,omitempty"`
	Agent     string `json:"agent,omitempty"`
	Version   string `json:"version,omitempty"`
	Title     string `json:"title,omitempty"`
}

SessionInfo is the opencode-serve session metadata returned on creation.