Getting started with Codex and CircleCI

Codex is OpenAI’s coding agent, powered by the GPT-5 family of models. It reads your files, proposes edits, and runs commands directly in your local environment. It ships as a desktop app and an open source CLI, and it extends through plugins that connect it to external tools and services.

Like any AI coding tool, Codex is strongest when the code it generates gets validated automatically. A function that looks right in the editor can still break a downstream integration, fail a lint rule, or introduce a regression that only surfaces under test. Continuous integration catches those problems before they ship, making it a natural complement to any AI coding workflow.

This tutorial connects the two. You’ll install the CircleCI plugin for Codex, then use one terminal session to validate config, trigger pipelines, and diagnose failing builds. The examples use the Codex CLI, but you can use the desktop app to get the same results.

Prerequisites

• Node.js 18 or newer, and git
• A sign-in for Codex: any current ChatGPT plan includes Codex access with usage limits, and Free and Go are included for now. An OpenAI API key also works for CLI auth.
• A free CircleCI account and a GitHub account
• The demo repo used in this tutorial: chunk-dataforge-demo

Installing Codex

Install with npm:

npm i -g @openai/codex

Then start it:

codex

Codex prompts for sign-in on first run. ChatGPT account or API key both work. The CLI runs on macOS, Linux, and Windows.

What the plugin adds over the bare CLI

Codex can already run the CircleCI CLI without any plugin. It has a shell, the circleci binary is on your PATH, and asking it to check a pipeline will get you an answer. That path works, and if you want the smallest possible setup, it is a legitimate place to stop.

What it doesn’t give you is judgment about CircleCI specifically. Codex has to discover the command surface on its own: probing --help, guessing which flags matter, and inventing an approach to diagnosis each time you ask.

The plugin closes that gap by shipping the knowledge alongside the commands:

• Command knowledge. The CLI skill carries the day-to-day loop and the details that are easy to get wrong: that most commands infer the project and branch from your git remote and checkout, that private orbs need validate --org, that -n previews upcoming config changes.
• A diagnosis method, not just log access. The builds skill works a sequence: find the first failing step rather than every downstream failure, classify the cause as config, toolchain, dependency, test regression, or external, apply the smallest viable fix, then define what a successful rerun should look like.
• Guardrails. It is told not to hide deterministic failures behind blanket retries, and not to fold unrelated refactoring into an incident fix. Those are the habits that make an agent’s CI changes reviewable.
• Routing. Because each skill declares what it is for, a prompt about a failing build reaches the diagnosis skill rather than a generic shell attempt.

The practical difference is fewer wasted turns and less improvisation on your pipeline. Same commands underneath, better decisions about which ones to run.

Setting up the CircleCI plugin

Three steps: install the CircleCI CLI, install the plugin in Codex, then point both at a project.

Install and authenticate the CircleCI CLI

The plugin drives many operations through the local CircleCI CLI, so install it before the plugin.

With Homebrew on macOS or Linux:

brew install circleci

WinGet, Snap, Debian, and RPM packages are available too. The CLI installation instructions cover each one.

Then log in:

circleci auth login

That opens the CircleCI authorization page in your browser. Once you approve the request, the CLI saves the credential to your system keyring and uses it automatically for every later command, so there is no API token to create, copy, or paste. If you don’t have a CircleCI account yet, circleci auth signup runs the same browser flow against the signup page instead.

Verify:

circleci auth me

Install the plugin in Codex

Back in Codex, open the plugin browser:

/plugins

Find CircleCI in the directory, install it, then restart Codex so the install takes effect.

The plugin ships a set of CircleCI skills, and the ones this tutorial exercises are build diagnosis, config review, and everyday CLI operations. It also carries skills for CircleCI Smarter Testing and for onboarding a new project, which are outside the scope of this guide.

Clone and connect the demo repo

With the tooling in place, get the demo project onto your machine and into CircleCI so there is real pipeline data to work with:

1. Fork github.com/CIRCLECI-GWP/chunk-dataforge-demo on GitHub
2. Clone your fork locally, then cd into it and start codex from inside the checkout. Most CircleCI commands infer the project and branch from your git remote and checkout, so the working directory matters.
3. In the CircleCI web app, select Home in the sidebar
4. Select Create Project or Set up a project, whichever button your organization shows, connect the fork, and let the initial pipeline run

Whether that first build passes or fails doesn’t matter. The point is generating some pipeline data to query.

If your CircleCI organization slug starts with circleci/ rather than gh/ or bb/, also run circleci project link in the checkout. It records the project in .circleci/info.yml so later commands resolve it without re-deriving it from the git remote.

