Lightweight scripted AI workflows for engineering teams

AI agents are often presented as interactive assistants, but they can also be invoked programmatically. When you have repeatable tasks such as updating version numbers, generating changelogs or reviewing diffs, you can script those actions using the headless modes of modern coding agents. This post focuses on the Codex CLI command codex exec, which runs the agent non-interactively. Similar patterns apply to other tools with scripting support.

Why script AI workflows

Interactive sessions are great for exploring a new problem, but automation shines when tasks repeat. In CI pipelines, pre-commit hooks or cron jobs you want predictable behaviour: the agent reads the repository, performs a task and exits with a clear result. Scripting reduces manual effort, ensures consistency and lets you integrate AI into existing automation. Because the agent runs headless, it can be part of your build system without requiring a human at the keyboard.

Running Codex in headless mode

Codex CLI offers codex exec (alias codex e), a command that runs Codex non-interactively for scripted and CI use. You pass a prompt, and Codex reads your repository, plans the changes, executes them and exits. By default it streams progress to stderr and prints only the final agent message to stdout. You can write that final message to a file with the --output-last-message flag, and emit newline-delimited JSON events with the --json flag when you want to parse progress programmatically.

Basic one-shot commands

You can call codex exec directly from a script. For example, to update a version number in a project file:

codex exec "Update the version number in package.json to 2.1.0"

import subprocess
subprocess.run(["codex", "exec", "Update the version number in package.json to 2.1.0"], check=True)

Codex parses the prompt, modifies package.json, runs any necessary commands and exits. Because the final message is printed to stdout, you can capture or log the result.

Controlling autonomy

Headless runs respect the same sandbox and approval controls as interactive sessions. Set the file system access level with --sandbox, which accepts read-only, workspace-write or danger-full-access. Set the approval behaviour with --ask-for-approval, which accepts untrusted, on-request or never. For a guarded run you can combine a writable workspace with on-request approvals (the official guidance prefers never for fully unattended, non-interactive runs):

codex exec --sandbox workspace-write --ask-for-approval on-request "Add a unit test for the parse_config function"

You can also set defaults in ~/.codex/config.toml using the model, model_reasoning_effort, approval_policy and sandbox_mode keys, so individual scripts stay short.

Integrating with CI/CD

codex exec fits naturally into CI pipelines. On GitHub Actions, the official Codex GitHub Action is the recommended path: it installs and authenticates Codex for you, with the API key supplied from a repository secret rather than exported as a job-level variable. Note that this is a YAML workflow file, not a shell command:

jobs:
  update_changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt: "Update CHANGELOG for the next release based on commits since the last tag"

For other CI systems such as GitLab CI/CD or Jenkins, install the CLI with npm install -g @openai/codex and scope the API key to the single invocation rather than exporting it for the whole job.

Batch processing

You can combine shell loops with codex exec to perform the same action on multiple files. For example, adding type hints to every Python file in a directory:

for file in src/utils/*.py; do
  codex exec "Add type hints to all functions in $file"
done

import glob
import subprocess
for file in glob.glob("src/utils/*.py"):
    subprocess.run(["codex", "exec", f"Add type hints to all functions in {file}"], check=True)

Get-ChildItem -Path src/utils -Filter *.py | ForEach-Object {
    codex exec "Add type hints to all functions in $($_.FullName)"
}

Each invocation of codex exec is isolated. Codex reads the specified file, applies the transformation and stops. For idempotent tasks this pattern is efficient and easy to reason about.

Tips for scripted workflows

1. Define completion criteria. Write prompts that describe both the action and what counts as success, for example "Refactor this module to remove global variables and make sure the existing tests still pass."
2. Review diffs. Even in headless mode, run a diff or a separate review step after the agent executes to confirm that the changes meet your standards.
3. Use AGENTS.md for standing instructions. Codex loads AGENTS.md from ~/.codex, the project root and each directory down to the working directory, so your scripts inherit conventions without repeating them. Closer files override more distant ones.
4. Combine with other tools. codex exec can sit inside a larger pipeline that includes linting, static analysis and deployment. Use exit codes to handle errors gracefully.

Conclusion

Lightweight scripting turns AI coding agents into practical automation tools. The headless codex exec command makes it easy to embed AI assistance into CI pipelines, cron jobs and simple scripts. By writing clear prompts, defining completion criteria and reviewing outputs, you can use AI to perform mundane tasks consistently and free your team to focus on higher value work.