---
title: "codex"
url: "https://claudemods.dev/ko/builds/codex-1a178b"
source: "https://github.com/alex2481kobe/claude-mods/tree/main/plugins/codex"
source_type: "github"
repo: "https://github.com/alex2481kobe/claude-mods/tree/main/plugins/codex"
author: "alex2481kobe"
author_handle: "alex2481kobe"
stars: 3
category: "멀티 에이전트 및 오케스트레이션"
categories: ["agents"]
tags: ["agent-tool", "claude-code-mods", "codex", "hooks", "openai", "plugin", "subagent"]
permission_level: 2
scan_complete: true
install: "claude plugin marketplace add alex2481kobe/claude-mods\nclaude plugin install codex@claude-mods"
added: "2026-10-05T01:57:46.522Z"
updated: "2026-10-28T09:20:42Z"
locale: "ko"
content_locale: "ko"
---

# codex

OpenAI Codex를 네이티브 Claude Code 서브 에이전트로 사용: Agent 도구가 하나를 시작하고, 모드가 그 자리에 codex app-server를 구동하며, 중간에 모델이 없습니다.

## Description

세 가지 Codex 에이전트 유형(codex:read, codex:write, codex:run)을 등록하는 Claude Code 플러그인으로, Agent 도구가 OpenAI Codex를 네이티브 서브 에이전트로 시작합니다. 이 모드는 Claude 모델 대신 `codex app-server`를 구동하여 에이전트 뷰에 Codex의 단계를 실시간으로 표시하고, 메시지, 대기열 메시지, 승인/질문, 프롬프트를 통한 모델/노력/샌드박스/승인 플래그, 그리고 뷰 내 `/codex-*` 명령을 지원합니다. macOS/Linux에서 Claude Code와 모드, 그리고 `codex app-server`가 설치 및 로그인된 Codex CLI가 필요합니다.

## Install

```
claude plugin marketplace add alex2481kobe/claude-mods
claude plugin install codex@claude-mods
```

## Original README

# codex

OpenAI Codex as a native Claude Code subagent.

![Two Codex agents on different models in Claude Code's agent list](media/agent-list.png)

Claude starts Codex with the Agent tool, the same way it starts any other
subagent, and Codex behaves like one:

- it shows in the agent list with its model and effort (`· Sol 6.1 (xhigh)`),
  its running time and token count, and clears when it finishes; the count
  is Codex's current context plus what it has written, the way Claude Code
  counts a Claude subagent, not the session's running total
- its row's activity line updates as Codex works, and Enter opens its view,
  where Codex's steps appear live and you can message it
- it runs in the background, and its report comes back to Claude
- you can message it, while it runs or after it finishes; each message
  resumes the same Codex session. A message Claude sends while Codex works
  joins Codex's running turn, so Codex reads it then and its answer covers it;
  one you type in the agent's view waits for the turn to end (`· 1 queued`)
- when Codex asks for an approval or an answer, the agent reports the question
  and its next message answers it, in the same paused Codex turn
- in its view, `/codex-*` commands change its model, effort, sandbox and
  approvals for its next Codex turns and show its status
- stopping the agent stops Codex, and so does Claude Code exiting or crashing;
  like a stopped Claude subagent, its next message carries on in the same
  Codex session rather than starting the task again

No Claude model runs inside the agent: the mod drives `codex app-server` in its
place and shows what Codex does in the agent's view as it happens. (A small Claude
model stands in only if the mod itself fails, to report that failure.)

| Agent type    | Shown as                | Codex sandbox and approvals            | Use it for                                      |
| ------------- | ----------------------- | -------------------------------------- | ----------------------------------------------- |
| `codex:read`  | `Codex read-only`       | `read-only`, approvals off             | second opinions, review, research, scoping      |
| `codex:write` | `Codex workspace-write` | `workspace-write`, approvals off       | bounded implementation in the working directory |
| `codex:run`   | `Codex`                 | your Codex config, changed by flags    | anything else Codex can be set up to do         |

## Requirements

