Codex

Natamux starts Codex with hooks for that session only.

Before you start

Install Codex and log in. Follow the Codex project page. Check that codex runs in your terminal.

What Natamux runs

Program	codex
Command line	codex --dangerously-bypass-hook-trust --sandbox workspace-write --ask-for-approval never -c 'projects={…}' -c 'hooks.<Event>=[…]' --no-alt-screen [extra args] '<prompt>'
Full screen	Off: --no-alt-screen runs Codex inline, so its output goes into the terminal history. NATAMUX_CODEX_ARGS cannot turn it back on: the flag wins over tui.alternate_screen
Permission flag	--sandbox workspace-write --ask-for-approval never, left out with "agents": { "permissionMode": "ask" } in .natamux.json
Change the program	NATAMUX_CODEX_COMMAND
Add arguments	NATAMUX_CODEX_ARGS

Set the variables in the environment of the daemon (or the desktop app) before it starts. Start the agent from the dashboard, or:

natamux agent start T-42 --agent codex

How hooks are added

Natamux passes one -c hooks.<Event>=… override for each event. Each hook runs natamux hook codex. Your own Codex settings do not change.

The -c 'projects={…}' override trusts the task’s worktree for this run, so Codex does not ask. See Folder trust.

Caution

Codex runs a hook only after you trust it. The hooks change with the daemon’s address, so Natamux passes --dangerously-bypass-hook-trust. This flag also skips the review of the session’s other hooks, including those of a project you already trust. To avoid the flag, start Codex by hand in the task’s terminal. Its hooks then come from its own settings, and Natamux sees only the terminal.

Events and states

Hook event	Meaning	Task state
UserPromptSubmit	A prompt was sent	running
PreToolUse, PostToolUse	The agent works	no change
PermissionRequest	Codex asks for permission	needs input
Stop, Interrupt	The turn ended, or you pressed Esc	needs input

Codex has no failure hook, so a failed turn does not move the task to failed.

Skills

Where	Folder	Shown as
Project	.agents/skills/<name>/SKILL.md	Project
You	~/.agents/skills/<name>/SKILL.md	Only on this machine

• Natamux does not read Codex plugins: their install path is not documented.
• {skill:<name>} becomes $<name> when Codex has the skill. Otherwise it becomes the path of a SKILL.md of that name, or the <name> skill when none exists.

Source: Codex skills, checked 2026-10-11.

For the rules in general, see Skills in a prompt. Agents change quickly: check the vendor docs if a skill is not found.

Tested

Not run against a real Codex session. The hooks follow Codex’s source code and are tested with made-up input.

Limits

• No failed state.
• If codex is not found, the task fails in the first 15 seconds with a message that names NATAMUX_CODEX_COMMAND.