Understand the codex-exec bridge
Codex has a headless mode: codex exec. You send a request, it works on it, and returns the final answer. That's a CLI, step 3 on the route ladder.
The kit wraps that command in a short script: runtime/pontes/codex-exec.sh. É a bridge. It already chooses the model, applies the policy, and returns only the relevant text.
Claude remains the decision-maker. Codex becomes a colleague Claude consults, like asking for another team member’s opinion.
🆕 New here? Four words from this module
- Script — a text file with commands in sequence. You run the file, and it executes everything in order.
- stdin (standard input) — the “pipe” through which a program receives text. The bridge sends your request to Codex through this pipe.
- Sandbox — a sandbox: the enclosed space where Codex works. It determines whether it can only read or can also write files.
- Output — what the program prints in the terminal. When there’s an error, it also returns a number (for example, “exit code 2”).
How to read the diagram: the blue box in the middle is the bridge. All the rules live in it: which sandbox applies, how long to wait, and what to return. The dashed arrow below is the response going back to Claude.
the official method (CLI)
codex-exec.sh
only reads, or reads and writes
uses quota, not API
Test the bridge by itself
Before putting Claude in the middle, test the bridge directly in the terminal. If it fails here, it’ll fail inside the agent too, and then it’s hard to tell who’s at fault.
The test is as simple as possible: ask Codex to respond with a single word. If the word comes back, the bridge, login, and quota are working.
Check your Codex login
The doctor in module 1.2 has to show codex ok and "Logged in using ChatGPT". If it doesn't show up, run codex login.
Give the script execution permission
O chmod +x marks the file as "ready to run". You only need to do this once.
Ask for the PONG
One sentence, one word back. It's proof that recipe R1 works.
In the terminal, from inside the kit folder:
chmod +x runtime/pontes/codex-exec.sh runtime/pontes/codex-exec.sh "Responda apenas PONG"
Result confirmed in CHANGELOG 0.1.0:
PONG
PONG. If you see codex falhou; log:, read the following lines and go to topic 6.💡 Why such a silly test
A one-word request uses almost no quota and gets a quick response. It helps distinguish a bridge problem (login, installation) from a request problem. Only after that should you ask for anything serious.
through the subscription
can run
the proof of R1
before the agent
Ask for a second opinion from inside Claude
Now for real-world use. Open Claude and ask it to consult Codex. Claude runs the bridge, reads the response, and compares it with its own.
Why is this worth it? Rule 3 of the ROTEAMENTO.md responds: review by another one model catches errors the same model doesn’t see. Two different perspectives make mistakes in different places.
Open claude in the kit folder and paste:
Use runtime/pontes/codex-exec.sh to ask Codex to review the README.md file: what might confuse a beginner? Then compare its feedback with your opinion.
runtime/pontes/codex-exec.sh and, in its response, separates what Codex said from what it thinks.How to read the diagram: the same file follows two independent paths. The value is in the box on the right: what only one of the two pointed out is exactly what you wouldn't have seen by asking just one model.
Clara can use the same idea with her data. She asks Claude: “Use runtime/pontes/codex-exec.sh to ask Codex to check whether runtime/exemplos/agenda.csv there are two appointments at the same time with the same provider. Then check it yourself too.”
✓ It’s okay to ask for a second opinion
- ✓ Review text intended for a client or team
- ✓ Check an account or an important spreadsheet
- ✓ Before a decision that's hard to undo
- ✓ When Claude seems too confident
✗ Not worth it
- ✗ Trivial task that a model can handle on its own
- ✗ Every question, out of habit: uses quota on both sides
- ✗ When you won’t read the comparison
- ✗ To “break a tie” without looking at the evidence
routing rule 3
Codex gives its opinion
bridge pattern (N4)
what only one saw
Let Codex modify files
By default, the bridge uses the sandbox read-only: Codex reads, but doesn't write anything. That's the "read" ceiling of the POLITICA.md, level N4.
When you want it to create or modify files, pass two more arguments: the folder and the sandbox workspace-write. This raises the action to "modify," level N3: it does it and notifies you.
| Sandbox | Codex can | Action in POLITICA | Level |
|---|---|---|---|
read-only (default) | read files in the folder | Read a file, page, or spreadsheet | N4 |
workspace-write | read and write inside the specified folder | Create/modify project file | N3 |
What to look for in the table: there are only two lines. Any other sandbox doesn’t cross the bridge, as you’ll see in the next topic.
In the terminal, from inside the kit folder:
runtime/pontes/codex-exec.sh "Crie notas.txt com a palavra OK" "$PWD" workspace-write cat notas.txt
Result confirmed in CHANGELOG 0.1.0 (the cat notas.txt):
OK
cat notas.txt shows OK. O "$PWD" it’s the folder you’re in: Codex only writes inside it.⚠️ Recording it is your decision, not the agent’s
The recipe is clear: modify files (N3) only if you ask. Don’t let Claude change the read-only by workspace-write "to speed things up". And point to the right folder: the "$PWD" from the project, never your entire personal folder.
default, N4
record, N3
the current folder
the proof
See the policy reject the dangerous action
Codex has a third sandbox, danger-full-access: full access to the machine. The bridge won't allow it. Before calling Codex, it checks the sandbox and stops immediately if it isn't one of the two allowed options.
This is the policy written in code, not in a polite request to the agent. Even if someone asks, the command never reaches Codex.
How to read the diagram: the gatekeeper comes before Codex. The blue arrows pass through; the red one returns with the message and exit code 2, without Codex ever being called.
In the terminal, from inside the kit folder:
runtime/pontes/codex-exec.sh "x" . danger-full-access
Result confirmed in CHANGELOG 0.1.0 (the message, with exit code 2):
sandbox recusado pela POLITICA
✓ The bridge accepts
- ✓
read-only, when you don’t say anything - ✓
workspace-write, when you ask - ✓ Any folder you specify in the 2nd argument
✗ The bridge refuses
- ✗
danger-full-access - ✗ Any sandbox name outside the list
- ✗ Call without any request (it shows the “usage”)
💡 Rule that applies to every bridge
Put the limit inside the bridge, not just in the request text. The agent can forget an instruction; a line of code that refuses won’t. The “did it refuse?” test matters just as much as the “did it work?” test.
Adjust the model, timing, and common errors
The bridge has two settings, made by environment variable: a named value that you define in the terminal before the command, and that the script reads.
The model’s default is gpt-6-luna, the "lower" level of the ROTEAMENTO.md. Starting with the smallest saves quota. Only move up if the response isn't good enough.
| Variable | Default | What for |
|---|---|---|
CODEX_MODELO | gpt-6-luna | another level of the ROTEAMENTO.md (in Codex: gpt-6-sol executor, gpt-6-astra top and super) |
CODEX_TIMEOUT | 600 | seconds before giving up |
What to look for in the table: model names change over time. The ROTEAMENTO.md asks you to check with codex --help and update the table.
Common errors ("If you get an error" section of R1)
It gets stuck without responding
The request needs to go through stdin with - at the end, otherwise Codex keeps waiting for more text. The bridge already does this; the problem comes up when someone calls codex exec directly, without the bridge.
sandbox recusado pela POLITICA
Only read-only e workspace-write are accepted. Check the 3rd argument.
The test needs network access
The Codex sandbox blocks the network, including the local network. If the test needs to start a server, add -c sandbox_workspace_write.network_access=true in the bridge and note it in LIMITES.md.
💡 Take notes before you continue
The bridge already has a line in the CAPACIDADES.md: "Codex CLI · CLI · 3 · runtime/pontes/codex-exec.sh · read (N4)". If you changed the network sandbox, the record goes in the LIMITES.md, with a date. That way, no one finds out about the change only when something breaks.
Quick test (optional): Clara wants Codex to only read the calendar and give an opinion. Which bridge call should she use?
start with the smallest
600 seconds
otherwise it freezes
adjustment noted
🎓 Module summary
Next module:
2.2 — Your first MCP bridge