- Claude Code with mods (tested on 2.1.287 and 2.1.288)
- macOS or Linux (the mod talks to Codex through a named pipe)
- The [Codex CLI](https://github.com/openai/codex) with `codex app-server`
  (tested on 0.159), installed and logged in:

  ```sh
  npm install -g @openai/codex
  codex login
  ```

  `codex` must be on the `PATH` Claude Code starts with.

## Install

```
/plugin marketplace add alex2481kobe/claude-mods
/plugin install codex@claude-mods
```

## Use

Ask Claude for it by name:

> Have codex:read review the changes in src/auth and report anything risky.

> Use codex:write to add input validation to parseConfig in src/config.ts.

Codex cannot see your conversation with Claude, so Claude passes it a
self-contained prompt. Codex uses your own Codex login, model and config.

### Choosing a model and settings

The Agent tool's own `model` option names Claude models, so Codex is set up in
the prompt instead. The prompt may open with Codex CLI flags, one per line,
spelled as `codex exec --help` spells them (`model: gpt-6-astra`,
`--sandbox workspace-write`, or a flag alone on its line). The mod passes them
to Codex and removes them from the task. `Model:` and `Effort:` may be written
in any case:

```
model: gpt-6-astra
effort: high
Review app.js for bugs and report back.
```

The agent types' descriptions list the models your Codex knows, so you can ask
in plain words: "have Codex review this on gpt-6-astra and gpt-6.1-sol".

Only an exact option line is an option: a flag's name with one plain value (a
path, or a config `key=value`, may hold spaces), or a flag that takes no value
alone on its line. The first line that is not one starts the task, so a prompt
that opens with prose such as `search: every call to fetch` or `color: change
the header color` is passed to Codex whole.

`codex:read` and `codex:write` take `model`, `effort` and the flags that leave
their sandbox alone; `sandbox`, approvals, `add-dir` and `cd` are refused there.
`codex:run` takes every flag that applies to a session the mod drives:

| Flag                                                      | What Codex gets                                         |
| --------------------------------------------------------- | ------------------------------------------------------- |
| `model`, `effort`                                         | `model`, `model_reasoning_effort`                       |
| `sandbox` (`s`)                                           | `sandbox_mode`                                          |
| `ask-for-approval` (`a`)                                  | `approval_policy`                                       |
| `approve-for-me`                                          | the automatic reviewer, in `workspace-write`            |
| `dangerously-bypass-approvals-and-sandbox`                | `danger-full-access` with approvals off                 |
| `add-dir`                                                 | an extra writable root, beside your config's            |
| `search`, `local-provider`, `cd` (`C`), `image` (`i`)     | live web search, the model provider, the folder, images |
| `config` (`c`), `enable`, `disable`, `strict-config`      | passed as given                                         |
| `ephemeral`, `output-schema`                              | an unsaved session, a JSON Schema for the answer        |

Everything left out comes from your Codex config. An option line for a flag
`codex app-server` has no use for (`profile: fast`, `worktree`, `json`, ...)
stops the run with the reason rather than being dropped.

### Answering Codex

When Codex asks for something, the agent hands the question back:

```
Codex asks to run:
  printf 'hi' > note.txt
in /path/to/project
Reason: requires approval by policy
Reply "approve", "approve for session", "decline", or "cancel" (decline and stop the turn).
```

Claude answers it itself or asks you, then sends the reply to the agent as a
message, and Codex carries on in the same turn. Questions for the user and MCP
servers' forms work the same way.

A question lives as long as the Codex that asked it. If that Codex is gone
(it exited, the session was resumed, or the mod reloaded), a reply such as
"approve" is not sent as a new task: the agent reports that the question has
expired, and the task has to be sent again.

Who Codex asks is set by its config. With `approvals_reviewer` set to Codex's
automatic reviewer, Codex never asks: its reviewer decides, and the transcript
shows what it decided. To be asked instead, set approvals to come to you, in
your config or for one agent:

```
ask-for-approval: on-request
config: approvals_reviewer="user"
Create note.txt containing hi.
```

### Commands in the agent's view

Open a codex agent's view (select it in the agent list, press Enter) and run
a command; the `/` menu there lists them. The reply shows above the prompt in
that view, and neither Codex nor Claude is sent it:

