bjornmelin/codex-sdk

Codex SDK + Codex CLI (master skill)

Build reliable, auditable, multi-step coding workflows that scale from a single run to multi-agent orchestration.

ExecPlans (durable planning)

For multi-hour work, keep intent durable across compaction/restarts using an ExecPlan:

• Contract: references/execplans.md
• Template + rules: .agent/PLANS.md (use scripts/init_agent_workspace.py to bootstrap a repo)
• ExecPlan skeleton: assets/templates/execplan.md (or generate a file with scripts/new_execplan.py)

Workflow decision tree

1. Need a scriptable one-shot in CI or cron? → use codex exec (references/codex-cli-exec.md)
2. Need a server-side app controlling Codex programmatically? → use @openai/codex-sdk (references/codex-sdk-typescript.md)
3. Need multi-agent orchestration or dynamic tools? → run codex mcp-server and orchestrate via OpenAI Agents SDK (references/mcp-and-agents-sdk.md)
4. Need durability across runs (memory, caching, resumable state)? → persist run metadata and event logs in SQLite (references/state-memory-sqlite.md)

Default workflow (safe + production-friendly)

1. Inventory inputs (repo root, diffs, failing commands, constraints).
2. Choose sandbox + approvals (least privilege; default to read-only).
3. Plan in explicit steps (short, verifiable; include stop conditions).
4. Use structured outputs (JSON Schema) and validate before acting.
5. Record an audit trail (JSONL events → SQLite).
6. Verify (re-run tests/lint/format; stop).

Durable state and “memory” (SQLite)

SQLite is the simplest reliable substrate for:

• recording every codex exec --json event as an immutable audit log
• indexing runs by repo, branch, and purpose
• storing threadId so runs can resume deterministically
• caching expensive analysis artifacts (diff summaries, inventories, dependency graphs)

Use the bundled scripts

• Initialize a DB:
  • python3 scripts/codex_jsonl_to_sqlite.py --db codex-runs.sqlite --init
• Ingest a JSONL run:
  • codex exec --json "<prompt>" | python3 scripts/codex_jsonl_to_sqlite.py --db codex-runs.sqlite --run-label "ci-autofix"
• Summarize runs:
  • python3 scripts/codex_sqlite_report.py --db codex-runs.sqlite --latest

Multi-agent orchestration (recommended shape)

Use:

• a single orchestrator responsible for gating and artifact checks
• multiple scoped worker agents with strict deliverables
• structured outputs at boundaries (handoff payloads, review findings, test results)
• traces/telemetry to debug and tune

Details: references/mcp-and-agents-sdk.md

Safety and policy

Prefer:

• analysis-only: sandbox: read-only, approval-policy: never
• controlled edits: sandbox: workspace-write, approval-policy: on-request / on-failure
• block risky commands with execpolicy rules (references/safety-and-execpolicy.md)

Resources

references/

• references/codex-sdk-typescript.md – SDK patterns (threads, streaming, schemas)
• references/codex-cli-exec.md – CLI patterns (JSONL, schema files, resume)
• references/mcp-and-agents-sdk.md – Codex as MCP server + multi-agent orchestration
• references/agents-sdk-consistent-workflows.md – gated handoffs + traces with Codex MCP + Agents SDK
• references/execplans.md – ExecPlans for long-running work across compaction
• references/state-memory-sqlite.md – SQLite schema + memory/caching patterns
• references/safety-and-execpolicy.md – sandboxing, approvals, prompt-injection defenses
• references/codex-config-knobs.md – config keys and feature flags that matter
• references/orchestration-patterns.md – planner/executor/verifier and orchestrator/worker patterns
• references/rag-and-memory.md – SQLite-first shared memory and RAG guidance
• references/context-personalization.md – state + memory notes personalization patterns (Agents SDK)

scripts/

• scripts/codex_jsonl_to_sqlite.py – ingest Codex JSONL into SQLite
• scripts/codex_sqlite_report.py – summarize runs from SQLite
• scripts/init_agent_workspace.py – create .agent/AGENTS.md + .agent/PLANS.md from templates
• scripts/new_execplan.py – generate execplans/execplan-*.md from the ExecPlan template

assets/

• assets/templates/ – copy/paste templates (ExecPlan, prompts, schemas)
• assets/templates/agents-sdk/ – Agents SDK starter snippets (MCP stdio, sessions, personalization)