{"id":51614017,"url":"https://github.com/hishamkaram/codex-agent-sdk-go","last_synced_at":"2026-07-12T11:31:18.416Z","repository":{"id":352286094,"uuid":"1214551165","full_name":"hishamkaram/codex-agent-sdk-go","owner":"hishamkaram","description":"Go SDK for the OpenAI Codex CLI app-server transport with JSON-RPC 2.0, typed events, approvals, MCP config, and structured output.","archived":false,"fork":false,"pushed_at":"2026-06-26T16:01:58.000Z","size":1193,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-26T18:04:27.416Z","etag":null,"topics":["agentd","ai-agents","app-server","approvals","codex","codex-cli","developer-tools","go","json-rpc","mcp","openai","sdk","structured-output","typed-events"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/hishamkaram/codex-agent-sdk-go","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hishamkaram.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-18T18:21:30.000Z","updated_at":"2026-06-26T16:02:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"d18d0c29-efc6-4a7a-8684-2d5300fa3e43","html_url":"https://github.com/hishamkaram/codex-agent-sdk-go","commit_stats":null,"previous_names":["hishamkaram/codex-agent-sdk-go"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/hishamkaram/codex-agent-sdk-go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hishamkaram%2Fcodex-agent-sdk-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hishamkaram%2Fcodex-agent-sdk-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hishamkaram%2Fcodex-agent-sdk-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hishamkaram%2Fcodex-agent-sdk-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hishamkaram","download_url":"https://codeload.github.com/hishamkaram/codex-agent-sdk-go/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hishamkaram%2Fcodex-agent-sdk-go/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35391313,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-12T02:00:06.386Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentd","ai-agents","app-server","approvals","codex","codex-cli","developer-tools","go","json-rpc","mcp","openai","sdk","structured-output","typed-events"],"created_at":"2026-07-12T11:31:13.167Z","updated_at":"2026-07-12T11:31:18.408Z","avatar_url":"https://github.com/hishamkaram.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Codex Agent SDK for Go\n\n[![Go 1.25](https://img.shields.io/badge/Go-1.25-00add8?logo=go\u0026logoColor=white)](https://go.dev/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\nGo SDK for the OpenAI Codex CLI **app-server** transport — spawns `codex app-server` as a child process, speaks JSON-RPC 2.0 over stdio, and exposes a typed Go API for threads, turns, streaming events, approvals, and MCP configuration.\n\n\u003e **Status**: preview (`v0.x`). API may change before `v1.0.0`. Feedback welcome.\n\nSibling SDK: [`claude-agent-sdk-go`](https://github.com/hishamkaram/claude-agent-sdk-go) does the same thing for the Claude Code CLI.\n\n## Why this SDK?\n\nCodex's app-server exposes a JSON-RPC 2.0 protocol over stdio — bidirectional, stateful, with server-initiated approval requests. Consuming it directly means handling line-framing with a 2 MiB minimum buffer, demultiplexing three request shapes (responses, notifications, server-initiated requests), serializing concurrent turns to preserve event boundaries, and mapping schema-covered notification methods to typed Go events. This SDK handles all of that and exposes a clean, typed API.\n\n## Feature matrix\n\n| Feature | Status on current mainline |\n|---|---|\n| `codex app-server` transport | ✅ |\n| `codex exec --json` one-shot | ❌ deferred to v2 |\n| Thread start / resume / fork / archive / list | ✅ |\n| `thread.Run()` (buffered) + `thread.RunStreamed()` (channel) | ✅ |\n| Streaming events: turn/item lifecycle, token usage, thread lifecycle/goals, process output, model/account/warning events, hooks, realtime, and unknown-event fallback | ✅ |\n| ThreadItem variants: agentMessage, userMessage, commandExecution, fileChange, mcpToolCall, webSearch, memoryRead/Write, plan, reasoning, systemError | ✅ |\n| Input variants: text, localImage | ✅ |\n| Sandbox modes: read-only, workspace-write, danger-full-access | ✅ |\n| Approval policies: untrusted, on-failure, on-request, granular, never | ✅ |\n| Approval callback (server-initiated request → caller decides) | ✅ |\n| MCP server config (stdio + streamable HTTP) | ✅ |\n| JSON-schema structured output | ✅ |\n| Typed errors with `Is*()` helpers | ✅ |\n| Turn interrupt | ✅ |\n| CLI discovery + soft version probe | ✅ |\n| Goroutine leak detection (goleak) | ✅ |\n| Hook observer events (HookStarted / HookCompleted) | ✅ v0.2.0 — via `WithHooks(true)` |\n| Programmatic Go hook callbacks (shim bridge, auto-wired) | ✅ v0.3.0 — `WithHookCallback(h)` writes hooks.json automatically and restores on Close. See `docs/hooks.md`. |\n| Slash-command equivalents (Compact, SetModel, ListMCPServerStatus, Review, etc.) | ✅ v0.4.0 — typed methods plus `GitDiff` / `InitAgentsMD` helpers. See `docs/commands.md`. |\n| Native FFI (CGO) | ❌ deferred |\n\n## Prerequisites\n\n- Go 1.25+\n- Codex CLI installed: `npm install -g @openai/codex` (or your distro's equivalent)\n  - Recommended/tested CLI: `0.130.0` (verified 2026-05-13); older versions run with a soft warning.\n- Auth (one of):\n  - `OPENAI_API_KEY` environment variable (pay-per-token)\n  - `~/.codex/auth.json` (ChatGPT Plus/Pro subscription; run `codex login` once outside the daemon)\n\n## Install\n\n```bash\ngo get github.com/hishamkaram/codex-agent-sdk-go\n```\n\n## Quick start\n\n### One-shot query\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\n\tcodex \"github.com/hishamkaram/codex-agent-sdk-go\"\n\t\"github.com/hishamkaram/codex-agent-sdk-go/types\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\topts := types.NewCodexOptions().\n\t\tWithSandbox(types.SandboxReadOnly).\n\t\tWithApprovalPolicy(types.ApprovalOnRequest)\n\n\tevents, err := codex.Query(ctx, \"Summarize the repo in the current directory\", opts)\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tfor event := range events {\n\t\tswitch e := event.(type) {\n\t\tcase *types.ItemCompleted:\n\t\t\tif msg, ok := e.Item.(*types.AgentMessage); ok {\n\t\t\t\tfmt.Println(msg.Text)\n\t\t\t}\n\t\tcase *types.TurnCompleted:\n\t\t\tfmt.Printf(\"Tokens: in=%d out=%d\\n\", e.Usage.InputTokens, e.Usage.OutputTokens)\n\t\t}\n\t}\n}\n```\n\n### Interactive multi-turn client\n\n```go\nclient, err := codex.NewClient(ctx, opts)\nif err != nil { log.Fatal(err) }\ndefer client.Close(ctx)\n\nthread, err := client.StartThread(ctx, \u0026types.ThreadOptions{Cwd: \"/my/project\"})\nif err != nil { log.Fatal(err) }\n\nevents, _ := thread.RunStreamed(ctx, \"Make a plan to fix the CI failure\", nil)\nfor event := range events { /* ... */ }\n\nevents2, _ := thread.RunStreamed(ctx, \"Now implement the plan\", nil)\nfor event := range events2 { /* ... */ }\n```\n\n### Approval callback\n\n```go\nopts = opts.WithApprovalCallback(func(ctx context.Context, req types.ApprovalRequest) types.ApprovalDecision {\n\tif r, ok := req.(*types.CommandExecutionApprovalRequest); ok {\n\t\tif isSafeCommand(r.Command) {\n\t\t\treturn types.ApprovalAccept{}\n\t\t}\n\t}\n\treturn types.ApprovalDeny{Reason: \"not on allowlist\"}\n})\n```\n\n## What it does\n\n- Spawns `codex app-server` as a subprocess with stdin/stdout pipes\n- Frames JSON-RPC 2.0 messages with LF termination (`jsonrpc` field omitted on wire)\n- Demultiplexes responses (id → pending chan), notifications (→ events chan), server-initiated requests (→ approval callback)\n- Serializes all stdin writes via single `stdinMu` to prevent frame interleave\n- Serializes per-thread `Run()` calls via `turnMu` to preserve turn boundaries\n- Maintains a 2 MiB read buffer for large notification payloads\n- Translates raw JSON-RPC notifications into typed Go events with schema drift checks for Codex upgrades\n- Handles CLI discovery (PATH, `~/.codex/bin`, brew, npm install paths) and soft version probe\n- Emits structured logs via zap\n\n## What it does NOT do (current preview)\n\n- `codex exec --json` (fire-and-forget) transport — the `app-server` path is the only one implemented\n- Codex-as-MCP-server mode (experimental upstream)\n- Dynamic OpenAI pricing table (use static rates in this SDK; fetch at integration time if needed)\n\n## Docs\n\n- [`docs/getting-started.md`](docs/getting-started.md) — install, first query, multi-turn, streaming, resume, approvals in ~2 pages\n- [`docs/architecture.md`](docs/architecture.md) — the four layers, dispatcher goroutine, turn lock, concurrency contract, shutdown ladder\n- [`docs/wire-protocol.md`](docs/wire-protocol.md) — JSON-RPC method reference, wire quirks (flat vs nested IDs, per-item delta methods), known-unknown methods\n- [`docs/approvals.md`](docs/approvals.md) — approval request/decision taxonomy, sandbox × policy matrix, deadlock warning\n- [`docs/hooks.md`](docs/hooks.md) — observer mode + auto-wired programmatic callbacks via `WithHookCallback` (v0.3.0)\n- [`docs/commands.md`](docs/commands.md) — slash-command-equivalent typed methods (Compact, SetModel, Rollback, StartReview, …) and local-helper parity (GitDiff, InitAgentsMD) (v0.4.0)\n\n## Examples\n\nEight runnable examples under [`examples/`](examples/):\n\n| Example | What it shows |\n|---|---|\n| [`simple_query`](examples/simple_query/main.go) | One-shot `Query()` |\n| [`streaming`](examples/streaming/main.go) | Multi-turn `RunStreamed` + delta streaming |\n| [`resume`](examples/resume/main.go) | Persistent thread across process restarts |\n| [`fork`](examples/fork/main.go) | Branching a thread |\n| [`with_approvals`](examples/with_approvals/main.go) | Command + file approval callback |\n| [`with_mcp`](examples/with_mcp/main.go) | Registering MCP servers (stdio + HTTP) |\n| [`with_hooks`](examples/with_hooks/main.go) | Observe HookStarted/HookCompleted events from your configured hooks |\n| [`structured_output`](examples/structured_output/main.go) | JSON-schema-constrained final response |\n\nBuild all: `make examples`. Run any: `go run ./examples/\u003cname\u003e`.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhishamkaram%2Fcodex-agent-sdk-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhishamkaram%2Fcodex-agent-sdk-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhishamkaram%2Fcodex-agent-sdk-go/lists"}