@xallindrome-labs/codex-bridge 0.1.0 → 0.2.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,12 @@
+{
+  "name": "codex-bridge",
+  "owner": { "name": "Xallindrome", "url": "https://xallindrome.co" },
+  "metadata": { "description": "Claude Code add-ons for codex-bridge." },
+  "plugins": [
+    {
+      "name": "codex-jobs",
+      "source": "./plugins/codex-jobs",
+      "description": "A pane beside the chat that lists your codex-bridge jobs live: running, done, interrupted."
+    }
+  ]
+}

package/README.md

@@ -2,7 +2,7 @@
 
 **Codex jobs for Claude Code that survive crashes, closed windows and reboots, with Codex image generation built in.** A dependency-free MCP server built Windows-first: every call is a job saved on disk, so you can close Claude, lose power, or kill a process, and pick the work up again with `codex_resume`.
 
-Roles: **Claude Code implements. Codex plans and builds images.**
+Roles: **Claude Code implements. Codex plans and builds images.** Optionally (opt-in, one folder), Codex can also write code while Claude reviews: see [Let Codex write code](#let-codex-write-code-opt-in). And an optional pane beside the chat lists your jobs live and shows your Codex usage and when it resets: see [Codex jobs pane](#codex-jobs-pane).
 
 ![Recorded session: Claude Code starts codex-bridge and asks Codex for a plan](docs/demo.svg)
 
@@ -26,11 +26,12 @@ Other MCP clients: run `npx -y @xallindrome-labs/codex-bridge` as a stdio server
 |---|---|---|---|
 | `codex_plan` | Codex writes implementation plans, design reviews and second opinions. It inspects the project in `cwd`. | `read-only` (always) | Your Codex config defaults |
 | `codex_image` | Codex generates or edits images. The bridge copies each one into `output_dir` as soon as it's made. | `read-only` (always) | **gpt-6-luna / high** |
+| `codex_code` | **Off by default.** Codex implements a change by editing files in one folder you choose. See [below](#let-codex-write-code-opt-in). | `workspace-write`, that folder only, no network | Your Codex config defaults |
 | `codex_result` | Gets a job's result or progress (`wait_seconds` up to 240), or lists recent jobs. | | |
 | `codex_resume` | Continues an interrupted, timed-out or failed job from where it stopped. | | |
 | `codex_cancel` | Stops a running job. | | |
 
-`codex_plan` and `codex_image` accept:
+`codex_plan`, `codex_image` and `codex_code` accept:
 - `effort`: `low`, `medium`, `high`, `xhigh`, `max` or `ultra` (Luna supports up to `max`).
 - `model`: overrides the default model for that call.
 - `background: true`: returns a `job_id` immediately so Claude can keep working.
@@ -38,6 +39,39 @@ Other MCP clients: run `npx -y @xallindrome-labs/codex-bridge` as a stdio server
 
 `codex_image` also takes `count`, the number of images wanted. Set it for batches: it enables `k/count` progress and resumes that ask for exactly the missing images.
 
+## Let Codex write code (opt-in)
+
+By default Codex can only read. If you want it to implement things while Claude reviews, name the one folder it may edit:
+
+```bash
+claude mcp add codex-bridge -e CODEX_BRIDGE_WRITE_ROOT=/path/to/your/project -- npx -y @xallindrome-labs/codex-bridge
+```
+
+Restart Claude Code and a fourth tool, `codex_code`, appears. Ask for it in plain words: *"Have Codex implement the plan in the background, then review its diff."*
+
+- **One folder.** `cwd` must be `CODEX_BRIDGE_WRITE_ROOT` or inside it. Anything else is refused, checked on real paths so `..` and symlinks don't escape. A drive root or your home folder is refused as too broad.
+- **No network, no commits.** Codex runs with network access off and is told to leave changes uncommitted so you can see them in `git diff`. The no-commit rule is a prompt, not a sandbox rule.
+- **Claude reviews.** Every `codex_code` result ends with a reminder to read the diff before accepting it. A failed or cancelled run says Codex may have left partial edits.
+- **Same job machinery.** It survives restarts, `background: true` and `codex_resume` work the same way, and a resume re-checks the folder rule.
+- **Temp files.** In our test on Windows 11, writes outside the folder and network access were blocked, but the system temp folder stayed writable. Treat temp as writable. `CODEX_BRIDGE_WRITE_ALLOW_TMP=1` stops asking Codex to block it.
+- **Don't edit the same files yourself** while a `codex_code` job runs.
+
+Unset the variable and restart, and the tool is gone; `codex_plan` and `codex_image` are always read-only.
+
+## Codex jobs pane
+
+An optional add-on that opens a pane beside the Claude Code chat listing your Codex jobs live: running, done, interrupted, with age, request and `images k/n` for batches. It also shows your Codex usage: the 5-hour and weekly windows, percent used, when each resets, and how many images were generated in each (Codex has one shared meter, so images use the same limits). It only reads the job files on disk, so it shows jobs from any session, including ones that kept running after you closed Claude. It also puts `codex: N running` in the status line and shows a toast when a job you watched finishes.
+
+At the prompt of a terminal Claude Code session:
+
+```
+/plugin install codex-jobs --marketplace xallindrome-labs/codex-bridge
+```
+
+In the desktop app, where `/plugin` does not run: click **+** next to the prompt box, then **Plugins**, **Add marketplace** with `xallindrome-labs/codex-bridge`, then **Add plugin**. Without a marketplace, for one session: `claude --plugin-dir "$(npx -y @xallindrome-labs/codex-bridge --pane-path)"`.
+
+Then type `/codex-jobs`. It also opens by itself the first time a job is running in a session. Details and how it works are in [plugins/codex-jobs](plugins/codex-jobs/README.md). It needs a Claude Code build that supports mods; it is tested against the engine's own test kit, not every surface's paint.
+
 ## How it compares
 
 OpenAI's [codex-plugin-cc](https://github.com/openai/codex-plugin-cc) is the official way to use Codex from Claude Code, and it's good at what it does: slash commands for review and rescue. codex-bridge is an MCP server instead, with a different focus: **jobs that don't get lost**, and **images**.
@@ -81,7 +115,7 @@ Each attempt keeps its own `prompt.txt`, `events.jsonl` (the Codex event stream)
 
 Each attempt runs `codex exec --json` (or `codex exec resume <thread>`) with the prompt on stdin. No shell is involved.
 
-Every call runs read-only. New sessions pass `-s read-only` plus `-c sandbox_mode="read-only"`; resumed sessions pass `-c sandbox_mode="read-only"` (`codex exec resume` takes no `-s`). Your Codex config may default to `danger-full-access`, but that default never applies to bridge calls. The `plan` smoke test checks that a write attempted from a resumed session fails.
+Every call runs read-only, except `codex_code` when you have opted in (it runs `workspace-write` in your one folder, with network off). New sessions pass `-s read-only` plus `-c sandbox_mode="read-only"`; resumed sessions pass `-c sandbox_mode="read-only"` (`codex exec resume` takes no `-s`). Your Codex config may default to `danger-full-access`, but that default never applies to bridge calls. The `plan` smoke test checks that a write attempted from a resumed session fails.
 
 | File | Role |
 |---|---|
@@ -110,6 +144,9 @@ Remove it with `claude mcp remove codex-bridge` (add `-s user` if you installed
 | `CODEX_BRIDGE_IDLE_TIMEOUT_MS` | `600000` (stops a run after 10 minutes with no Codex output) |
 | `CODEX_BRIDGE_PLAN_MODEL` / `CODEX_BRIDGE_PLAN_EFFORT` | Your Codex config defaults |
 | `CODEX_BRIDGE_IMAGE_MODEL` / `CODEX_BRIDGE_IMAGE_EFFORT` | `gpt-6-luna` / `high` |
+| `CODEX_BRIDGE_WRITE_ROOT` | Unset: `codex_code` is off. Set to one folder to let `codex_code` edit files there. |
+| `CODEX_BRIDGE_WRITE_ALLOW_TMP` | Unset. `1` stops asking Codex to block temp-folder writes (not enforced on Windows anyway). |
+| `CODEX_BRIDGE_CODE_MODEL` / `CODEX_BRIDGE_CODE_EFFORT` | Your Codex config defaults |
 
 ## Test
 

package/SECURITY.md

@@ -9,7 +9,8 @@ Please don't open a public issue for a vulnerability. This is a one-person proje
 
 ## What codex-bridge does that matters for security
 
-- It runs the Codex CLI on your machine, always with a **read-only sandbox**: `-c sandbox_mode="read-only"` on every call, plus `-s read-only` when starting a new session. Your Codex config's default sandbox mode never applies to bridge calls.
+- It runs the Codex CLI on your machine, by default always with a **read-only sandbox**: `-c sandbox_mode="read-only"` on every call, plus `-s read-only` when starting a new session. Your Codex config's default sandbox mode never applies to bridge calls.
+- **Opt-in exception: `codex_code`.** Only if you set `CODEX_BRIDGE_WRITE_ROOT` to one folder, an extra tool `codex_code` appears. It runs Codex in the `workspace-write` sandbox with network access off, and refuses any `cwd` that is not that folder or inside it (checked on the real path, so `..` and symlinks don't escape; a drive root or your home folder is refused as too broad). The check repeats on every resume. Everything else stays read-only. In our test on Windows 11, writes outside the folder and network access were blocked, but the system temp folder stayed writable even with the flags that ask Codex to block it (`CODEX_BRIDGE_WRITE_ALLOW_TMP` unset); treat temp as writable. Codex is told not to commit or push, but that is a prompt, not a sandbox rule: review the diff.
 - It starts Codex without a shell: arguments are passed as an array and the prompt goes in over stdin.
 - Prompts and any `context` you pass are sent to OpenAI through the Codex CLI, under your own Codex login. **Don't put secrets in prompts.**
 - Job files (prompts, Codex event streams, results) are stored unencrypted under `~/.codex-bridge/jobs/` (override with `CODEX_BRIDGE_HOME`) and deleted after 14 days.

package/lib.mjs

@@ -34,10 +34,16 @@ export function resolveCodexBin() {
 }
 
 // `codex exec` (or `codex exec resume`) arguments; the prompt is always read from stdin.
-export function buildCodexArgs({ sandbox, cwd, sessionId, model, effort, images = [] }) {
+// workspace-write is the opt-in codex_code sandbox: Codex may write in `cwd` only, with no network.
+// Unless allowTmp, the system temp dirs are not writable either, so "one folder" really means one folder.
+export function buildCodexArgs({ sandbox, cwd, sessionId, model, effort, images = [], allowTmp = false }) {
   const args = ['exec'];
   if (sessionId) args.push('resume');
   args.push('--json', '--skip-git-repo-check', '-c', `sandbox_mode="${sandbox}"`);
+  if (sandbox === 'workspace-write') {
+    args.push('-c', 'sandbox_workspace_write.network_access=false');
+    if (!allowTmp) args.push('-c', 'sandbox_workspace_write.exclude_tmpdir_env_var=true', '-c', 'sandbox_workspace_write.exclude_slash_tmp=true');
+  }
   if (!sessionId) args.push('-s', sandbox, '-C', cwd);
   if (model) args.push('-m', model);
   if (effort) args.push('-c', `model_reasoning_effort="${effort}"`);
@@ -47,6 +53,34 @@ export function buildCodexArgs({ sandbox, cwd, sessionId, model, effort, images
   return args;
 }
 
+// ---------------------------------------------------------------- write root
+
+// The one folder codex_code may write in (CODEX_BRIDGE_WRITE_ROOT), as a real path. Throws with a
+// reason if it is unusable: missing, not a folder, a drive root or the home folder (too broad).
+export function resolveWriteRoot(raw = process.env.CODEX_BRIDGE_WRITE_ROOT) {
+  if (!raw) return null;
+  let root;
+  try { root = fs.realpathSync(path.resolve(raw)); } catch { throw new Error(`CODEX_BRIDGE_WRITE_ROOT does not exist: ${raw}`); }
+  if (!fs.statSync(root).isDirectory()) throw new Error(`CODEX_BRIDGE_WRITE_ROOT is not a folder: ${raw}`);
+  let home = os.homedir();
+  try { home = fs.realpathSync(home); } catch {}
+  if (path.parse(root).root === root || root === home) {
+    throw new Error(`CODEX_BRIDGE_WRITE_ROOT is too broad (${root}); point it at one project folder`);
+  }
+  return root;
+}
+
+// Real path of `dir` if it is `root` or inside it, otherwise throws.
+export function insideWriteRoot(root, dir) {
+  let real;
+  try { real = fs.realpathSync(path.resolve(dir)); } catch { throw new Error(`cwd does not exist: ${dir}`); }
+  const rel = path.relative(root, real);
+  if (rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+    throw new Error(`codex_code may only write inside ${root}; ${real} is outside it`);
+  }
+  return real;
+}
+
 // ---------------------------------------------------------------- files
 
 export function readJson(p, fallback = null) {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@xallindrome-labs/codex-bridge",
-  "version": "0.1.0",
-  "description": "MCP server that lets Claude Code consult the Codex CLI for plans, second opinions and images, as durable background jobs.",
-  "keywords": ["mcp", "model-context-protocol", "claude-code", "codex", "openai-codex", "planning", "image-generation"],
+  "version": "0.2.0",
+  "description": "MCP server that lets Claude Code consult the Codex CLI for plans, second opinions and images, as durable background jobs. Optional write mode, and a live jobs pane.",
+  "keywords": ["mcp", "model-context-protocol", "claude-code", "codex", "openai-codex", "planning", "image-generation", "claude-code-plugin"],
   "homepage": "https://github.com/xallindrome-labs/codex-bridge#readme",
   "bugs": "https://github.com/xallindrome-labs/codex-bridge/issues",
   "repository": {
@@ -25,7 +25,10 @@
     "lib.mjs",
     "smoke-test.mjs",
     "docs/demo.svg",
-    "SECURITY.md"
+    "SECURITY.md",
+    ".claude-plugin/marketplace.json",
+    "plugins/codex-jobs",
+    "!plugins/codex-jobs/**/*.test.tsx"
   ],
   "engines": {
     "node": ">=20"

package/plugins/codex-jobs/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "codex-jobs",
+  "version": "0.1.0",
+  "description": "A pane beside the chat that lists your codex-bridge jobs live: running, done, interrupted.",
+  "author": { "name": "Xallindrome", "url": "https://xallindrome.co" },
+  "homepage": "https://github.com/xallindrome-labs/codex-bridge#codex-jobs-pane",
+  "license": "MIT",
+  "types": "./types/index.d.ts"
+}

package/plugins/codex-jobs/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Wilson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/plugins/codex-jobs/README.md

@@ -0,0 +1,45 @@
+# codex-jobs
+
+A Claude Code add-on (a "mod") that opens a pane beside the chat listing your [codex-bridge](https://github.com/xallindrome-labs/codex-bridge) jobs, live. It is read-only: it looks at the job files codex-bridge keeps on disk, so it shows jobs started by any Claude session, including ones that kept running after you closed Claude.
+
+For each job it shows the tool (`plan`, `code` or `image`), the status (running, done, failed, interrupted, cancelled, timed out), how long it has run or took, the request, and `images k/n` for image batches. Above the list it shows your **Codex usage**: the 5-hour and weekly windows with percent used, a bar, when each resets, and how many images the bridge generated in each window. Codex has one shared meter, so images use the same limits as text; there is no separate image meter. A status-line entry shows `codex: N running`, and a short toast appears when a job you watched start finishes.
+
+## Install
+
+At the prompt of a terminal Claude Code session:
+
+```
+/plugin install codex-jobs --marketplace xallindrome-labs/codex-bridge
+```
+
+From a shell: `claude plugin install codex-jobs --marketplace xallindrome-labs/codex-bridge`.
+
+In the desktop app, where `/plugin` does not run: click **+** next to the prompt box, then **Plugins**, **Add marketplace** with `xallindrome-labs/codex-bridge`, then **Add plugin**.
+
+Or, without a marketplace, from the npm package (this session only):
+
+```
+claude --plugin-dir "$(npx -y @xallindrome-labs/codex-bridge --pane-path)"
+```
+
+## Use
+
+- Type `/codex-jobs` to open the pane. It also opens by itself the first time a job is running in a session.
+- The list refreshes every 3 seconds and shows the 12 newest jobs.
+- If a job shows **interrupted**, its Codex process is gone (reboot, crash or kill). Ask Claude to run `codex_resume` with that job id.
+
+It finds the jobs in `$CODEX_BRIDGE_HOME/jobs`, or `~/.codex-bridge/jobs` if that is not set. Usage comes from the newest Codex session logs in `$CODEX_HOME/sessions` (default `~/.codex/sessions`), where Codex records its usage windows; it is re-read every 30 seconds and shows when it was last written, so it can lag until Codex runs again. A window whose reset time has passed shows as reset.
+
+## What it needs
+
+- codex-bridge, which creates the jobs. This add-on only reads local files (codex-bridge job files and Codex session logs); it does not call Codex or the network.
+- A Claude Code build that supports mods (hooks modules and `Pane`). Whether a pane is drawn depends on the surface; the add-on is tested against the terminal, desktop, VS Code and mobile element tables, not every paint.
+
+## Develop
+
+```
+claude plugin validate plugins/codex-jobs
+claude plugin test plugins/codex-jobs
+```
+
+MIT licensed, like codex-bridge. Built by [Xallindrome](https://xallindrome.co).

package/plugins/codex-jobs/hooks/hooks.json

@@ -0,0 +1 @@
+{ "modules": ["./register.tsx"] }

package/plugins/codex-jobs/hooks/register.tsx

@@ -0,0 +1,390 @@
+import { atom, read, update } from 'claude-code'
+import type { EngineInterface, Register } from 'claude-code'
+
+import type { ImageTally, JobRow, JobStatus, JobsSnapshot, Usage, UsageWindow } from '../types'
+
+// A pane beside the chat that lists codex-bridge jobs. It only reads files:
+// the job files codex-bridge keeps (jobs/<id>/job.json, attempt-<n>/result.json
+// and heartbeat), so it works for jobs started by any Claude session, and the
+// newest Codex session logs, where Codex records how much of its 5-hour and
+// weekly usage windows is used and when each resets.
+
+const PANE = 'codex-jobs'
+const POLL_MS = 3000
+const SHOWN = 12
+// Jobs read per poll (the rest of the list is older). Finished ones are cached, so this is cheap.
+const READ = 60
+// Codex usage is re-read every this many polls (30s); its logs change slowly.
+const USAGE_EVERY = 10
+const USAGE_FILES = 4
+const DAY_MS = 24 * 3600 * 1000
+// The runner beats every 2s; a job whose heartbeat is older than this is dead.
+const BEAT_STALE_MS = 30_000
+const LAUNCH_GRACE_MS = 60_000
+
+// Change the tag when the snapshot's fields change: it declines what an earlier
+// version stored, which outlives a reload.
+const snapshot = atom(
+  { plugin: 'codex-jobs', key: 'snapshot' } as const,
+  { rows: [], images: [], at: 0 } as JobsSnapshot,
+  { shape: 'snapshot-2' },
+)
+
+type Job = {
+  id: string
+  tool: string
+  created: number
+  attempts: number
+  attemptStarted?: number
+  cwd?: string
+  outDir?: string
+  args?: { request?: string; prompt?: string; count?: number }
+}
+type Result = { status: JobStatus; finished?: number; images?: string[] }
+
+const ICON: Record<JobStatus, string> = {
+  running: '●',
+  done: '✓',
+  failed: '✗',
+  interrupted: '!',
+  cancelled: '○',
+  timed_out: '✗',
+}
+const COLOR: Record<JobStatus, string> = {
+  running: 'yellow',
+  done: 'green',
+  failed: 'red',
+  interrupted: 'red',
+  cancelled: 'gray',
+  timed_out: 'red',
+}
+
+export const ago = (ms: number): string => {
+  const s = Math.max(0, Math.round(ms / 1000))
+  if (s < 120) return `${s}s`
+  const m = Math.round(s / 60)
+  return m < 120 ? `${m}m` : `${Math.round(m / 60)}h`
+}
+
+// "3h 12m", "2d 4h": how long until a usage window resets.
+export const until = (ms: number): string => {
+  const m = Math.max(0, Math.round(ms / 60_000))
+  if (m < 60) return `${m}m`
+  const h = Math.floor(m / 60)
+  if (h < 24) return `${h}h ${m % 60}m`
+  return `${Math.floor(h / 24)}d ${h % 24}h`
+}
+
+const bar = (percent: number, width = 10): string => {
+  const filled = Math.min(width, Math.max(0, Math.round((percent / 100) * width)))
+  return '█'.repeat(filled) + '░'.repeat(width - filled)
+}
+
+// Jobs finished, failed or dead are history; only these can still change.
+const isFinal = (s: JobStatus) => s !== 'running' && s !== 'interrupted'
+
+// What this module remembers between ticks. A reload starts it over.
+const cache = new Map<string, { mtime: number; row: JobRow }>()
+let last = ''
+let lastRunning = -1
+let ticks = 0
+let usage: Usage | undefined
+let hasAutoOpened = false
+let timer: { cancel: () => void } | undefined
+
+const slash = (p: string) => p.replace(/\\/g, '/')
+
+async function json<T>($: EngineInterface, path: string): Promise<T | undefined> {
+  try {
+    return JSON.parse(await $.fs.read(path)) as T
+  } catch {
+    return undefined
+  }
+}
+
+async function jobsDir($: EngineInterface): Promise<string | undefined> {
+  const custom = await $.env.get('CODEX_BRIDGE_HOME')
+  if (custom) return `${slash(custom)}/jobs`
+  const user = (await $.env.get('USERPROFILE')) ?? (await $.env.get('HOME'))
+  return user ? `${slash(user)}/.codex-bridge/jobs` : undefined
+}
+
+async function readRow($: EngineInterface, dir: string, id: string): Promise<JobRow | undefined> {
+  const jobFile = `${dir}/${id}/job.json`
+  const stat = await $.fs.stat(jobFile).catch(() => undefined)
+  if (!stat) return undefined
+  const hit = cache.get(id)
+  if (hit && hit.mtime === stat.mtimeMs && isFinal(hit.row.status)) return hit.row
+
+  const job = await json<Job>($, jobFile)
+  if (!job) return undefined
+  const attempt = `${dir}/${id}/attempt-${job.attempts}`
+  const result = await json<Result>($, `${attempt}/result.json`)
+
+  let status: JobStatus
+  if (result) {
+    status = result.status
+  } else {
+    const now = await $.clock.now()
+    const beat = await $.fs.stat(`${attempt}/heartbeat`).catch(() => undefined)
+    const isAlive = beat
+      ? now - beat.mtimeMs < BEAT_STALE_MS
+      : now - (job.attemptStarted ?? job.created) < LAUNCH_GRACE_MS
+    status = isAlive ? 'running' : 'interrupted'
+  }
+
+  let images: number | undefined
+  if (job.tool === 'codex_image') {
+    const copied = result?.images
+      ? result.images.length
+      : Object.keys((await json<Record<string, string>>($, `${dir}/${id}/copied.json`)) ?? {}).length
+    images = copied
+  }
+
+  const row: JobRow = {
+    id: job.id,
+    tool: job.tool,
+    status,
+    created: job.created,
+    finished: result?.finished,
+    label: (job.args?.request ?? job.args?.prompt ?? '').replace(/\s+/g, ' ').trim().slice(0, 160),
+    where: job.cwd ?? job.outDir ?? '',
+    attempts: job.attempts,
+    images,
+    count: job.args?.count,
+  }
+  cache.set(id, { mtime: stat.mtimeMs, row })
+  return row
+}
+
+const names = async ($: EngineInterface, dir: string, kind: 'dir' | 'file') =>
+  ((await $.fs.list(dir).catch(() => [])) ?? [])
+    .filter(entry => entry.kind === kind)
+    .map(entry => entry.name)
+    .sort()
+    .reverse()
+
+const toWindow = (w: unknown): UsageWindow | undefined => {
+  const x = w as { used_percent?: number; window_minutes?: number; resets_at?: number } | null | undefined
+  if (typeof x?.used_percent !== 'number' || typeof x.window_minutes !== 'number' || typeof x.resets_at !== 'number') {
+    return undefined
+  }
+  return { usedPercent: x.used_percent, windowMinutes: x.window_minutes, resetsAt: x.resets_at * 1000 }
+}
+
+// Codex writes its usage windows into every session log (token_count events:
+// payload.rate_limits.primary / .secondary). The newest log with a reading is
+// the freshest one; the same meter covers text and image generation.
+async function readUsage($: EngineInterface): Promise<Usage | undefined> {
+  const codexHome = await $.env.get('CODEX_HOME')
+  const user = (await $.env.get('USERPROFILE')) ?? (await $.env.get('HOME'))
+  const base = codexHome ?? (user ? `${user}/.codex` : undefined)
+  if (!base) return undefined
+  const root = `${slash(base)}/sessions`
+  const files: string[] = []
+  for (const year of await names($, root, 'dir')) {
+    for (const month of await names($, `${root}/${year}`, 'dir')) {
+      for (const day of await names($, `${root}/${year}/${month}`, 'dir')) {
+        const dayDir = `${root}/${year}/${month}/${day}`
+        for (const name of await names($, dayDir, 'file')) {
+          if (name.startsWith('rollout-') && name.endsWith('.jsonl')) files.push(`${dayDir}/${name}`)
+          if (files.length >= USAGE_FILES) break
+        }
+        if (files.length >= USAGE_FILES) break
+      }
+      if (files.length >= USAGE_FILES) break
+    }
+    if (files.length >= USAGE_FILES) break
+  }
+  for (const file of files) {
+    // A log over 4 MiB cannot be read whole; the next one is tried.
+    const text = await $.fs.read(file).catch(() => undefined)
+    if (!text) continue
+    const lines = text.split('\n')
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const line = lines[i]
+      if (!line?.includes('"rate_limits":{')) continue
+      try {
+        const event = JSON.parse(line) as { timestamp?: string; payload?: { rate_limits?: { primary?: unknown; secondary?: unknown } } }
+        const limits = event.payload?.rate_limits
+        const primary = toWindow(limits?.primary)
+        const secondary = toWindow(limits?.secondary)
+        if (primary || secondary) {
+          return { primary, secondary, asOf: event.timestamp ? Date.parse(event.timestamp) || 0 : 0 }
+        }
+      } catch {
+        // A half-written last line; the one before it is fine.
+      }
+    }
+  }
+  return undefined
+}
+
+async function tick($: EngineInterface): Promise<void> {
+  const dir = await jobsDir($)
+  const now = await $.clock.now()
+  let rows: JobRow[] = []
+  let problem: string | undefined
+  if (!dir) {
+    problem = 'Cannot work out where codex-bridge keeps its jobs (no home folder).'
+  } else {
+    // A missing folder just means codex-bridge has not run yet.
+    const ids = (await names($, dir, 'dir')).filter(name => name.startsWith('job-')).slice(0, READ)
+    for (const id of cache.keys()) if (!ids.includes(id)) cache.delete(id)
+    const loaded = await Promise.all(ids.map(id => readRow($, dir, id).catch(() => undefined)))
+    rows = loaded.filter((row): row is JobRow => row !== undefined)
+  }
+
+  // Images the bridge saved in the last week, counted per usage window when drawn.
+  const images: ImageTally[] = rows
+    .filter(row => row.tool === 'codex_image' && (row.images ?? 0) > 0 && now - row.created < 7 * DAY_MS)
+    .map(row => ({ at: row.created, n: row.images ?? 0 }))
+  const isUsageTick = ticks++ % USAGE_EVERY === 0
+  if (isUsageTick) usage = await readUsage($).catch(() => usage)
+  rows = rows.slice(0, SHOWN)
+
+  const running = rows.filter(row => row.status === 'running').length
+  if (running !== lastRunning) {
+    lastRunning = running
+    $.ui.status(running > 0 ? `codex: ${running} running` : undefined)
+  }
+  if (running > 0 && !hasAutoOpened) {
+    hasAutoOpened = true
+    void $.ui.open({ id: PANE, title: 'Codex jobs' })
+  }
+
+  const key = JSON.stringify([rows, images, usage]) + (problem ?? '')
+  if (running > 0 || isUsageTick || key !== last) {
+    last = key
+    await update($, snapshot, () => ({ rows, images, usage, at: now, problem }))
+  }
+}
+
+// Tells the person when a job they were watching ends.
+const wasRunning = new Set<string>()
+function announce($: EngineInterface, rows: JobRow[]) {
+  for (const row of rows) {
+    if (row.status === 'running') {
+      wasRunning.add(row.id)
+    } else if (wasRunning.delete(row.id) && isFinal(row.status)) {
+      const verb = row.status === 'done' ? 'finished' : row.status.replace('_', ' ')
+      $.ui.toast(`Codex ${row.tool.replace('codex_', '')} ${verb}: ${row.label.slice(0, 50)}`)
+    }
+  }
+}
+
+export const register: Register = on => {
+  on('session.start', async ($, e, next) => {
+    await $.command.register({
+      name: 'codex-jobs',
+      description: 'Show your codex-bridge jobs in a pane',
+    })
+    timer?.cancel()
+    const run = () =>
+      tick($)
+        .then(async () => announce($, (await read($, snapshot)).rows))
+        .catch(() => {})
+    void run()
+    timer = $.clock.every(POLL_MS, () => void run())
+
+    return next(e)
+  })
+
+  on('command.run', { command: 'codex-jobs' }, async $ => {
+    await tick($).catch(() => {})
+    await $.ui.open({ id: PANE, title: 'Codex jobs' })
+
+    return { text: 'Codex jobs pane opened.' }
+  })
+
+  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
+    const { Box, Text } = $.ui.resolve(e)
+    const snap = await read($, snapshot)
+    const room = Math.max(1, Math.floor(((e.viewport?.rows ?? 30) - 14) / 2))
+    const running = snap.rows.filter(row => row.status === 'running').length
+    const interrupted = snap.rows.filter(row => row.status === 'interrupted')
+    const windows = [
+      snap.usage?.primary && { label: '5-hour', ...snap.usage.primary },
+      snap.usage?.secondary && { label: 'Weekly', ...snap.usage.secondary },
+    ].filter((w): w is UsageWindow & { label: string } => !!w)
+
+    return (
+      <Box flexDirection="column" gap={1}>
+        <Box gap={1}>
+          <Text bold>Codex jobs</Text>
+          <Text dimColor>
+            {running} running, {snap.rows.length} shown
+          </Text>
+        </Box>
+        <Box flexDirection="column">
+          <Text bold>Codex usage</Text>
+          {windows.length === 0 && <Text dimColor>No usage reading yet. Codex records one after its first run.</Text>}
+          {windows.map(w => {
+            const isReset = w.resetsAt <= snap.at
+            // Images are counted from the start of this window, by when each job began.
+            const since = w.resetsAt - w.windowMinutes * 60_000
+            const imagesNow = snap.images.filter(i => i.at >= since).reduce((sum, i) => sum + i.n, 0)
+
+            return (
+              <Box flexDirection="column">
+                <Box gap={1}>
+                  <Text>{w.label}</Text>
+                  <Text color={w.usedPercent >= 90 ? 'red' : w.usedPercent >= 70 ? 'yellow' : 'green'}>
+                    {bar(isReset ? 0 : w.usedPercent)} {isReset ? 0 : Math.round(w.usedPercent)}%
+                  </Text>
+                  <Text dimColor>{isReset ? 'window has reset' : `resets in ${until(w.resetsAt - snap.at)}`}</Text>
+                </Box>
+                <Text dimColor>
+                  {'  '}images this window: {isReset ? 0 : imagesNow}
+                </Text>
+              </Box>
+            )
+          })}
+          {windows.length > 0 && (
+            <Text dimColor>
+              Images share these limits; Codex has no separate image meter.
+              {snap.usage?.asOf ? ` Read ${ago(snap.at - snap.usage.asOf)} ago.` : ''}
+            </Text>
+          )}
+        </Box>
+        {snap.problem && <Text color="red">{snap.problem}</Text>}
+        {!snap.problem && snap.rows.length === 0 && (
+          <Text dimColor>
+            No Codex jobs yet. They appear here when Claude calls codex_plan, codex_code or codex_image.
+          </Text>
+        )}
+        {snap.rows.slice(0, room).map(row => {
+          const age = ago((row.finished ?? snap.at) - row.created)
+          const extra = [
+            row.tool === 'codex_image' ? `images ${row.images ?? 0}${row.count ? `/${row.count}` : ''}` : '',
+            row.attempts > 1 ? `attempt ${row.attempts}` : '',
+          ]
+            .filter(Boolean)
+            .join(', ')
+
+          return (
+            <Box flexDirection="column">
+              <Box gap={1}>
+                <Text color={COLOR[row.status]}>{ICON[row.status]}</Text>
+                <Text bold>{row.tool.replace('codex_', '')}</Text>
+                <Text color={COLOR[row.status]}>{row.status.replace('_', ' ')}</Text>
+                <Text dimColor>{age}</Text>
+                {extra && <Text dimColor>{extra}</Text>}
+              </Box>
+              <Text wrap="truncate-end" dimColor>
+                {row.label || row.id}
+              </Text>
+            </Box>
+          )
+        })}
+        {snap.rows.length > room && <Text dimColor>+{snap.rows.length - room} older</Text>}
+        {interrupted.length > 0 && (
+          <Text dimColor>
+            Interrupted: ask Claude to run codex_resume with job_id {interrupted[0]?.id}
+            {interrupted.length > 1 ? ` (and ${interrupted.length - 1} more)` : ''}.
+          </Text>
+        )}
+      </Box>
+    )
+  })
+}

package/plugins/codex-jobs/types/index.d.ts

@@ -0,0 +1,54 @@
+export type JobStatus = 'running' | 'done' | 'failed' | 'interrupted' | 'cancelled' | 'timed_out'
+
+export type JobRow = {
+  id: string
+  tool: string
+  status: JobStatus
+  // Milliseconds since the epoch.
+  created: number
+  // Set once the job has a result.
+  finished?: number
+  // The request or prompt, one line.
+  label: string
+  // The folder the job works in (cwd for plans and code, output_dir for images).
+  where: string
+  attempts: number
+  // Image jobs only: saved so far, and how many were asked for.
+  images?: number
+  count?: number
+}
+
+// One of Codex's usage windows, as its last session log reported it.
+export type UsageWindow = {
+  usedPercent: number
+  windowMinutes: number
+  // Milliseconds since the epoch.
+  resetsAt: number
+}
+
+export type Usage = {
+  // The 5-hour window and the weekly one. Codex reports one shared meter: images draw on it too.
+  primary?: UsageWindow
+  secondary?: UsageWindow
+  // When Codex wrote the reading.
+  asOf: number
+}
+
+// Images the bridge saved, by when the job started; the pane counts them per usage window.
+export type ImageTally = { at: number; n: number }
+
+export type JobsSnapshot = {
+  rows: JobRow[]
+  images: ImageTally[]
+  usage?: Usage
+  // When the snapshot was read; the pane's elapsed times count up from it.
+  at: number
+  // Set when the jobs folder could not be read.
+  problem?: string
+}
+
+declare module 'claude-code' {
+  interface PluginState {
+    'codex-jobs': { snapshot: Shaped<JobsSnapshot> }
+  }
+}

package/runner.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Runs one attempt of a codex-bridge job, detached from Claude Code, so the job
-// survives Claude closing or crashing. Usage: node runner.mjs <jobId> <attempt>
+// survives Claude closing or crashing. Usage: node runner.mjs <jobId> <attempt> [bridgeHome]
 //
 // Reads   jobs/<id>/job.json, attempt-<n>/spec.json, attempt-<n>/prompt.txt
 // Writes  attempt-<n>/events.jsonl, stderr.txt, state.json, heartbeat, result.json
@@ -8,11 +8,15 @@
 import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
-import {
+
+const [jobId, n, bridgeHome] = process.argv.slice(2);
+// On Windows the runner is started through WMI and does not inherit the server's environment,
+// so the server passes its job storage folder as an argument. lib.mjs reads it at import time.
+if (bridgeHome) process.env.CODEX_BRIDGE_HOME = bridgeHome;
+const {
   EventTail, attemptDir, collectImages, jobDir, jobImages, killTree, readJson, writeJson,
-} from './lib.mjs';
+} = await import('./lib.mjs');
 
-const [jobId, n] = process.argv.slice(2);
 const dir = attemptDir(jobId, n);
 const job = readJson(path.join(jobDir(jobId), 'job.json'));
 const spec = readJson(path.join(dir, 'spec.json'));

package/server.mjs

@@ -9,6 +9,7 @@
 //
 // Tools:
 //   codex_plan   - read-only planning / design review / second opinion
+//   codex_code   - OPT-IN: Codex implements a change, writing only inside CODEX_BRIDGE_WRITE_ROOT
 //   codex_image  - image generation; images are saved into output_dir
 //   codex_result - status/result of jobs (optionally waits); lists jobs
 //   codex_resume - continue an interrupted/failed job where it left off
@@ -20,6 +21,11 @@
 //   CODEX_BRIDGE_IDLE_TIMEOUT_MS   kill a run after this long with no Codex output (default 600000)
 //   CODEX_BRIDGE_PLAN_MODEL        plan model (default: Codex config default)
 //   CODEX_BRIDGE_PLAN_EFFORT       plan reasoning effort (default: Codex config default)
+//   CODEX_BRIDGE_WRITE_ROOT        enables codex_code: the ONE folder Codex may write in (unset = tool off)
+//   CODEX_BRIDGE_WRITE_ALLOW_TMP   1 = codex_code may also write to the system temp dirs. Default: asks Codex to
+//                                  block them. Tested: honoured on Linux/macOS builds only if Codex supports it;
+//                                  NOT enforced on Windows (temp stays writable there)
+//   CODEX_BRIDGE_CODE_MODEL / _EFFORT   codex_code model / reasoning effort (default: Codex config default)
 //   CODEX_BRIDGE_IMAGE_MODEL       image model (default gpt-6-luna)
 //   CODEX_BRIDGE_IMAGE_EFFORT      image reasoning effort (default high)
 
@@ -30,8 +36,8 @@ import path from 'node:path';
 import readline from 'node:readline';
 import { fileURLToPath } from 'node:url';
 import {
-  EventTail, JOBS_DIR, attemptDir, buildCodexArgs, collectImages, isWin, jobDir, jobImages,
-  pidAlive, readJson, resolveCodexBin, writeJson,
+  BRIDGE_HOME, EventTail, JOBS_DIR, attemptDir, buildCodexArgs, collectImages, insideWriteRoot, isWin, jobDir, jobImages,
+  pidAlive, readJson, resolveCodexBin, resolveWriteRoot, writeJson,
 } from './lib.mjs';
 
 const PKG = JSON.parse(fs.readFileSync(new URL('./package.json', import.meta.url), 'utf8'));
@@ -41,21 +47,31 @@ const IDLE_TIMEOUT_MS = Number(process.env.CODEX_BRIDGE_IDLE_TIMEOUT_MS) || 10 *
 const DEFAULTS = {
   codex_plan: { model: process.env.CODEX_BRIDGE_PLAN_MODEL || '', effort: process.env.CODEX_BRIDGE_PLAN_EFFORT || '' },
   codex_image: { model: process.env.CODEX_BRIDGE_IMAGE_MODEL || 'gpt-6-luna', effort: process.env.CODEX_BRIDGE_IMAGE_EFFORT || 'high' },
+  codex_code: { model: process.env.CODEX_BRIDGE_CODE_MODEL || '', effort: process.env.CODEX_BRIDGE_CODE_EFFORT || '' },
 };
 const EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max', 'ultra'];
 const MAX_WAIT_S = 240;
 const STALE_HEARTBEAT_MS = 10 * 60 * 1000;
 const PRUNE_AFTER_MS = 14 * 24 * 3600 * 1000;
 const CODEX_BIN = resolveCodexBin();
+const WRITE_ALLOW_TMP = process.env.CODEX_BRIDGE_WRITE_ALLOW_TMP === '1';
+let WRITE_ROOT = null; // set only when the user opts in to codex_code
+try { WRITE_ROOT = resolveWriteRoot(); } catch (err) { process.stderr.write(`codex-bridge: codex_code stays off: ${err.message}\n`); }
 
 if (process.argv.includes('--version') || process.argv.includes('-v')) {
   console.log(PKG.version);
   process.exit(0);
 }
+// Where the bundled codex-jobs pane add-on lives, for `claude --plugin-dir "$(npx ... --pane-path)"`.
+if (process.argv.includes('--pane-path')) {
+  console.log(path.join(path.dirname(fileURLToPath(import.meta.url)), 'plugins', 'codex-jobs'));
+  process.exit(0);
+}
 if (process.argv.includes('--help') || process.argv.includes('-h') || process.stdin.isTTY) {
   console.log(`codex-bridge ${PKG.version}: an MCP server (stdio) that lets Claude Code consult the Codex CLI.
 It is started by an MCP client, not run by hand. Register it with Claude Code:
   claude mcp add codex-bridge -- npx -y @xallindrome-labs/codex-bridge
+Flags: --version, --help, --pane-path (print the folder of the bundled codex-jobs pane add-on)
 Docs: ${PKG.homepage}`);
   process.exit(0);
 }
@@ -74,6 +90,18 @@ Rules:
 Request from Claude Code:
 `;
 
+const CODE_PREAMBLE = cwd => `You are the BUILDER in a two-agent workflow. Claude Code is the reviewer and will check your work.
+Rules:
+- Work only inside ${cwd}. Your sandbox allows writes there and nowhere else; do not try to work around it.
+- Make the change that was asked for and nothing else: no unrelated refactors, renames or reformatting.
+- Do not commit, push, create branches or change git config. Leave your changes uncommitted in the working tree so Claude can review the diff.
+- Do not install global packages. The sandbox has no network access: if the task needs a dependency or the network, stop and say so instead of guessing.
+- Run the project's tests or linters if you can and report the exact result. If something cannot run in the sandbox, say what and why.
+- When finished, reply with: a short summary, the files you created, changed or deleted, and how you verified.
+
+Task from Claude Code:
+`;
+
 // Codex only generates; the runner collects each image from Codex's image store
 // the moment it appears. (Left to save files itself, Codex may re-type the image
 // as base64 through shell commands: slow, and can corrupt the file.)
@@ -91,8 +119,9 @@ Request:
 `;
 
 function initialPrompt(tool, args) {
-  if (tool === 'codex_plan') {
-    return (args.session_id ? '' : PLAN_PREAMBLE) + args.request + (args.context ? `\n\nContext:\n${args.context}` : '');
+  if (tool === 'codex_plan' || tool === 'codex_code') {
+    const preamble = tool === 'codex_code' ? CODE_PREAMBLE(args.cwd) : PLAN_PREAMBLE;
+    return (args.session_id ? '' : preamble) + args.request + (args.context ? `\n\nContext:\n${args.context}` : '');
   }
   return args.session_id ? `${args.prompt}\n\nRules:\n${IMAGE_RULES}` : IMAGE_PREAMBLE(args.count) + args.prompt;
 }
@@ -101,6 +130,9 @@ function resumePrompt(job) {
   if (job.tool === 'codex_plan') {
     return 'Your previous run on this request was interrupted before you finished. Continue from where you stopped and give your complete final answer.';
   }
+  if (job.tool === 'codex_code') {
+    return 'Your previous run on this task was interrupted before you finished. Some of your edits may already be in the working tree: inspect the current state first, do not redo finished work, then finish the task and give your final summary (files changed, how you verified).';
+  }
   const done = jobImages(job).length;
   const remaining = job.args.count ? Math.max(job.args.count - done, 0) : null;
   return `Your previous run on this request was interrupted before it finished. ${done} image(s) were already generated and collected; do NOT regenerate them.
@@ -112,6 +144,7 @@ ${IMAGE_RULES}
 
 // ---------------------------------------------------------------- jobs
 
+const WRITE_OFF = 'codex_code is switched off. To let Codex write files, the user must set CODEX_BRIDGE_WRITE_ROOT to the one folder it may edit, then restart the MCP server.';
 const newJobId = () => `job-${new Date().toISOString().replace(/[-:T]/g, '').slice(2, 14)}-${crypto.randomBytes(2).toString('hex')}`;
 const loadJob = id => readJson(path.join(jobDir(id), 'job.json'));
 const saveJob = job => writeJson(path.join(jobDir(job.id), 'job.json'), job);
@@ -120,12 +153,12 @@ const saveJob = job => writeJson(path.join(jobDir(job.id), 'job.json'), job);
 // closing Claude doesn't kill it. On Windows that means WMI Win32_Process.Create.
 function launchRunner(jobId, n, cwd) {
   if (!isWin) {
-    const c = spawn(process.execPath, [RUNNER, jobId, String(n)], { cwd, detached: true, stdio: 'ignore' });
+    const c = spawn(process.execPath, [RUNNER, jobId, String(n), BRIDGE_HOME], { cwd, detached: true, stdio: 'ignore' });
     c.unref();
     return Promise.resolve(c.pid);
   }
   const q = s => `'${String(s).replace(/'/g, "''")}'`;
-  const cmdLine = `"${process.execPath}" "${RUNNER}" ${jobId} ${n}`;
+  const cmdLine = `"${process.execPath}" "${RUNNER}" ${jobId} ${n} "${BRIDGE_HOME}"`;
   const ps = `$ErrorActionPreference = 'Stop'
 $si = New-CimInstance -ClassName Win32_ProcessStartup -ClientOnly -Property @{ ShowWindow = [uint16]0 }
 $r = Invoke-CimMethod -ClassName Win32_Process -MethodName Create -Arguments @{ CommandLine = ${q(cmdLine)}; CurrentDirectory = ${q(cwd)}; ProcessStartupInformation = $si }
@@ -149,15 +182,21 @@ async function launchAttempt(job, prompt, sessionId) {
   const n = job.attempts + 1;
   const dir = attemptDir(job.id, n);
   fs.mkdirSync(dir); // throws EEXIST if another session launched this attempt first
-  const cwd = job.tool === 'codex_plan' ? job.cwd : job.outDir;
+  const cwd = job.cwd ?? job.outDir;
+  const writes = job.tool === 'codex_code';
+  if (writes) { // re-checked on every attempt: a resume must not outlive the user's opt-in
+    if (!WRITE_ROOT) throw new Error(WRITE_OFF);
+    insideWriteRoot(WRITE_ROOT, cwd);
+  }
   fs.writeFileSync(path.join(dir, 'prompt.txt'), prompt);
   writeJson(path.join(dir, 'spec.json'), {
     bin: CODEX_BIN,
     cwd,
     args: buildCodexArgs({
-      sandbox: 'read-only',
+      sandbox: writes ? 'workspace-write' : 'read-only',
       cwd, sessionId, model: job.model, effort: job.effort,
       images: n === 1 ? job.refs : [],
+      allowTmp: WRITE_ALLOW_TMP,
     }),
     env: process.env.CODEX_HOME ? { CODEX_HOME: process.env.CODEX_HOME } : {},
     idleTimeoutMs: IDLE_TIMEOUT_MS,
@@ -180,9 +219,14 @@ async function startJob(tool, args) {
     created: Date.now(),
     attempts: 0,
   };
-  if (tool === 'codex_plan') {
+  if (tool === 'codex_plan' || tool === 'codex_code') {
     job.cwd = path.resolve(args.cwd);
     if (!fs.existsSync(job.cwd)) throw new Error(`cwd does not exist: ${job.cwd}`);
+    if (tool === 'codex_code') {
+      if (!WRITE_ROOT) throw new Error(WRITE_OFF);
+      job.cwd = insideWriteRoot(WRITE_ROOT, job.cwd);
+      args.cwd = job.cwd;
+    }
   } else {
     job.outDir = path.resolve(args.output_dir);
     fs.mkdirSync(job.outDir, { recursive: true });
@@ -227,7 +271,7 @@ function imageCount(job) {
 function jobLine(job) {
   const { status, result } = jobStatus(job);
   const age = secs((result?.finished ?? Date.now()) - job.created);
-  const where = job.tool === 'codex_plan' ? job.cwd : job.outDir;
+  const where = job.cwd ?? job.outDir;
   const label = (job.args.request || job.args.prompt || '').replace(/\s+/g, ' ').slice(0, 70);
   const extra = [job.tool === 'codex_image' ? imageCount(job) : null, job.attempts > 1 ? `attempt ${job.attempts}` : null].filter(Boolean).join(', ');
   return `${job.id} [${job.tool}] ${status}, ${age}${extra ? `, ${extra}` : ''} - ${label} (${where})`;
@@ -247,6 +291,11 @@ function renderResult(job, result) {
     if (result.stderrTail) lines.push(result.stderrTail);
   }
   if (result.message) lines.push(result.message);
+  if (job.tool === 'codex_code') {
+    lines.push('', result.status === 'done'
+      ? `Codex edited files in ${job.cwd} and committed nothing. Review the diff (git diff / git status) before accepting it.`
+      : `Codex may have made partial edits in ${job.cwd}. Check git status / git diff before continuing.`);
+  }
   lines.push('', '---',
     `job_id: ${job.id}${job.attempts > 1 ? ` (attempt ${job.attempts})` : ''}`,
     `session_id: ${result.threadId ?? 'unknown'} (pass as session_id to continue this Codex thread)`,
@@ -383,8 +432,34 @@ const TOOLS = [
   },
 ];
 
+// Only listed when the user opted in with CODEX_BRIDGE_WRITE_ROOT.
+if (WRITE_ROOT) {
+  TOOLS.splice(1, 0, {
+    name: 'codex_code',
+    description:
+      'Ask Codex (OpenAI) to IMPLEMENT a change: it edits files directly, inside ' + WRITE_ROOT + ' (the one folder the user allowed; temp files may also be writable). ' +
+      'It has no network access and does not commit. `cwd` must be that folder or one inside it. Claude stays the reviewer: afterwards read the diff (git diff) ' +
+      'and test before accepting, and fix or send follow-ups with session_id. Use it for well-specified, self-contained work; use codex_plan when you only need a plan. ' +
+      'Calls can take many minutes; use background=true to keep working meanwhile, and avoid editing the same files yourself while it runs.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        request: { type: 'string', description: 'What to implement. Include the goal, constraints, files involved and acceptance criteria / how to verify.' },
+        cwd: { type: 'string', description: `Absolute path of the project folder Codex edits. Must be ${WRITE_ROOT} or inside it.` },
+        context: { type: 'string', description: 'Optional extra context: a plan to follow, error output, decisions already made.' },
+        session_id: { type: 'string', description: 'Optional. Continue an earlier Codex thread (e.g. to fix review comments).' },
+        effort: { type: 'string', enum: EFFORTS, description: 'Optional reasoning effort. Default: the user\'s Codex config.' },
+        model: { type: 'string', description: 'Optional Codex model override. Default: the user\'s Codex config.' },
+        background: BACKGROUND_PROP,
+      },
+      required: ['request', 'cwd'],
+    },
+  });
+}
+
 async function callJobTool(name, args, onActivity) {
-  if (name === 'codex_plan' && (!args.request || !args.cwd)) throw new Error('request and cwd are required');
+  if (name === 'codex_code' && !WRITE_ROOT) throw new Error(WRITE_OFF);
+  if ((name === 'codex_plan' || name === 'codex_code') && (!args.request || !args.cwd)) throw new Error('request and cwd are required');
   if (name === 'codex_image' && (!args.prompt || !args.output_dir)) throw new Error('prompt and output_dir are required');
   if (args.effort && !EFFORTS.includes(args.effort)) throw new Error(`effort must be one of ${EFFORTS.join(', ')}`);
   const job = await startJob(name, args);
@@ -451,6 +526,9 @@ function instructions() {
   let text = 'Use codex_plan to get an implementation plan or second opinion from Codex (read-only), and codex_image to have Codex generate images. ' +
     'Claude implements; Codex plans and builds images. Codex calls take minutes: when there is other work to do meanwhile, pass background=true and collect the result with codex_result. ' +
     'Jobs are durable: they survive Claude closing, and codex_resume continues interrupted ones.';
+  if (WRITE_ROOT) {
+    text += ` The user also enabled codex_code: Codex may implement changes by editing files, but only inside ${WRITE_ROOT}. Review its diff before accepting it.`;
+  }
   try {
     const interrupted = listJobs().filter(j => jobStatus(j).status === 'interrupted').slice(0, 10);
     if (interrupted.length) {
@@ -488,7 +566,7 @@ async function handle(msg) {
       };
       try {
         let out;
-        if (name === 'codex_plan' || name === 'codex_image') out = await callJobTool(name, args, onActivity);
+        if (name === 'codex_plan' || name === 'codex_image' || name === 'codex_code') out = await callJobTool(name, args, onActivity);
         else if (name === 'codex_result') out = await jobResult(args);
         else if (name === 'codex_resume') out = await resumeJob(args);
         else if (name === 'codex_cancel') out = cancelJob(args);