Codex AI Agent: Automate Coding Beyond CI/CD

OpenAI Codex shipped a GitHub Action for CI pipelines and an Automations feature that runs on a schedule from its own app. Neither one reacts to a Slack message, answers a follow-up question by pinging a human, or lets another AI agent call it mid-task. Heym's new Codex node turns Codex into exactly that kind of Codex AI agent, and it went live in our own repository yesterday.

The Codex node is a Heym workflow node that runs the OpenAI Codex CLI against a GitHub repository from inside any workflow, triggered by any event, and callable as a tool by another AI agent. It clones the repo, gives Codex a task, and publishes the result as a patch, a commit, or a pull request, all without a CI YAML file.

This guide covers how it actually works: the two ways to authenticate, the seven ways to publish a result, what happens when Codex gets stuck and needs a human, and how to hand a coding task to Codex from inside a larger agent.

Where the Codex node fits next to OpenAI's own tools

OpenAI already ships two ways to automate Codex: a GitHub Action for CI/CD, and an Automations feature inside the Codex app. Both are useful, and neither is built for the same job as a workflow node.

Here is how the three actually compare, checked directly against OpenAI's own documentation the same week this was written.

None of this makes OpenAI's tools worse at their job. A GitHub Action is still the right choice for "run Codex on every pull request." The gap is a workflow node that reacts to anything else and can be delegated to by a larger agent, which is what the rest of this guide covers.

Authentication: Sign in with ChatGPT, isolated from the rest of your workflow

The Codex credential in Heym supports two authentication modes. Sign in with ChatGPT runs a PKCE OAuth flow, a variant of the OAuth login standard that proves the request came from the same client that started it, without a client secret that could leak. You click sign in, authorize in your browser, and paste the resulting localhost:1455 redirect URL back into Heym. Runs made this way use your ChatGPT Plus or Pro subscription instead of billing per token against the API.

Access token mode accepts a Codex access token directly for the local runner. API keys are not accepted for this credential; Codex does not submit tasks to a cloud queue, it runs inside your own Heym instance.

The token itself is handled more strictly than a typical credential. It is written to an isolated auth file that only the Codex process reads, refreshed automatically as it nears expiry, and, unlike every other credential type in Heym, deliberately excluded from the $credentials expression context. No other node or expression in the same workflow can read a Codex token, even by accident.

In Docker deployments, Codex runs inside a sibling container built from the same Heym image rather than a separate one, mounting only the Codex workspace and letting Codex's own internal sandbox create the namespaces it needs.

That is a different tradeoff than the tighter, no-capability sandbox Heym uses for Python tool execution: Codex's sandbox needs a bit more room to do its own isolation correctly, so the container grants it rather than fighting it, while still keeping the host's Docker socket and secrets out of reach.

This is also why self-hosting Codex inside Docker is annoying to get right on your own. Codex's CLI uses bubblewrap internally to sandbox the commands it runs, and bubblewrap needs to create its own Linux namespaces. A plain Docker container usually blocks that, which is where the bwrap: No permissions to create a new namespace error most self-hosters eventually hit comes from. Heym's Codex container ships with the specific capabilities bubblewrap needs already granted, so that error never shows up in the first place.

The seven publish modes

Once Codex finishes a task, how the result reaches your repository is a separate decision from the task itself.

diff_only and patch_artifact are the safe defaults while you are still trusting the setup: nothing touches your remote until you review the patch yourself. draft_pr is the practical default once you trust it, because a human still merges. direct_commit only makes sense on a low-stakes branch or a repository where every commit already goes through other checks.

When Codex needs a decision, it asks a person

A coding agent occasionally hits a fork in the road that it should not resolve alone: which of two valid approaches to take, whether a breaking change is acceptable, what a vague requirement actually means. Codex can return a needs_input status instead of guessing.

When that happens, Heym pauses the workflow at that step and exposes a question output. Wire that into a Slack or Send Email node, and Heym generates a public follow-up link for the reviewer. Once they answer, Heym resumes the same execution snapshot and the same Codex thread, so the task continues instead of restarting.

The hold expires after 168 hours if nobody answers, the same window Heym uses for human-in-the-loop approvals elsewhere on the canvas, though the two use separate mechanisms under the hood so a Codex follow-up does not depend on a HITL node being present in the workflow.

If you attach the Codex node as a tool on an Agent node instead of running it as a standalone step, a needs_input result is returned straight to the calling agent rather than pausing the whole workflow, so the agent can refine the request and try again on its own.

Using Codex as a tool for another agent

The Codex node does not have to sit alone on the canvas. Attach it to an AI Agent node's tool handle, the same way you would attach a Slack or HTTP node as a tool, and the agent gains the ability to delegate coding work as one option among several.

Mark the fields the agent should control at call time with the agent-provided toggle. On the Codex node, that applies to Repository URL, Base Branch, Task Prompt, Branch Name, and Setup Command. The Codex Credential, GitHub Credential, Model, Timeout, and Publish Mode stay fixed by whoever built the workflow, so an agent can decide what to ask Codex to do without also deciding which credentials or model that costs money to run.

