talon.plugins.codex

A Talon plugin that runs the OpenAI Codex CLI as an MCP server, turning Codex into a delegatable autonomous coding agent your Talon bot can hand tasks to.

It wraps codex mcp-server (Codex as an MCP server) — not to be confused with codex mcp, which manages Codex's own external servers.

What you get

Two MCP tools, surfaced to the agent as mcp__codex-tools__*:

codex returns a threadId plus the agent's final content. Feed that threadId back into codex-reply to keep the conversation going.

Related MCP server: claude-code-codex-agents

Defaults

For non-interactive, agent-to-agent use (there is no human on the MCP channel to click "approve"), the plugin launches Codex with:

codex mcp-server -c approval_policy="never" -c sandbox_mode="danger-full-access"

• approval_policy="never" — Codex never blocks waiting for shell-command approval.

• sandbox_mode="danger-full-access" — Codex runs shell commands without its bubblewrap sandbox.

Both are overridable: per call via the tool's approval-policy / sandbox arguments, or globally via the TALON_CODEX_SANDBOX / TALON_CODEX_APPROVAL env vars.

Why full-access by default?

Codex's workspace-write and read-only sandboxes wrap every shell command in bubblewrap, which must create a user namespace. On hardened hosts — notably Ubuntu 24.04+, which ships kernel.apparmor_restrict_unprivileged_userns=1 — bwrap fails with:

bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted

When that happens, Codex can't run the sandboxed shell at all, so under approval_policy=never every command (including writing a file) is auto-denied — the agent looks broken. danger-full-access skips bubblewrap and works. Since this plugin is meant for a trusted host (where the parent agent typically already runs with elevated permissions), full-access is the pragmatic default.

If your host's bwrap sandbox works and you want it enforced, set TALON_CODEX_SANDBOX=workspace-write (or pass sandbox: "read-only" per call for analysis-only tasks).

Requirements

• codex CLI installed and on PATH (or set TALON_CODEX_BIN). Tested with codex-cli 0.132.0.

• Codex authenticated — either a ChatGPT login (codex login) or an API key. Auth lives in ~/.codex/auth.json.

• The default model comes from ~/.codex/config.toml. Override per call with the model param (e.g. "gpt-5.5", "gpt-5.2-codex") for heavier work.

Install

Clone next to your other Talon plugins:

git clone https://github.com/talon-agent/talon.plugins.codex.git

Register it in ~/.talon/config.json:

{
  "plugins": [
    // ...
    { "path": "/absolute/path/to/talon.plugins.codex" }
  ]
}

Then hot-reload plugins (or restart Talon). The plugin is a single self-contained module — no npm install required.

Optional env

• TALON_CODEX_BIN — absolute path to the codex binary. Defaults to /home/dylan/.npm-global/bin/codex; set this if yours lives elsewhere.

• TALON_CODEX_SANDBOX — default sandbox mode (read-only / workspace-write / danger-full-access). Defaults to danger-full-access (see Why full-access by default?).

• TALON_CODEX_APPROVAL — default approval policy. Defaults to never.

Usage notes

• Always set cwd to the repo you want Codex to work in. If relative, it resolves against the MCP server process's working directory.

• Use Codex for self-contained, multi-step coding tasks (refactors, writing a feature, debugging in a repo) — anything you'd want a separate agent to grind on independently.

• Override model per call for non-trivial work; the config default may be a small/cheap model.

How it works

A Talon plugin is just a module exporting { name, description, version, mcpServer: { command, args }, getSystemPromptAddition() }. Talon launches command/args as a stdio MCP server and exposes its tools to the agent. This plugin's command is the codex binary and its args are ["mcp-server", ...defaults].

License

MIT — see LICENSE.