| Command                                                      | What it does                                                  |
| ------------------------------------------------------------ | ------------------------------------------------------------- |
| `/codex-model <id>`                                          | the Codex model, from the agent's next Codex turn             |
| `/codex-effort <level>`                                      | the reasoning effort, from the next turn                      |
| `/codex-sandbox <read-only\|workspace-write\|danger-full-access>` | the sandbox, from the next turn                         |
| `/codex-approvals <untrusted\|on-request\|never>`            | when Codex asks for approval, from the next turn              |
| `/codex-status`                                              | what Codex said the session ran with at its last turn, what changes next turn, the Codex session and its running token total |
| `/codex-help`                                                | the list                                                      |

```
model     gpt-6-astra from the next Codex turn (now gpt-6-luna)
effort    low
sandbox   workspace-write
approvals on-request
session   01a0f9f0-0000-7000-8000-000000000000
tokens    141,551 in (127,488 cached), 296 out, running total
```

A setting is kept for that agent and goes with each of its later Codex turns,
and the header of each turn names the model and effort Codex reports for it.
Values follow the option rules above: `codex:read` and `codex:write` refuse
`/codex-sandbox` and `/codex-approvals`, since they pin their sandbox, and a
value that is not one plain word is refused. An unknown `/codex-` command, or
one without its value, answers with the list. Claude can send one to the
agent with SendMessage; then the reply is the agent's report, and a message
sent together with it goes to Codex on its own.

While a codex agent's view is open, the footer and the `/` menu list these
commands alone: Claude Code's own commands act on the main session, not on
the agent, so they are hidden there (typed in full, they still run). Elsewhere
the `/codex-` commands are hidden, and one typed in full says to open a codex
agent's view.

## How it works

- The mod registers the three agent types.
- When a `codex:*` agent's loop asks its model for a response, the mod answers
  instead: it starts `codex app-server` with the agent's flags as config
  overrides, starts or resumes the Codex session in the session's working
  directory with the settings its commands chose, shows Codex's messages and commands in the agent's view as they
  happen (each is also appended as a notice, which is what refreshes the agent
  list's activity line; the detailed transcript, ctrl+o, shows both), and
  reports Codex's token usage on the agent's row: each turn hands Claude Code
  the input of Codex's last request (its current context, cached tokens
  apart) and the output the turn generated. Claude Code keeps the latest
  input and adds up the outputs, as it does for a Claude subagent. The
  running total, which counts every cached re-read of the session and soon
  reaches millions, is in `/codex-status`.
- A mod's process takes its input once, so the mod writes to `codex app-server`
  through a named pipe in a private temporary folder, which goes when the
  process does. The mod writes only to that pipe, and never once the server
  has gone.
- Codex runs in a process group of its own under a small shell. Stopping the
  agent ends the shell and Codex with it; if Claude Code exits without stopping
  it (a crash, `kill -9`), the shell sees its parent gone within a second or
  two and ends Codex and the folder.
