Skip to content

Instantly share code, notes, and snippets.

@fullkomnun

fullkomnun/CODEX-CLI-GUIDE.md

Last active March 24, 2026 22:00
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save fullkomnun/d0497a172fd8474da3f214997cf85222 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save fullkomnun/d0497a172fd8474da3f214997cf85222 to your computer and use it in GitHub Desktop.
Download ZIP
Codex CLI Guide for `compliant-transfer-aleo`
Raw
CODEX-CLI-GUIDE.md

Codex CLI Guide for compliant-transfer-aleo

Slack-ready onboarding guide for a teammate on Apple Silicon macOS who has ChatGPT Plus and wants to use Codex CLI well in this repository.

What this is

  • This guide assumes Apple Silicon Mac.
  • This guide assumes a ChatGPT Plus subscription.
  • This guide assumes little or no prior Codex CLI or terminal-agent experience.
  • This guide assumes you want to review, design, plan, implement, and debug work in this repo.
  • This repo is already prepared with agent context.
  • Root AGENTS.md exists and is auto-loaded by Codex when you start in the repo.
  • The linked docs are useful, but not auto-loaded unless you ask Codex to read them.

Important current note

  • As of 2026-03-24, the latest public Codex CLI GitHub release is 0.116.0, released on 2026-03-19.
  • Codex CLI supports ChatGPT sign-in. For a ChatGPT Plus user, that is the recommended path for interactive local use.

5-minute install and first run

1. Install Codex CLI

Recommended on macOS if you already use Homebrew:

brew install --cask codex
codex --version

If you prefer npm:

npm install -g @openai/codex
codex --version

2. Sign in the right way

Run:

codex

Then choose:

  • Sign in with ChatGPT

Why:

  • That uses your ChatGPT subscription access
  • Fast-mode features rely on ChatGPT sign-in
  • It is the default CLI login path when no valid session exists

If your ChatGPT account uses email/password, set up MFA first. If you use Apple/Google/Microsoft login, manage MFA with that provider.

3. Prefer macOS Keychain for cached auth

Create or edit ~/.codex/config.toml:

cli_auth_credentials_store = "keyring"

That keeps credentials in the macOS credential store instead of a plaintext auth file when possible.

4. Open this repo and verify Codex sees the repo instructions

cd /path/to/repo/compliant-transfer-aleo
codex

First prompt to send:

Summarize the instruction sources you loaded for this repository, then list which additional docs I should explicitly ask you to read for Leo work and for test work.

Expected result:

  • Codex should mention the root AGENTS.md.
  • It should point you to docs like docs/DEVELOPMENT.md.
  • It should point you to docs like docs/TESTING.md.
  • It should point you to docs like docs/LEO-ALEO-PATTERNS.md.
  • It should point you to docs like docs/CODE-PATTERNS.md.

Best one-time quickstart for /review with GPT-5.4 and high reasoning

If you want a single command without setting up config first:

codex \
  -C /path/to/repo/compliant-transfer-aleo \
  -m gpt-5.4 \
  -a on-request \
  -s read-only \
  -c 'model_reasoning_effort="high"' \
  -c 'plan_mode_reasoning_effort="high"' \
  -c 'review_model="gpt-5.4"' \
  -c 'service_tier="fast"'

Then inside Codex:

/status

Check that you are in:

  • model gpt-5.4
  • reasoning effort high
  • sandbox read-only
  • approval policy on-request

Then send:

Read AGENTS.md, docs/LEO-ALEO-PATTERNS.md, docs/CODE-PATTERNS.md, and docs/TESTING.md. After that, review this repository's current working tree for correctness, security, Leo/Aleo execution-model mistakes, authorization-order mistakes, private/public visibility leaks, Merkle/freeze-list inconsistencies, and missing tests. Findings first with file references.

Then:

/review

Notes:

  • /review uses the current session model unless review_model is configured
  • /review is ideal for uncommitted changes, a commit, or a PR-style review against a base branch
  • /diff is the fastest follow-up when you want to inspect exact changed files

Recommended personal config

Put this in ~/.codex/config.toml.

model = "gpt-5.4"
review_model = "gpt-5.4"
model_reasoning_effort = "high"
plan_mode_reasoning_effort = "high"
model_reasoning_summary = "concise"
model_verbosity = "medium"
personality = "pragmatic"
approval_policy = "on-request"
sandbox_mode = "read-only"
service_tier = "fast"
cli_auth_credentials_store = "keyring"

[profiles.review]
model = "gpt-5.4"
review_model = "gpt-5.4"
model_reasoning_effort = "high"
plan_mode_reasoning_effort = "high"
model_reasoning_summary = "concise"
model_verbosity = "medium"
approval_policy = "on-request"
sandbox_mode = "read-only"
service_tier = "fast"
personality = "pragmatic"

[profiles.edit]
model = "gpt-5.4"
review_model = "gpt-5.4"
model_reasoning_effort = "high"
plan_mode_reasoning_effort = "high"
model_reasoning_summary = "concise"
model_verbosity = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
service_tier = "fast"
personality = "pragmatic"

