codexsdk-go

README

codexsdk-go

Go client and generated protocol types for the Codex app-server JSON-RPC protocol.

This project is unofficial and experimental. It is not an OpenAI product, is not supported by OpenAI, and may lag or diverge from the Codex CLI/app-server implementation. Use it when you want a small Go SDK that talks to a locally launched Codex app-server over stdio.

Status

• License: MIT for this repository.
• Upstream protocol source: OpenAI Codex, Apache-2.0, generated from the app-server schema baseline recorded in codexsdk/internal/protocolschema/appserver/v2/baseline_metadata.json.
• API stability: pre-1.0. Public APIs are intended to be useful and reviewed, but breaking changes can happen before v1.0.
• Runtime requirement: the SDK launches an external codex app-server command. Unit tests and CI do not require a local Codex binary.

Packages

• codexsdk: stdio client, generated typed facades, exact ThreadRunner, exact notification streaming, and generated server-request handling.
• codexsdk/protocolv2: generated app-server v2 params, responses, notifications, enums, unions, JSON helpers, and method registry.
• codexsdk/internal/protocolgen: generator internals for the checked-in schema baseline.
• codexsdk/internal/protocolschema/appserver/v2: reviewed schema baseline, classified manifest, coverage matrix, drift report, and provenance metadata.

Installation

go get github.com/ronhuafeng/codexsdk-go

The module targets Go 1.23 or newer.

To run against a real app-server, install Codex CLI separately and make sure codex is on PATH:

codex --version

Quick Start: Typed Client

package main

import (
	"context"
	"log"
	"os"

	"github.com/ronhuafeng/codexsdk-go/codexsdk"
	"github.com/ronhuafeng/codexsdk-go/codexsdk/protocolv2"
)

func main() {
	ctx := context.Background()
	workspace, err := os.Getwd()
	if err != nil {
		log.Fatal(err)
	}

	client, err := codexsdk.New(codexsdk.ClientOptions{
		CWD:     workspace,
		Command: []string{"codex", "app-server", "--listen", "stdio://"},
	})
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	resp, err := client.Models().List(ctx, protocolv2.ModelListParams{})
	if err != nil {
		log.Fatal(err)
	}
	log.Printf("models: %d", len(resp.Data))
}

Quick Start: Exact ThreadRunner

ThreadRunner transparently composes exact generated thread/start and turn/start params. The result retains the exact start response, terminal turn, usage, and every attributable generated notification.

package main

import (
	"context"
	"log"
	"os"

	"github.com/ronhuafeng/codexsdk-go/codexsdk"
	"github.com/ronhuafeng/codexsdk-go/codexsdk/protocolv2"
)