- Codex's final message, or its question, goes back as the agent's report:
  through the `SubagentHandback` tool in an interactive session, or as the
  final text where that tool does not exist (headless, SDK). A handback you
  interrupt (Esc in the agent's view) does not change that. A report that
  never reached the caller (its handback interrupted, or failed for want of
  the tool) is given again the next time the agent's loop runs, once: ahead
  of the answer to a new message, or alone when there is none.
- A step interrupted before Codex finished (Esc, or stopping the agent) stops
  Codex, and the agent hands back only `codex: stopped before Codex
  finished.`: what Codex said on the way is never handed back, and that line
  is never given again as an undelivered report. (Claude Code's own notice
  that the agent was stopped still quotes what the agent had shown so far.) A message counts as passed on once Codex
  has taken it (its turn started, or its question answered), finished or not:
  the next message resumes the same Codex session with that message alone,
  and the stopped task is not sent again. Only a step cut off before Codex
  took its messages (Esc, or the session moving host, while the session was
  starting) passes nothing on, and the next time the agent's loop runs, those
  messages are given to Codex again. The agent's options come from the prompt
  it was spawned with, which the mod records at spawn, so a first task run
  again keeps them however Claude Code places the messages sent since; the
  task goes first, then those messages. Claude Code's interruption marker
  (`[Request interrupted by user]`) never reaches Codex. When the interruption is the session moving to the background
  (the session list opening while the agent's first turn runs), Claude Code
  2.1.287 continues the agent in a forked session whose conversation, as the
  mod reads it, no longer holds the task, so the agent reports
  `codex: nothing new to send to Codex.` and Claude has to send the task
  again.
- Codex runs only while it works or waits on a question. Every message sent to
  the agent is passed to Codex once, in the sender's own words: as the answer
  to a waiting question, added to Codex's running turn (`turn/steer`, for a
  message Claude sends with SendMessage while Codex works), or as a new turn
  of the same Codex session. Claude
  Code places a message sent to a running agent twice, wrapped in its own
  instructions and as typed; the mod counts it once and drops the wrapping, so
  the same words sent twice are asked twice. A `/codex-` message is the mod's
  own and never reaches Codex.

## Limits

- The Agent tool's `model` and `cwd` options are ignored: Codex uses your Codex
  config, in the session's working directory.
- What Codex may do is decided by its sandbox, approvals and requirements, not
  by Claude Code's permission prompts. `codex:run` takes every flag Codex
  accepts, `dangerously-bypass-approvals-and-sandbox` included. Codex's own
  requirements (`allowed_sandbox_modes`, `allowed_approval_policies`) are the
  place to forbid one; the mod has not been tested against them. In auto mode, Claude may note that its safety
  check could not review the agent's output, since no Claude model wrote it.
- `codex app-server` takes no profiles: set those values with `config:` lines.
- `codex:read` and `codex:write` run with approvals off, so the sandbox is the
  limit. Codex's `workspace-write` sandbox keeps `.git` read-only, so
  `codex:write` cannot stage or commit (`git add` fails on `.git/index.lock`);
  commit its work yourself, or use `codex:run` with approvals that let Codex
  ask.
- A question left unanswered keeps that Codex waiting until it is answered or
  the session ends.
- An agent started with `ephemeral` cannot take follow-ups: Codex does not
  keep its session, so there is nothing to resume.
- Claude Code 2.1.287 shows a mod a message typed in an agent's view only
  once the agent's turn has ended, so such a message cannot join Codex's
  running turn; it waits for Codex's current task, then runs as its next turn.
- A command's reply shows above the prompt only while that view stays open,
  and goes when the view closes or the mod reloads.
- What the agent answers also reaches Claude as
  the agent's report, and Claude reads a message typed in the view as one the
  agent got.
- Claude Code may run the agent's loop again for the copy of a message it
  places later. Codex is not asked again, but the loop has to report, so
  Claude gets the one line `codex: nothing new to send to Codex.`, and the
  view shows `codex: nothing to run.` (Ending without a report would have
  Claude Code tell Claude that no report came and to message the agent for
  one.)
- Opening the session list (← from the prompt) moves the conversation into a
  background process. On macOS Claude Code 2.1.287 sometimes starts that
  process as the Claude Code app itself, which macOS checks on its own for
  access to Documents, Desktop and Downloads. If the plugin's folder is under
  one of those and Claude Code has not been given access, that process cannot
  read the plugin, so the conversation continues there without it: the codex
  agent types are gone until you restart. A plugin installed from the
  marketplace lives under `~/.claude` and is not affected; for a
  `--plugin-dir` or a local marketplace, keep the folder outside those three.
- Claude Code's task list (`/tasks`) names the stand-in's model, Haiku, for a
  codex agent; the agent's row and header show Codex's. The agent keeps a
  Claude model so that a run the mod does not answer (the mod not loaded, or
  the session resumed without it) reaches the stand-in, which reports that
  Codex did not run, rather than failing on a Codex model id.
- Tested on macOS with codex-cli 0.159 and Claude Code 2.1.287 and 2.1.288, in an
  interactive terminal session (agent list, agent view and its commands,
  footer and `/` menu, background agents, messages and queued messages,
  approvals, stop) and headless (`claude -p`). Linux should behave
  the same; Windows is not supported (the mod needs `sh` and a named pipe).
- The mods API is early access and may change between Claude Code releases.

## Develop

```sh
claude plugin validate plugins/codex
claude plugin test plugins/codex
claude --plugin-dir plugins/codex
```
