Agents · Codex
Run Codex in the background
Run OpenAI’s Codex CLI on real tasks without watching it. wisp starts codex exec in a fresh worktree, keeps the sandbox you pick, and turns the JSON event stream into a readable report: what changed, what ran, what passed.
Free and open source · uses your own OpenAI account · macOS, Linux, Windows (beta) · Node 20+
What wisp adds to Codex
- A worktree per task. Each task gets its own branch from
origin/main, so several Codex runs can work on the same repo at once without colliding. - A report instead of a transcript. When the run ends you read a headline, the numbers that changed, the real diff from its own edits, the test run and what to do next.
- Questions mid-run. When it needs a decision, the card moves to Needs you and you get a notification, on your desktop or your phone.
- Ship it. One click commits, pushes and opens the pull request; the card follows CI and review, and Merge syncs your local main.
- Take over any time. Press T and your terminal opens in the worktree with
codex resume <id>.
How wisp runs Codex
wisp doesn’t replace or wrap Codex’s model access: it starts the codex CLI you already have installed and signed in, in headless mode, and reads its event stream. Roughly:
codex exec --json --skip-git-repo-check \
-c sandbox_mode="workspace-write" \
-c mcp_servers.wisp.command=…Follow-ups resume the same session, so Codex keeps its context. Override the binary with WISP_CODEX_BIN.
Permission modes
Pick a mode per launch in the launcher (ShiftTab cycles them) or with --mode on the CLI. Here is what each one passes to codex:
| wisp mode | Codex flag |
|---|---|
| Plan (read-only) | -c sandbox_mode="read-only" |
| Edits | -c sandbox_mode="workspace-write" |
| Full auto | --dangerously-bypass-approvals-and-sandbox |
Codex has no “accept edits only” mode, so Edits uses the workspace-write sandbox: it edits the project and runs sandboxed commands. Anything the sandbox refuses shows up on the card with Allow & retry.
Questions, /btw and take over
- Asking you
- An MCP tool,
mcp__wisp__ask_user, configured for the run. Codex pauses on it, and your answer comes back as the tool result. /btwside questions- Type
/btw did you update the docs too?while it works. The question is answered on a fork of the thread (codex exec fork <id>), so it knows what the run did and why; the running task never sees it. - Take over
- Press T on the card, or run
codex resume <id>yourself in the task’s worktree. - Models
- Any model your Codex CLI can use, plus a reasoning level passed as
-c model_reasoning_effort.
- Several folders in one task:
--add-diron the first turn, writable roots in the sandbox config after that. - Pasted screenshots go in as images.
- Compare: run the same task on Codex and Claude Code side by side and keep the better branch.
Get started
- Install Codex and sign in. Follow OpenAI’s instructions until
codexruns in your terminal. - Start wisp.
- Pick Codex in the launcher, describe the task and press Enter. From a shell:
wisp "fix the flaky auth test" --agent codex.
Run it next to other agents
The same queue takes every harness. Compare one task on two of them side by side, or let Auto pick the harness and model per task from what worked before.
Guides: Run Claude Code and Codex in parallel · Run coding agents on multiple machines · Multi-agent coding across Claude Code, Codex and more.