[sandbox_workspace_write]
network_access = false
writable_roots = []

Why this is a good starting point:

  • review profile is safe for reading and reviewing
  • edit profile allows normal implementation work but still asks before risky commands
  • gpt-5.4 with high reasoning is a good default for complex code review, debugging, and design
  • service_tier = "fast" is useful for interactive work if your ChatGPT sign-in supports it

If fast is not available in your workspace, switch that line to:

service_tier = "flex"

Daily start commands

Review mode

cd /path/to/repo/compliant-transfer-aleo
codex --profile review

Edit / implement mode

cd /path/to/repo/compliant-transfer-aleo
codex --profile edit

One-off non-interactive run

codex exec \
  --profile review \
  --cd /path/to/repo/compliant-transfer-aleo \
  "Read AGENTS.md, docs/LEO-ALEO-PATTERNS.md, docs/CODE-PATTERNS.md, and docs/TESTING.md. Review the current working tree and output findings only."

Resume the last non-interactive session

codex exec resume --last

The commands and slash commands you will actually use

Terminal commands

codex --profile review
codex --profile edit
codex --version
codex login
codex logout
codex features list
codex exec "your prompt here"
codex exec resume --last

Useful flags:

  • -C or --cd: start Codex in a specific directory
  • -m or --model: override the model for one run
  • -p or --profile: use a named config profile
  • -a or --ask-for-approval: untrusted, on-request, or never
  • -s or --sandbox: read-only, workspace-write, or danger-full-access
  • -c or --config: one-off config override
  • --search: enable live web search for that run
  • --json: machine-readable output for automation
  • -o or --output-last-message: write the final answer to a file

Slash commands

These are the ones worth memorizing:

  • /status
  • /debug-config
  • /model
  • /fast
  • /plan
  • /review
  • /diff
  • /mention
  • /new
  • /resume
  • /fork
  • /mcp

What they are for:

  • /status: confirm model, approvals, writable roots, token usage
  • /debug-config: see which config layer is winning
  • /model: switch models in-session
  • /fast: toggle fast mode for the thread
  • /plan: force planning before coding
  • /review: run a focused code review
  • /diff: inspect Git diff
  • /mention: explicitly attach a file into the current conversation
  • /resume: reopen a saved chat
  • /fork: branch the current conversation into an alternative path
  • /mcp: list connected MCP tools

Repository bootstrap for actual work

If you want Codex to compile or test changes in this repo, make sure the repo itself is prepared first.

Required local setup

Use the repo root only:

cd /path/to/repo/compliant-transfer-aleo

Recommended setup:

cp .env.example .env
npm ci --ignore-scripts
npm install -g @sealance-io/dokojs@1.0.4 --ignore-scripts

Node notes:

  • Repo requirement: Node 20.19.0+ on the 20.x line, or 22.12.0+
  • Repo default in .nvmrc: v24

Critical repo rules:

  • Always install from repo root
  • Never run npm install inside a workspace subdirectory
  • Keep --ignore-scripts on npm installs in this repo
  • Integration tests must run sequentially

Build and test commands Codex should use here

dokojs compile
npm test
DEVNET=true npm test
npm run test:agent
npm run test:select ./test/merkle_tree.test.ts
npm run test:select:agent ./test/merkle_tree.test.ts
npm run build --workspace=@sealance-io/policy-engine-aleo
npm run format:fix

Important repo-specific test behavior:

  • Default and recommended mode is devnode
  • DEVNET=true is slower and should be used only when needed
  • Prefer the agent reporter for Vitest when possible
  • Tests share chain state, so they must not be parallelized

If tests fail to pull images:

docker login ghcr.io

If port 3030 is already taken:

docker stop $(docker ps -q --filter ancestor=ghcr.io/sealance-io/leo-lang)

How to prompt Codex well in this repo

OpenAI’s own guidance is a strong default:

  • State the goal
  • Give the relevant context
  • State constraints
  • Define what “done” means

In this repo, the biggest mistake is assuming Codex will automatically read every linked architecture/testing doc. It will not. Tell it what to read.

Good default prompt shape

Goal: <what you want>
Context: Read AGENTS.md and <specific docs/files>.
Constraints: Follow repo rules, keep changes minimal, preserve existing patterns, and call out assumptions.
Done when: <tests/review output/behavioral proof>.

Copy-paste prompt templates

1. Review current changes

Read AGENTS.md, docs/LEO-ALEO-PATTERNS.md, docs/CODE-PATTERNS.md, and docs/TESTING.md. Then review the current working tree. Prioritize correctness, security, behavioral regressions, Leo async transition/finalize mistakes, authorization-order issues, public/private visibility leaks, Merkle and freeze-list mismatches, and missing tests. Findings first with file references.

2. Review a Leo feature design before coding

Use /plan. Read AGENTS.md, docs/ARCHITECTURE.md, docs/LEO-ALEO-PATTERNS.md, docs/CODE-PATTERNS.md, and the relevant files under programs/ and test/. Propose the safest implementation plan for <feature>. Include affected programs, async transition/finalize changes, SDK parity implications, required tests, deployment implications, and open questions. Do not edit yet.

