# talon.plugins.codex

A [Talon](https://github.com/talon-agent) 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__*`:

| Tool | Purpose | Required | Notable optional params |
| --- | --- | --- | --- |
| `codex` | Start a new Codex session | `prompt` | `cwd`, `model`, `sandbox`, `approval-policy` |
| `codex-reply` | Continue an existing session | `prompt`, `threadId` | — |

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

## 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](https://github.com/openai/codex) 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:

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

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

```jsonc
{
  "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?](#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](./LICENSE).