func main() {
	ctx := context.Background()
	workspace, err := os.Getwd()
	if err != nil {
		log.Fatal(err)
	}
	model := os.Getenv("CODEXSDK_EXAMPLE_MODEL")
	if model == "" {
		log.Fatal("set CODEXSDK_EXAMPLE_MODEL")
	}

	root, err := codexsdk.New(codexsdk.ClientOptions{
		CWD:     workspace,
		Command: []string{"codex", "app-server", "--listen", "stdio://"},
	})
	if err != nil {
		log.Fatal(err)
	}
	defer root.Close()

	result, err := root.ThreadRunner().Start(ctx, codexsdk.StartThreadRunRequest{
		Thread: protocolv2.ThreadStartParams{
			Ephemeral: protocolv2.Value(true),
			Model:     protocolv2.Value(model),
		},
		Turn: protocolv2.TurnStartParams{
			Input: []protocolv2.UserInput{
				protocolv2.NewUserInputText(protocolv2.UserInputText{
					Text: "Reply with a short confirmation.",
				}),
			},
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	log.Println(result.Run.FinalResponse)
}

StartStream and ResumeStream expose every exact protocolv2.ServerNotification; Result remains available on failures and contains the latest immutable partial snapshot. More compile-checked examples live in codexsdk/examples_test.go.

The v0.1 ThreadClient, copied request/result models, event projections, and conversion helpers remain deprecated compatibility surface through v0.2. New code should use generated params and ThreadRunner.

Real App-Server Smoke Test

The real smoke test is opt-in because it launches Codex, uses a configured model, and may create or consume account state.

CODEXSDK_REAL_APP_SERVER_SMOKE=1 \
CODEXSDK_REAL_APP_SERVER_MODEL=gpt-5-mini \
go test ./codexsdk -run TestRealAppServerSmokeStartResumeFork -count=1

Optional command override:

CODEXSDK_REAL_APP_SERVER_COMMAND='codex app-server --listen stdio://' \
CODEXSDK_REAL_APP_SERVER_SMOKE=1 \
CODEXSDK_REAL_APP_SERVER_MODEL=gpt-5-mini \
go test ./codexsdk -run TestRealAppServerSmokeStartResumeFork -count=1

Normal CI does not run this test.

Protocol V2 Schema Strategy

protocolv2 code is generated from a checked-in Codex app-server v2 schema baseline, not by shelling out to Codex during normal builds. The baseline is tracked with:

• baseline_metadata.json: upstream tag/ref name, target kind, peeled commit, Codex version, generation command, source license, file count, and schema bundle checksum.
• manifest.json: classified method surface, request/notification direction, response schema mapping, facade target, and stable-vs-experimental marking.
• coverage_matrix.json: reviewed support status for methods, types, and key fields.
• drift_report.json and matrix_update_skeleton.json: last clean comparison artifacts and the shape of follow-up review work when upstream changes.

Regenerate Go code from the checked-in baseline:

go run ./codexsdk/internal/cmd/protocolv2gen

Check generated code reproducibility without modifying the tree:

go run ./codexsdk/internal/cmd/protocolv2gen -stdout method-registry |
  diff -u codexsdk/protocolv2/method_registry.gen.go -
go run ./codexsdk/internal/cmd/protocolv2gen -stdout protocol-types |
  diff -u codexsdk/protocolv2/protocol_types.gen.go -

Maintenance

Use the upstream tracking script to generate review artifacts for a Codex schema update. The script is read-only for the checked-in baseline unless a maintainer copies reviewed files back into the SDK tree.

Check the target policy before generating drift artifacts. Scheduled automation tracks stable rust-vX.Y.Z tags only when the current baseline is already on that stable tag track; manual commits and track switches must be explicit.

python3 scripts/codexsdk_target_policy.py \
  --baseline codexsdk/internal/protocolschema/appserver/v2/baseline_metadata.json \
  --target-ref rust-v0.140.0 \
  --target-kind stable_rust_tag \
  --target-sha <peeled-target-commit> \
  --target-explicit true \
  --mode manual \
  --json

scripts/codexsdk_track_upstream.sh \
  --codex-repo /path/to/openai/codex \
  --commit <peeled-target-commit> \
  --source-ref rust-v0.140.0 \
  --source-ref-kind stable_rust_tag \
  --out /tmp/codexsdk-upstream

Then review the generated reports/SUMMARY.md, schema drift summary, and matrix update skeleton before updating the baseline, manifest, coverage matrix, and generated Go code. Keep handwritten SDK changes limited to reviewed public surface or compatibility fixes. See docs/release.md for the release and schema baseline checklists.

After committing a successful baseline sync, tag the codexsdk-go commit with an annotated upstream sync tag. These tags intentionally live outside the Go module release namespace.

python3 scripts/codexsdk_sync_tag.py --json
python3 scripts/codexsdk_sync_tag.py --create --push origin --json

Stable upstream Codex tags use upstream-codex-rust-vX.Y.Z. Existing upstream sync tags are never moved; use --next-suffix to create upstream-codex-rust-vX.Y.Z-sync.N for follow-up SDK fixes against the same upstream tag. Manual upstream commits and refs intentionally do not get fallback sync tags.

Compatibility Policy

Before v1.0, minor releases may include breaking changes when the upstream Codex app-server protocol changes or when the SDK corrects an unsafe public API. Patch releases should be backwards compatible except for security or data corruption fixes.

After v1.0, the project should follow SemVer for the public API in codexsdk and codexsdk/protocolv2. Generated protocolv2 additions are usually minor changes. Removing or changing generated types, method constants, or facade method signatures is a major change unless the upstream protocol removed the surface and compatibility cannot be preserved safely.

Security

Do not put API keys, account tokens, private workspaces, private schema dumps, or local absolute paths into issues, tests, schema metadata, or generated artifacts. The SDK starts a local app-server process and forwards requests over stdio; callers are responsible for choosing an appropriate Codex command, working directory, approval policy, and server request handler.

See SECURITY.md for vulnerability reporting guidance.