Codex CLI Playbook

Get Codex CLI ready

1. Install Codex CLI and authenticate (follow the official quickstart or the bundled terminal guide for platform-specific steps).
2. Keep the toolkit alongside your repository (AI-toolkit/). Export helpers:

   export CODEX_TOOLKIT=$PWD/AI-toolkit
   export CODEX_OUTPUT=$PWD/.codex
   mkdir -p "$CODEX_OUTPUT"

3. Run codex config set default_workdir $(pwd) so commands use the project root.
4. Symlink frequently used agents into .codex/agents if you prefer shorter paths.
5. Verify everything by asking Codex to list files: codex ask "List $CODEX_TOOLKIT/prompts".

Launch a new initiative with Codex

1. Seed context with codex prompt $CODEX_TOOLKIT/prompts/create_brief.md --input kickoff.md; copy the output into your Claude session.
2. Generate an execution plan via codex agent $CODEX_TOOLKIT/agents/orchestration/tech-lead-orchestrator.md --input feature.md and file the plan in your engineering notes.
3. For scaffolding, use codex agent $CODEX_TOOLKIT/agents/build-specialists/backend-developer.md or codex agent $CODEX_TOOLKIT/agents/build-specialists/frontend-developer.md to produce starter files, then stage them with git add.
4. Schedule automated tests by having Codex write the command queue (e.g., npm test, pytest) and paste it into a Makefile or GitHub Action.
5. Before code review, run the prompts and agents listed below to cross-check coverage, security, and docs.

Codex for legacy or refactor work

• Diff digestion: Pipe historical diffs into codex prompt $CODEX_TOOLKIT/prompts/code_review.md --diff old.patch to understand prior changes.
• Refactor plan: Use codex agent $CODEX_TOOLKIT/agents/quality/code-refactorer.md --input refactor-notes.md to create a safe sequence of commits.
• Audit dependencies: Combine npm ls --json or pipdeptree with codex agent $CODEX_TOOLKIT/agents/orchestration/project-analyst.md to surface risky libraries.
• Rollback blueprint: Ask reliability-commander.md for rollback steps and share with operations through Claude session updates.

Agent recipes that shine in Codex

Multi-agent execution loops

1. Orchestrate first: Use codex agent $CODEX_TOOLKIT/agents/orchestration/tech-lead-orchestrator.md --input epic.md to produce a sequenced plan that names each downstream agent.
2. Validate staffing: Run team-configurator.md with the orchestrator output so responsibilities, escalation paths, and required artefacts are explicit.
3. Chain commands: For each phase, feed the previous agent’s artefact to the next command (e.g. codex agent $CODEX_TOOLKIT/agents/frameworks/react/react-component-architect.md --input plan-phase2.md).
4. Agent-driven handoffs: When Codex suggests delegating work, ask it to write a handoff note (via session-closer.md) and reuse that file with codex agent ... for the next specialist.
5. Close with reviewers: Finish the chain by running code-reviewer.md, testing-expert.md, and reliability-commander.md; append their findings to /project:session-update.

Keep each agent’s output under $CODEX_OUTPUT/chain/ so you can re-run or parallelise specific phases without regenerating the entire plan.

Sample scenario: refactoring a legacy module

1. Brief & plan: Use codex prompt $CODEX_TOOLKIT/prompts/create_brief.md --input legacy-notes.md followed by codex prompt $CODEX_TOOLKIT/prompts/plan_feature.md to understand scope and constraints. Paste both outputs into the Claude session.
2. Chain specialists: Run tech-lead-orchestrator.md then team-configurator.md to identify the order: code-archaeologist.md (map code), code-refactorer.md (safe sequence), testing-expert.md (coverage requirements).
3. Implement: Let code-archaeologist.md summarise the module, feed that file to code-refactorer.md, and follow its step-by-step git commands. Execute recommended commands locally and paste logs into /project:session-update.
4. Review & validate: Run codex prompt $CODEX_TOOLKIT/prompts/code_review.md --diff git.diff and let brutal-critic.md in Claude highlight remaining risks. Finish with reliability-commander.md to ensure compliance.
5. Documentation: Generate final docs with codex prompt $CODEX_TOOLKIT/prompts/write_docs.md and attach the resulting markdown to the session log and repository docs.