This is the composition OpenAI's own tooling does not offer today: an orchestrator agent that triages an incoming bug report, decides it is a real code fix rather than a support question, and calls Codex to produce a draft pull request, all inside one workflow. The Agent-Guided Codex PR Dispatcher template is a ready-made version of this pattern. The same pattern extends to adversarial code review: a Codex-authored PR is exactly the kind of change a second agent should check before a human ever sees it.

A concrete build: bug report to draft PR

A minimal version of that pattern: a Slack slash command triggers the workflow, an LLM node classifies the message as a bug report or a question, and a Condition node routes bug reports to the Codex node with the reporter's message as the task prompt and draft_pr as the publish mode.

A Slack node posts the resulting PR link back to the channel. If Codex cannot finish without clarification, the question output routes to the same Slack channel instead of a second node, so the reporter answers where they already are.

None of this requires touching CI configuration or keeping a laptop's Codex app open. The workflow runs the moment the Slack command fires, whether that is once a day or fifty times. The Codex PR Fix Agent template starts from exactly this shape if you want to import it instead of building it from scratch.

Cost: subscription vs. metered

Every Codex API call through the GitHub Action or a bare access_token integration bills per token against your OpenAI usage. Signing in with ChatGPT routes runs through your existing Plus or Pro subscription instead, which matters most for teams already paying for ChatGPT seats and running Codex often enough that metered API costs would add up.

The tradeoff is the same one covered in more general terms in AI agent cost optimization: the cheapest run is the one billed against a seat you already have, not a new line item.

"We shipped the sandboxing for this the same way we approach every process that runs code we did not write ourselves: assume it needs room to fail safely, not room to do anything it wants. Codex gets its own container and its own credential path, and nothing else on the canvas can see either one." — Mehmet Burak Akgün, Founding Engineer, Heym

Frequently Asked Questions

Can OpenAI Codex be used as an AI agent tool? OpenAI's own documentation does not describe Codex as a callable tool for another AI agent or orchestrator; its Automations feature runs independently on a schedule. In Heym, the Codex node can be attached directly to an Agent node's tool handle, so a higher-level agent can decide mid-task to delegate a coding job to Codex, read the result, and continue. Five of the node's ten fields (repository URL, base branch, task prompt, branch name, and setup command) can be set dynamically by the calling agent; the credential, GitHub credential, model, timeout, and publish mode stay fixed by whoever configured the workflow.

How is this different from the OpenAI Codex GitHub Action? The official GitHub Action runs inside a CI/CD job, so it fires on GitHub repository events such as a push, a pull request, or a manual workflow dispatch, and it requires a hand-written YAML file plus an API key billed per token. Heym's Codex node runs inside a workflow that any trigger can start: a webhook, a Slack message, an inbound email, a cron schedule, or a database change. There is no YAML to write, and the node can also authenticate with a ChatGPT Plus or Pro subscription instead of a metered API key.

Does Codex Automations do the same thing as Heym's Codex node? No. OpenAI's Codex Automations feature runs recurring tasks on a schedule (daily, weekly, or custom cron) and requires the local Codex app to stay open for project-scoped automations. It checks connected sources like Slack or GitHub by polling rather than reacting to them in real time. Heym's Codex node is triggered by an actual event as part of a hosted workflow, needs nothing running on your machine, and pushes its follow-up questions to a person instead of waiting in an inbox.

What happens when Codex needs more information to finish a task? The node returns a needs_input status instead of failing. Heym pauses that step, exposes a question output you can route to a notification node such as Slack or email, and generates a public follow-up link. When a reviewer answers through that link, Heym resumes the exact same execution and Codex thread, picking up where it left off rather than starting the task over.

Is my ChatGPT or Codex token exposed to the rest of the workflow? No. The Codex credential is deliberately excluded from the $credentials expression context that every other credential type in Heym is available through, so no other node or expression in the workflow can read it. The token is written to an isolated auth file that only the Codex process reads, and Heym refreshes it automatically as it nears expiry.

Can Codex open a pull request automatically, or does it just suggest changes? Both, depending on the publish mode you choose. diff_only and patch_artifact never touch your remote and just return the patch. draft_pr, open_pr, commit_push, direct_commit, and update_existing_pr all push a real branch, with draft_pr and open_pr also opening a pull request (draft or review-ready) for a human to merge.

Conclusion

The gap between "Codex can write code" and "Codex fits into how our team actually works" is triggers and composition, not capability. A GitHub Action only starts from a repository event. Codex's own Automations only start on a schedule and need an app left open. A Codex AI agent built on Heym's node starts from anything you can wire a trigger to, routes its questions to a person instead of an inbox, and can be handed a task by another agent instead of running alone.

Configure a credential, point it at a repository, and connect any trigger. The rest, publishing the result, asking for help when it is stuck, reporting back, is the same workflow logic as every other node on the canvas.

Build with the Codex node in Heym →