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)