feat(baseline): init

Author: Savid

.claude/rules/architecture.md

@@ -0,0 +1,41 @@
+# Architecture
+
+## Transport and Backend Model
+
+The SDK supports two built-in execution backends:
+
+1. `exec` backend (`codex exec`)
+2. `app-server` backend (`codex app-server`)
+
+## Backend Routing Rules
+
+- `Query(...)` auto-selects backend from enabled options.
+  - Uses `exec` when all selected options are supported there.
+  - Routes to `app-server` when required by selected options.
+- `QueryStream(...)` uses app-server semantics unless `WithTransport(...)` injects custom transport.
+- `Client.Start(...)` uses app-server transport semantics.
+
+Capability selection/validation logic lives in:
+
+- `internal/config/capability.go`
+
+## High-Level Components
+
+- `query.go`: one-shot and query-stream orchestration
+- `client.go` + `client_impl.go`: stateful client interface + implementation
+- `with_client.go`: lifecycle helper wrapper
+- `mcp.go`: `Tool` interface and `NewTool` constructor for SDK-defined tools
+- `internal/subprocess/`: process and app-server adapters
+- `internal/protocol/`: JSON-RPC/session controller, dynamic tool dispatch
+- `internal/message/`: parsing + public message mapping
+- `internal/config/`: options, `DynamicTool` type, and backend capability policy
+- `internal/session/`: SQLite-based session metadata lookup
+- `internal/mcp/`: MCP server integration and status
+
+## Change Impact Guidance
+
+When changing options, transport, or session behavior:
+
+- verify backend capability mapping in `internal/config/capability.go`
+- update related tests (capability, query/client behavior)
+- keep docs aligned (`README.md`, package docs, CLAUDE rules where needed)

.claude/rules/boundaries.md

@@ -0,0 +1,22 @@
+# Boundaries
+
+## Always
+
+- Follow existing patterns in neighboring code before introducing new patterns.
+- Keep behavior changes covered by tests in the same PR.
+- Run relevant tests for changed code; run `go test ./...` for substantial changes.
+- Keep user-facing and agent-facing docs aligned when public behavior changes.
+
+## Ask First
+
+- Adding exported API surface (new public functions/types/options).
+- Changing transport interfaces or protocol semantics.
+- Adding new third-party dependencies.
+- Making breaking behavior changes to existing option semantics.
+
+## Never
+
+- Leave errors unchecked.
+- Store `context.Context` in structs.
+- Mix naming that implies another SDK/provider when describing this codebase.
+- Bypass backend capability checks for options.

.claude/rules/build-and-test.md

@@ -0,0 +1,25 @@
+# Build and Test
+
+## Default Commands
+
+```bash
+go build ./...
+go test ./...
+go test -race ./...
+go test -v -run TestQuery ./...
+go test -tags=integration ./integration/...
+golangci-lint run
+go run ./examples/quick_start
+```
+
+## Command Usage
+
+- Use targeted tests first while iterating (single package or `-run` pattern).
+- Before finishing substantial code changes, run `go test ./...`.
+- Run `go test -race ./...` for concurrency-sensitive changes.
+- Run `golangci-lint run` before finalizing when Go files changed.
+
+## Integration Test Notes
+
+- Integration tests require Codex CLI availability and a working runtime setup.
+- If integration tests are not runnable in the current environment, call that out explicitly.

.claude/rules/coding-conventions.md

@@ -0,0 +1,32 @@
+# Coding Conventions
+
+## Core Style
+
+- Keep package and naming consistent with existing code (`codexsdk`).
+- Keep context as the first parameter for blocking operations.
+- Use functional options (`WithXxx(...)`) for configurable behavior.
+- Re-export public-facing types from root package when following existing pattern.
+
+## Logging
+
+- Use structured `slog` logging.
+- Prefer context-aware logging calls when a relevant context is available in that path.
+- Keep log messages concise and action-oriented.
+
+## Errors
+
+- Wrap errors with `%w` so callers can use `errors.Is`/`errors.As`.
+- Prefer typed or sentinel errors from `errors.go` for stable checks.
+- Do not suppress or ignore returned errors.
+
+## API and Option Changes
+
+- Keep public option constructors in `options.go`.
+- If option behavior differs by backend, update capability policy in `internal/config/capability.go`.
+- Ensure unsupported combinations fail with `ErrUnsupportedOption`.
+
+## Repo Structure
+
+- Keep implementation details in `internal/`.
+- Avoid introducing generic catch-all packages (`utils`, `helpers`, `common`).
+- Follow nearby file patterns before introducing new structure.

.claude/rules/project-overview.md

@@ -0,0 +1,34 @@
+# Project Overview
+
+## Identity
+
+- Repository: `github.com/ethpandaops/codex-agent-sdk-go`
+- Primary package: `codexsdk`
+- Go version: `1.26+`
+- Minimum Codex CLI version: `0.103.0+` (see `version.go`)
+
+## What This SDK Exposes
+
+- One-shot query API: `Query(ctx, prompt, opts...)`
+- Streaming input query API: `QueryStream(ctx, messages, opts...)`
+- Stateful client API: `NewClient()` + `Client` methods
+- Lifecycle helper: `WithClient(ctx, fn, opts...)`
+- Session metadata API: `StatSession(ctx, sessionID, opts...)`
+
+## Primary Public Surface Areas
+
+- `options.go`: all `WithXxx(...)` constructors
+- `mcp.go`: `Tool` interface, `NewTool` constructor, and `WithSDKTools` tool registration
+- `client.go`: `Client` interface
+- `query.go`: top-level query functions
+- `session_stat.go`: `SessionStat` struct and `StatSession()` function
+- `types.go`: re-exported message/content/config types
+- `errors.go`: typed and sentinel errors
+
+## Documentation Sync Expectations
+
+When public APIs or options change, update in the same PR:
+
+- `README.md` (user-facing)
+- `doc.go` (package docs)
+- `CLAUDE.md` / `.claude/rules/*` if agent guidance changed

.github/dependabot.yml

@@ -0,0 +1,19 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      github-actions:
+        patterns:
+          - "*"
+
+  - package-ecosystem: gomod
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      go-dependencies:
+        patterns:
+          - "*"

.github/typos.toml

@@ -0,0 +1,2 @@
+[files]
+extend-exclude = ["go.mod", "go.sum"]

.github/workflows/check-typos.yml

@@ -0,0 +1,17 @@
+name: Typos
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  typos:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Check for typos
+        uses: crate-ci/typos@0f0ccba9ed1df83948f0c15026e4f5ccfce46109 # v1.32.0

.github/workflows/go-setup/action.yml

@@ -0,0 +1,17 @@
+name: 'Setup Go'
+description: 'Set up Go environment with caching'
+
+inputs:
+  go-version:
+    description: 'Go version to use'
+    required: false
+    default: '1.25'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Set up Go
+      uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5.5.0
+      with:
+        go-version: ${{ inputs.go-version }}
+        cache: true

.github/workflows/go-test.yml

@@ -0,0 +1,26 @@
+name: Test
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Setup Go
+        uses: ./.github/workflows/go-setup
+
+      - name: Build
+        run: go build ./...
+
+      - name: Test
+        run: go test -race ./...