Keep a timeline of agent outputs (plan, refactor steps, tests, docs) in $CODEX_OUTPUT/timeline.md so reviewers can trace every decision.

Creation catalogue & CLI recipes

Code & automation

• Greenfield services: codex prompt $CODEX_TOOLKIT/prompts/plan_feature.md --input new-service.md followed by codex agent $CODEX_TOOLKIT/agents/build-specialists/backend-developer.md to scaffold controllers, tests, and Dockerfiles.
• Script factories: Supply requirements to codex agent $CODEX_TOOLKIT/agents/build-specialists/python-expert.md --input automation.md to generate CLI tools, cron jobs, or migration scripts.
• CI/CD pipelines: Combine devops-cicd-expert.md with codex prompt --input .github/workflows/template.yml to tailor GitHub Actions, GitLab pipelines, or Jenkinsfiles.

Documentation & knowledge

• Architecture docs: Pipe project-analyst.md output into codex prompt $CODEX_TOOLKIT/prompts/write_docs.md --input architecture-notes.md for ADRs or system overviews.
• Runbooks: Have reliability-commander.md list operational steps, then let codex prompt --input runbook.md structure the content for on-call guides.
• API references: Feed OpenAPI specs into codex prompt --model codex-pro --input openapi.yml to produce SDK snippets and quickstart guides.

Testing & quality

• Unit/integration harnesses: codex agent $CODEX_TOOLKIT/agents/quality/testing-expert.md --input feature-plan.md can emit targeted pytest, Jest, or rspec suites.
• Static analysis rules: Ingest existing lint logs via codex prompt --input lint-report.txt --text "produce eslint rules" to generate new rule configs.
• Chaos scenarios: Pair reliability-commander.md with codex prompt --input chaos-plan.md to script fault-injection experiments.

Interfacing with other generators

• Image prompt drafting: Let Codex assemble structured prompts, then feed them to Gemini or Imagen for visual assets.
• Data prep: Use Codex to build CSV/JSON transformation scripts before handing data to BI or ML tooling.
• CLI orchestration: Have Codex generate shell scripts that call external generators (e.g. DALL·E, transcription APIs), then review the scripts inside Cursor or Claude.

Set CODEX_DEFAULT_MODEL in your shell to switch between models (e.g. export CODEX_DEFAULT_MODEL=codex-pro) and keep reusable command wrappers in a justfile for one-liners.

Prompt workflows

Stay aligned with Claude sessions

Discipline-specific playbooks

• Backend & microservices: Generate gRPC or REST contracts, add test cases with testing-expert.md, and request devops-cicd-expert.md for deployment pipeline snippets.
• Frontend & design: Use frontend-designer.md to translate Figma tokens, then tailwind-css-expert.md or vue-state-manager.md to wire state management.
• Data & ML: Ask ml-data-expert.md for experimentation notebooks, data validation plans, and feature store integration steps.
• Ops & SRE: Feed incident timelines to reliability-commander.md and performance-expert.md for postmortem-ready summaries.

Terminal and tooling integration

• Workflow automation: Wrap Codex commands in just or make recipes so engineers can run just codex-plan feature.
• Lint/test loop: Ask Codex to suggest command sequences, run them locally, and paste logs back for debugging (eslint, flake8, go test, npm run build).
• Diff application: When Codex proposes patches, save them to $CODEX_OUTPUT/ and inspect with git apply --stat before committing.
• External APIs: Pair with httpie or curl to gather live responses and feed them into agents for contract verification.

Best practices for Codex

• Keep prompts and agent inputs under token limits by summarising large files (sed -n '1,160p', rg excerpt pipelines).
• Request rationale: append --explain or ask “provide reasoning and trade-offs” to ensure you understand the proposed code.
• After Codex edits files, run local formatters and tests before asking Claude to finalise documentation.
• Store Codex conversations alongside Claude session logs to maintain a single source of truth.