Codex

Codex gets a skill, five hooks and a permission profile. The profile lets commands in Codex's sandbox write where a search records and reach only the search hosts, so a search runs and is recorded without opening the network to anything else.

Install

Setup finds Codex when codex is on PATH.

jevlin setup                         # sets up every agent it finds
jevlin setup -with codex             # found or not
jevlin agents install -client codex  # later, without the rest of setup

Then start codex, or open the app, and approve Jevlin's hooks when Codex asks you to review hooks. Until you do, the hooks do nothing. Searches still run and record, without a session or a turn, and under codex exec nothing says so. Jevlin never records an approval for you.

note

Supported Codex is 0.158.0 or newer. Below 0.131 Codex refuses the whole config file with "invalid type: map, expected a boolean" and does not start. Upgrade Codex, or remove the block between its two markers. Versions 0.131 to 0.157 have not been tried.

What is written

path	what
~/.codex/skills/jevlin/	The skill, rendered for your OS and shell.
~/.codex/hooks.json	macOS and Linux: five hooks, PreToolUse, SessionStart, PreCompact, PostCompact and Stop, each written where any of Jevlin's stood before so no other hook moves.
~/.codex/config.toml	A marked block, created if the file is not there. On macOS and Linux it is a permission profile named jevlin, made the default with default_permissions. On Windows it makes the same directories writable and opens no network.

The block sits before the first table in the file, because default_permissions must, and is added and taken out without a byte of its own, so uninstall gives your file back exactly as it was.

Use it

Ask Codex anything that needs the web, or be explicit with /jevlin <question>. /jevlin off, /jevlin on, /jevlin status and /jevlin tier <band> work as in every agent with the skill. Codex runs Bash on macOS and Linux, PowerShell on Windows. See Search from your agent.

What to know

What the profile opens. It extends Codex's :workspace profile, or a profile of your own that you agreed to switch from, with write access to the state directory, plus the intake, sessions and spool directories when [miner] enabled is set, and network access to the search hosts only: the router, the authorization server when as_url is set, and the platform's agents API. The block also turns on Codex's network_proxy feature, which is what enforces the host list. The config, key and wallet are never writable from the sandbox. A host on this machine's loopback is never listed.

The Switch? question. When your config has a setting of your own that the profile would change, such as your own profile in default_permissions, default_permissions = ":workspace", a bare sandbox_mode = "workspace-write" or network_proxy = false in your [features] table, install asks once and shows every line it would write. -yes does not answer it. Answering no installs nothing for Codex and exits 0; no answer stops the install with nothing written. Without a terminal, install prints the exact lines to change by hand.

Changing hosts. If you change router_url, as_url or the platform in your config, run jevlin agents install again. jevlin agents status says when the profile names other hosts than the config does.

Turning the proxy off. codex features disable network_proxy deletes the profile's [features.network_proxy] table, and the profile then lets every command Codex runs reach any host. jevlin agents status says so, and jevlin agents install puts the table back. Do not set network_proxy = false in a project config while Jevlin's profile is your default: status reads only ~/.codex/config.toml and cannot see it.

The trace. With the hooks approved, a search carries its session, turn and call, and a subagent's search names the session that started it. Only the search command the skill shows is given them and allowed without a prompt; the search after a cd, in a loop or piped on runs as written with the per-shell identity. A Codex search carries no assistant text.

On Linux, approving the hooks is what delivers your Codex searches. Codex runs each command in its own process namespace there, so the flush a search starts to deliver its evidence ends with the search. The evidence is kept, and goes out with the next Jevlin run outside Codex: the SessionStart or Stop hook once approved, another agent's hooks, or a jevlin search or jevlin flush from your own shell. With mining on and neither of those two hooks approved, jevlin agents status and jevlin status say so, status counts the searches waiting and when the oldest was made (delivery in status -json), and agents install says it when it writes the hooks. Until something delivers them, searches made only in Codex may miss their epoch and earn nothing. macOS is not affected.

The turn end. With [miner] turn_end = true, the Stop hook reports a turn in which a search was served, read from Codex's own session file: what you asked, what the assistant wrote along the way, its final answer, and each tool call by name and outcome. A subagent's turn sends nothing of its own. See The turn end.

Codex writes into its own file too. Tables at the end, a [features] table from codex features enable, settings from the desktop app. Install and uninstall change only Jevlin's own lines, move a setting Codex wrote inside the markers to just outside them, and name each in the plan. A block that is not valid TOML, or whose profile holds anything Jevlin did not write, is left and reported.

Known limits

• Windows gets no hooks and no profile. What runs a Codex hook there has not been seen, and no permission profile has been seen to work in Codex's sandbox. The block makes the directories writable and opens no network, so a search there needs Codex's approval to reach the router.
• A Codex turn end gives a shell command no duration. The session file Codex 0.160.0 writes holds none that is the command's.
• An explicit sandbox mode discards the profile. A client of Codex's app server that starts a thread with its own sandbox mode has the network off for that thread. The skill cannot help there.
• On Linux, each command runs in its own process namespace. A flush a search starts ends with the search; the hooks, which run outside the sandbox, flush instead, so approve them. The daily release check is never started from inside the sandbox either.

Remove

jevlin agents uninstall -client codex

Removes the skill, Jevlin's hooks and its block, and puts back each line of yours it changed, unless you changed it since. When uninstall has to leave Jevlin's block, it names it, lists what to put back, and exits 1. See Removing and coming back.