3. Implement a Leo feature

Read AGENTS.md, docs/DEVELOPMENT.md, docs/TESTING.md, docs/LEO-ALEO-PATTERNS.md, and docs/CODE-PATTERNS.md. Implement <feature> with the smallest safe change. Preserve repository patterns. Update or add tests. Run dokojs compile and the narrowest relevant tests first, then summarize residual risks.

4. Debug a failing test

Read AGENTS.md, docs/TESTING.md, docs/CODE-PATTERNS.md, and docs/LEO-ALEO-PATTERNS.md. Reproduce the failure in <test file or command>, explain the root cause, fix it, add a regression test if needed, and rerun only the narrowest relevant commands before broadening scope.

5. Review or implement SDK parity work

Read AGENTS.md, packages/policy-engine-sdk/AGENTS.md, packages/policy-engine-sdk/README.md, docs/LEO-ALEO-PATTERNS.md, and the relevant Leo program. Compare the SDK's off-chain hashing, Merkle proof generation, constants, and encoding against the on-chain logic. Call out or fix any parity mismatches and add tests.

6. Ask Codex to interview you before planning

Before proposing a design, interview me. Ask the minimum set of concrete questions needed to remove ambiguity around constraints, Leo visibility rules, authorization flow, test expectations, and deployment impact. Then switch to /plan and propose the implementation plan.

Repo-specific best practices for Leo work

When the task touches programs/**/*.leo, ask Codex to explicitly check:

  • Async transitions vs async functions
  • That mappings are written only in async functions
  • That only public values or commitments cross public async boundaries
  • Authorization order for token-registry style flows.
  • Check that prehook happens before transfer.
  • Check that the prehook future is awaited before the transfer future.
  • Public/private visibility decisions
  • Freeze-list invariants.
  • Check ZERO_ADDRESS sentinel usage.
  • Check index mappings.
  • Check root updates.
  • Check previous root window rules.
  • Block height window checks in threshold-style policy flows
  • Upgradability and multisig assumptions when relevant

Good habit:

  • Ask Codex to inspect both the Leo program and the nearest tests before proposing changes

Repo-specific best practices for tests

When the task touches behavior, ask Codex to:

  • Start with the narrowest test file
  • Prefer devnode first
  • Use agent reporter where possible
  • Avoid full DEVNET=true runs unless needed
  • Keep tests sequential
  • Add regression coverage for every bug fix that changed behavior

Good review prompt for tests:

Read AGENTS.md, docs/TESTING.md, docs/CODE-PATTERNS.md, and the affected tests. Review whether coverage is missing for negative cases, authorization failures, private/public boundary cases, Merkle proof edge cases, initialization requirements, and block-height timing windows.

Suggested workflow by task type

For review

  1. Start codex --profile review
  2. Run /status
  3. Ask Codex to read the relevant repo docs
  4. Run /review
  5. Use /diff for changed files
  6. If findings are interesting, /fork the session to explore fixes without losing the original review

For design / planning

  1. Start codex --profile review
  2. Use /plan
  3. Point Codex to the exact docs and files
  4. Make it list risks, assumptions, affected tests, and rollout impact
  5. Only switch to edit profile after the plan looks correct

For implementation

  1. Start codex --profile edit
  2. Ask it to read the relevant docs first
  3. Ask for the smallest safe change
  4. Require compile and narrow test verification
  5. End with /review

For bug fixing

  1. Reproduce with the smallest test or command
  2. Ask Codex to explain root cause before broad changes
  3. Fix the bug
  4. Add a regression test
  5. Re-run the narrow test
  6. Review the diff

Anti-patterns to avoid

  • Do not start Codex outside the repo and expect it to pick up repo instructions
  • Do not assume linked docs are loaded automatically
  • Do not ask it to run the whole suite first when a single test file can reproduce the issue
  • Do not ask it to parallelize integration tests in this repo
  • Do not jump into danger-full-access unless you truly need it
  • Do not use API-key auth for normal interactive local work if you already have ChatGPT Plus
  • Do not ask for vague output like "take a look"; ask for findings, plan, or implementation with explicit done criteria

Minimal cheat sheet

Install / update

brew install --cask codex
brew upgrade codex

Or:

npm install -g @openai/codex
npm update -g @openai/codex

Start sessions

codex --profile review
codex --profile edit

One-off overrides

codex --profile review -m gpt-5.4 -c 'model_reasoning_effort="high"'
codex --profile edit -s workspace-write -a on-request

Useful repo commands

dokojs compile
npm test
npm run test:agent
npm run test:select:agent ./test/merkle_tree.test.ts
npm run format:fix

Useful slash commands

/status
/model
/fast
/plan
/review
/diff
/mention
/resume
/fork
/debug-config

Official sources

Repo docs to explicitly ask Codex to read

  • AGENTS.md
  • docs/DEVELOPMENT.md
  • docs/TESTING.md
  • docs/LEO-ALEO-PATTERNS.md
  • docs/CODE-PATTERNS.md
  • packages/policy-engine-sdk/AGENTS.md
  • packages/policy-engine-sdk/README.md
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment