codex-sdk-go

Go SDK for driving the codex CLI as a library.

This repository is the Go module:

go get github.com/f10et/codex-sdk-go

Requirements

• Go 1.24+
• codex available on PATH, or pass CodexPathOverride

Quickstart

package main

import (
	"fmt"

	codex "github.com/f10et/codex-sdk-go"
)

func main() {
	client := codex.New()
	thread := client.StartThread()

	turn, err := thread.Run("Diagnose the test failure and propose a fix")
	if err != nil {
		panic(err)
	}

	fmt.Println(turn.FinalResponse)
	fmt.Println(turn.Items)
}

Call Run() repeatedly on the same Thread to continue the same conversation.

Streaming responses

stream, err := thread.RunStreamed("Diagnose the test failure and propose a fix")
if err != nil {
	panic(err)
}

for event := range stream.Events {
	switch event.Type {
	case "item.completed":
		fmt.Printf("item: %#v\n", event.Item)
	case "turn.completed":
		fmt.Printf("usage: %#v\n", event.Usage)
	}
}

if err := stream.Wait(); err != nil {
	panic(err)
}

Structured output

schema := map[string]any{
	"type": "object",
	"properties": map[string]any{
		"summary": map[string]any{"type": "string"},
		"status": map[string]any{
			"type": "string",
			"enum": []any{"ok", "action_required"},
		},
	},
	"required":             []any{"summary", "status"},
	"additionalProperties": false,
}

turn, err := thread.Run("Summarize repository status", codex.TurnOptions{
	OutputSchema: schema,
})

Images

turn, err := thread.Run([]codex.UserInput{
	{Type: "text", Text: "Describe these screenshots"},
	{Type: "local_image", Path: "./ui.png"},
	{Type: "local_image", Path: "./diagram.jpg"},
})

Text entries are concatenated with blank lines. Image entries are forwarded as repeated --image flags.

Resuming threads

thread := client.ResumeThread(savedThreadID)
_, err := thread.Run("Implement the fix")

Thread options

enabled := true

thread := client.StartThread(codex.ThreadOptions{
	Model:                "gpt-5-codex",
	SandboxMode:          codex.SandboxWorkspaceWrite,
	WorkingDirectory:     "/path/to/project",
	SkipGitRepoCheck:     true,
	ModelReasoningEffort: codex.ReasoningHigh,
	NetworkAccessEnabled: &enabled,
	ApprovalPolicy:       codex.ApprovalOnRequest,
	AdditionalDirectories: []string{
		"/tmp/shared",
	},
})

Client options

client := codex.New(codex.CodexOptions{
	CodexPathOverride: "/path/to/codex",
	BaseURL:           "https://api.openai.com",
	APIKey:            "token",
	Config: map[string]any{
		"show_raw_agent_reasoning": true,
		"sandbox_workspace_write": map[string]any{
			"network_access": true,
		},
	},
	Env: map[string]string{
		"PATH": "/usr/local/bin",
	},
})

Config is flattened into repeated --config key=value TOML-compatible overrides. Thread options are emitted later, so they override overlapping client-level config values.