Using the CircleCI plugin

Ask for what you want in plain language. Each skill’s description is written to match the intent behind a prompt, so a request that is clearly about CircleCI reaches the right skill without any special syntax:

Check the latest CircleCI pipeline run

Validating config before pushing

Review the CircleCI config for this repo

The plugin runs circleci config validate, which reports YAML, schema, and compilation errors and points at the part of the config that broke. That beats discovering a YAML typo after a push triggers a failed build.

Optimization questions work the same way:

Suggest improvements to my CircleCI config for faster builds

Typical suggestions cover caching, parallelism, test splitting, and image choices.

Triggering pipelines from the terminal

Run a CircleCI pipeline on my current branch

Codex reads the Git remote and branch, triggers the pipeline through the CLI, and reports the run it started. You can also name the branch explicitly. The next section needs a failure to work with, and the demo’s test/broken-batch-processing branch fails deterministically, so it is the reliable choice. The demo’s main sometimes carries a deliberate break too, in which case you already have one:

Trigger a CircleCI pipeline on the test/broken-batch-processing branch

Investigating build failures

Diagnose the latest failing CircleCI build

Codex pulls logs from the failed job, classifies the failure as transient or deterministic, identifies the step that broke, and recommends targeted fixes or reruns. With the failing branch checked out, it has both the failure and the code in one session and can apply the fix directly.

A natural follow-up extends the workflow into a closed loop:

Fix that issue and run the pipeline again. Let me know when it passes.

Codex edits the code, commits and pushes, triggers a new build, and reports back. If there is another failure, Codex keeps iterating through different changes, aiming for a green pipeline.

You can also ask for the failure report directly:

Show me the failure report for the latest run on the test/broken-batch-processing branch

That request lands on circleci run get --branch test/broken-batch-processing --failure-report, which prints a condensed summary of every failed step in that run, written to be read by an agent rather than scrolled by a human. Note that the underlying commands identify a run by UUID or by branch, never by a web address.

Prompt your agent directly from the CircleCI UI

Everything so far starts in the terminal. CircleCI can also start the conversation for you, handing an agent a failure with the ids and commands already filled in.

In the CircleCI web app, select Pipelines in the sidebar and find a failed pipeline. Beneath the pipeline title is the workflow row, and at the end of it a wrench icon opens a small menu:

Select Copy Fix Prompt. As the tooltip says, that copies a prompt to your clipboard for use with your preferred AI coding agent. What lands on the clipboard looks like this:

If the circleci CLI is not installed/authenticated, ask permission before
setting it up (see https://cli.circleci.com/).

Check out branch main. Pipeline 27176347-6912-4b9b-9e66-27422503b5fb failed; run "circleci run get 27176347-6912-4b9b-9e66-27422503b5fb --failure-report"
to see the failed steps.

Review the output, identify the root cause(s), and fix the code so the pipeline passes.

Paste that straight into Codex. It saves the agent the two steps it would otherwise have to guess at: which run failed, and which command explains why. The run is identified by UUID, the branch is named, and --failure-report is the flag that returns a condensed summary written for an agent to read. Codex checks out the branch, pulls the report, and starts on the root cause.

The menu’s other option, Fix with CircleCI, hands the same failure to CircleCI’s own agent instead of a local one.

Working on the codebase

The same session handles ordinary coding work. Read-only prompts explore without touching anything:

Explain this codebase. What are the main modules and how do they relate?

Edit prompts propose a change and print the diff before applying it. And test runners, linters, and build commands all work the same way:

Run the test suite and tell me which tests pass.

That’s the core loop: read, propose, run, approve.

Troubleshooting

• The plugin doesn’t seem active. Restart Codex. A plugin install needs a fresh session before its skills load.
• CircleCI requests return CLI errors. The plugin routes most operations through the local circleci binary. Confirm it is on your PATH with circleci version, and confirm you’re signed in with circleci auth me.
• The plugin can’t find your project. Check the Git remote with git remote -v, confirm the project is connected in the CircleCI web app, and confirm the account from circleci auth me has access to it. You can also name the project in the prompt: get CircleCI build status for gh/my-org/my-repo.
• Authentication errors. Run circleci auth login again to replace the stored credential.

Bringing it together

Codex covers what happens at the keyboard. CircleCI covers what happens after the push: running test suites, validating builds, shipping changes. The plugin keeps both sides accessible from one terminal session.

The fastest way to put any of this into practice is on a real project. Sign up for a free CircleCI account and connect a repo to start running pipelines today.