Hacking Subagents Into Codex CLI — Brian John, BetterUp

How do you move between coding tools without giving up the delegation workflow that makes them useful? Brian John approaches that problem as a principal full stack engineer responsible for AI enablement in BetterUp’s R&D organization: helping people work faster and produce higher-quality results. At the time of the talk, he had spent more than eight years at BetterUp, which he describes as using AI from its beginning. Its mission—helping people live with purpose, clarity, and passion—also frames his invitation to engineers interested in working with LLMs.

Claude Code is his daily driver, and subagents are a regular part of his work. But those workflows create a dependency: switching tools can mean losing the ability to delegate in the same way. Codex CLI’s models look appealing to him, and he wants to use them without being locked into either one tool or one model family.

The main benefit is context isolation. The parent gives a subagent a problem; the child spends its own tokens investigating it and returns only the answer. The intermediate work does not fill the parent’s context window. John credits Dex Horthy’s context-engineering talk with changing how he works, particularly in large codebases. Delegation is therefore more than assigning a role: it controls how much working material the main agent has to carry forward.

The implementation starts with a small observation: a subagent can be another instance of the main agent. There is no need to build a separate agent runtime. The parent Codex session can invoke a wrapper that starts a child through codex exec.

The complete execution loop has four steps:

1. The parent calls the wrapper with a delegated task.
2. The wrapper selects the agent definition, builds its prompt, and launches child Codex.
3. The child performs the task and writes its final answer into a file.
4. The wrapper reads that file and prints its contents to stdout, where the parent receives the result.

The answer file is the handoff between child and wrapper; stdout is the handoff between wrapper and parent. The design is small, but John’s first attempts immediately run into sandbox errors.

John does not solve those errors by disabling permission checks. The hard part is finding the minimum permissions that let the nested process work. In his setup, the parent needs at least --sandbox workspace-write to run the Codex command. The child then encounters another boundary: the OpenAI credentials in the user’s home directory sit outside the workspace accessible under the parent’s sandbox.

The child’s own settings cannot make the parent’s filesystem restrictions disappear. John therefore also disables the rollout recorder, the logging mechanism whose filesystem access causes trouble inside the enclosing sandbox.

Before proceeding, he evaluates the arrangement using Meta’s Agents Rule of Two. The framework examines three properties: processing untrusted input, accessing sensitive systems or private data, and changing state or communicating externally. Its security boundary depends on restricting at least one of these properties; allowing all three together calls for supervision.

John assumes his particular workflow does not process untrusted input. It does access private data through a proprietary codebase, and it can both change state and communicate externally. He considers the state changes in his environment relatively low risk and says the external communication is limited to OpenAI’s API endpoint. That is a conditional assessment of his system: lower risk does not mean no risk, and a different input source or set of accessible systems changes the assessment.

A working wrapper is not enough: the parent needs to know it exists. The repository’s invocation instructions in AGENTS.md supply three parts of the contract:

• How: map a request for a named subagent to the wrapper invocation.
• When: delegate when the user asks, or when the parent judges delegation useful.
• What: list the available subagents and their responsibilities.

This turns a natural-language request to use a subagent into a concrete action the parent can perform.

John then opens the small BetterUp Codex CLI Subagent Demo. Its agent definitions contain a name, a reasoning-effort setting, and a prompt, much like Claude Code’s subagent definitions. He describes choosing lighter, medium, or higher reasoning according to the work. The two toy agents make that distinction easy to see: one counts words, while the other writes supplied text to a file, a task that needs little reasoning.

John describes the command wrapper as 72 lines. It accepts the inputs, calls the Python AgentExecutor, and prints the returned answer to stdout. The executor owns the process details: child permissions, reasoning effort, and rollout-recorder settings. Keeping those details together leaves the outer command focused on input and output.

The invocation contract has an unusual detail: the parent writes the agent name into agent.txt and the user’s query into query.txt before running the wrapper. Passing both values as command-line arguments would be more obvious, but it would change the command on every request.

In the permission system John demonstrates, an exactly unchanged command can retain approval, while changing its arguments prompts for approval again. Moving variable data into files lets different tasks use the same invocation. The following Python example prepares a word-count request through that file interface:

from pathlib import Path
import subprocess

Path("agent.txt").write_text("word-counter\n", encoding="utf-8")
Path("query.txt").write_text(
    "Count the words in this text: Small wrappers preserve useful workflows.\n",
    encoding="utf-8",
)

subprocess.run(
    ["timeout", "600", "bin/agent-exec"],
    check=True,
)

The sentence can change without changing timeout 600 bin/agent-exec. This separates the command being approved from the task data it will read.

The reusable approval is consequently approval to invoke the wrapper with changing file contents, not approval of one immutable query. Bypassing permission checks would remove the repeated prompts too, but that is not the operating mode John chooses.

A second wrapper prepares the parent session. It copies Codex home files from the user’s home directory into a workspace subdirectory so the nested process can access them. John describes this as syncing the files, pointing CODEX_HOME at the new location, and launching Codex. In the inspected repository, those responsibilities are split: bin/codex copies the files into tmp/codex-home, while AgentExecutor sets CODEX_HOME for the child. The accessible copy resolves the earlier credential-location problem.

The launch shown uses --full-auto. John associates it with workspace-write permissions but does not recall its precise approval policy. These flags and approval behaviors belong to the historical demonstration: the current CLI reference marks --full-auto deprecated, and current Codex supports native parallel subagents. The wrapper walkthrough explains how this setup worked without treating its historical limitations as current requirements.

With the prepared session running, John asks Codex to use the word-counter subagent. The parent recognizes that it needs the agent-execution wrapper, writes the agent name and query into their files, and requests permission to run the command. John chooses the option to approve it without asking again for that command. This first invocation establishes the approval that the next task will reuse.

The demonstrated workflow runs serially: the parent waits while the child does its work. John finds it slower than his Claude Code workflow and interprets Codex as better suited to hands-off, unattended work, while Claude Code feels more iterative to him. He accepts that tradeoff for his usage. The child’s result then appears on stdout, and the parent turns it into the answer shown to the user.

The second request uses the file-writer subagent. Codex writes a new agent name and query into the same input files and invokes the same command. This time there is no permission prompt. The task has changed, but the approved command has not.

The command uses timeout 600, giving the outer invocation ten minutes. John reports that large-codebase tasks can take ten minutes and sometimes as long as twenty minutes. That motivates allowing more time for substantial repository work. There is also an implementation detail to account for: AgentExecutor passes its own 600-second timeout to subprocess.run, so increasing only the outer timeout would leave the internal limit in place.

John reports that the easy file-writing example took about 40 seconds. These durations are observations from his usage and demonstration, rather than controlled comparisons across models or repositories. He finishes by checking that the requested file was written—the concrete output matters beyond the parent’s success message.

The recording closes with pointers to the open-source code and BetterUp, plus email and X direct messages for questions. The proof of concept ends at a useful boundary: two different delegated tasks, one reusable wrapper approval, and a file checked after creation.