Knowledge, Context and Agentic Engineering for Knowledge Work
← Module 04 · Agentic Engineering

Codex CLI introduction

This tutorial introduces the Codex CLI as an AI harness for bounded work in a local repository. It connects repository instructions, tool permissions, inspectable changes and verification.

Sources and product details checked 25 August 2026

Use a disposable practice repository without confidential files.Complete the Preparation path before beginning.

The Codex CLI connects a model with a bounded local workspace, tools and evidence that can be reviewed.

Step 1

Identify the harness and its working surface

The Codex CLI is a terminal-based AI harness that works with project files, repository instructions, tools and execution feedback.

  1. Locate the workspace that defines the authorised file boundary.
  2. Identify the active model and the tools exposed by the harness.
  3. Require evidence through diffs, commands and reported checks.
  4. Keep human acceptance as an explicit state after technical validation.

Check: you can distinguish the model, Codex, the workspace and the evidence used for review.

Official Codex CLI documentation · Codex bootcamp 101

A known repository state makes the first result observable and reversible.

Step 2

Prepare one bounded repository

  1. Use a disposable repository that contains no confidential files or credentials.
  2. Run git status --short outside Codex and record the starting state.
  3. Locate the repository instructions and the commands that check its current artefacts.
  4. Confirm the current account or workspace access required by the chosen Codex surface.

Check: the repository boundary, starting Git state and available checks are known before Codex starts.

Product prerequisites checked 25 August 2026 against the official CLI documentation.

The official installation route closes with a visible version and a read-only start.

Step 3

Install the Codex CLI through the maintained route

  1. Follow the current installation route in the official Codex CLI documentation.
  2. Open a new terminal when the installation changes the executable search path.
  3. Run codex --version and record the version used for the exercise.
  4. Start the CLI with codex --sandbox read-only from the practice repository.

Check: Codex reports its version and opens inside the intended repository with the read-only sandbox selected.

Installation command and CLI flags checked 25 August 2026. Open the official CLI guide.

The working surface should expose the repository, model route and current task boundary.

Step 4

Confirm the workspace and active model route

  1. Confirm the current repository and branch before supplying the task.
  2. Identify the active model or provider shown by the CLI.
  3. State the files that may be inspected and the evidence expected in return.
  4. Treat codex --oss --local-provider ollama and codex --oss --local-provider lmstudio as optional local-provider routes. This introduction uses the standard provider route.

Check: the repository, branch, model route and task boundary can each be named from the visible session state.

--oss and --local-provider checked 25 August 2026 in the official Codex CLI reference.

Codex combines a global instruction file with project instructions from the repository root towards the working directory.

Step 5

Read the complete instruction hierarchy

Codex first loads one global file from CODEX_HOME: AGENTS.override.md takes precedence over AGENTS.md. It then searches each directory from the project root to the working directory, again preferring AGENTS.override.md. Instructions are combined root-down, so deeper guidance applies later.

  1. Identify the global AGENTS.override.md or AGENTS.md in CODEX_HOME.
  2. Locate the applicable instruction file in every directory from the project root to the current directory.
  3. Read the effective chain in order and assign each rule to its scope.
  4. Use /init only when the repository needs a reviewed starting instruction file.

Check: you can name the global and project instruction files that apply to the current directory and explain their precedence.

Official AGENTS.md guide, checked 25 August 2026.

Sandbox, approval policy and task scope are separate controls that must agree.

Step 6

Inspect tools and permission boundaries before action

The sandbox sets the technical boundary for commands. The approval policy determines when Codex must stop and request authorisation before crossing that boundary.

  1. Open /permissions and inspect the active sandbox and approval policy.
  2. Keep the first exercise in the read-only sandbox and authorise file inspection only.
  3. Review every requested permission or sandbox expansion against the task and repository boundary.
  4. Require Codex to report commands, observed outputs and remaining uncertainty.

Check: the displayed permissions permit inspection and exclude workspace changes during the first exercise.

Sandboxing and agent approvals checked in the official OpenAI documentation on 25 August 2026.

Codex supplies distinct mechanisms for procedures, connections, delegation and file isolation.

Step 7

Locate the extension and parallel-work mechanisms

Skills and MCP

Skills provide maintained task procedures. Model Context Protocol connections expose external resources and tools whose scope must be inspected.

Subagents and worktrees

Subagents return evidence from bounded contexts. Worktrees isolate concurrent file changes before integration.

Check: each enabled mechanism has a defined function, source, scope and verification route.

Skills · MCP · Subagents · Worktrees

The first task ends with evidence from Codex and an independent Git check.

Step 8

Run one reversible repository orientation

Ask Codex to inspect the repository, identify applicable instructions and explain its maintained checks. Keep the task inside the read-only sandbox.

  1. Request a compact repository summary with direct file references.
  2. Ask Codex to name the applicable global and project instruction files and existing check commands.
  3. Inspect the cited files and compare the answer with the repository state.
  4. Exit the session and run git status --short outside Codex.

Check: the summary is supported by repository evidence and the final Git state matches the recorded baseline.

The working loop follows the source-checked objectives of Codex bootcamp 101.