Codex Bee

codex-bee is a transparent wrapper around Codex CLI. It keeps you in the real Codex terminal, adds a companion screen for logs and session controls, and can optionally keep repetitive work moving by sending a prewritten prompt after each completed turn.

Start in 30 seconds

Use npx if you want to try it right away:

npx @usulpro/codex-bee codex

On first launch, Codex-Bee checks that Codex hooks are enabled and that the required hook entries are present. If the global setup is missing, it can prompt you to create or update it before the session starts.

Quick tour

1. Launch Codex through Bee by running bee codex in your terminal. You still work in the real Codex CLI session. Bee wraps it without replacing it.
2. Press Ctrl+B to open the Bee screen. This is where you see the current mode, recent turns, live session stats, and the prompt composer. Press Shift+Tab to switch modes.

3. Stay in Off mode if you only want logs and stats, or switch to Static and stage the prompt Bee should send after each completed turn. Switch back to Codex with Ctrl+B and submit your prompt as usual.

4. Once Static is active, Bee follows the session turn by turn and waits for each completed turn before deciding whether to continue.

5. Press Ctrl+B again to return to Codex. When a turn ends in Static, Bee sends the prepared prompt back into the real Codex input.

For more detail, see Modes, Slash commands, and How it works.

Why use it

• Keep Codex moving instead of stopping for intermediate status reports.
• Run long Codex sessions with explicit time or iteration limits.
• Define your own continuation prompt for the next iteration.
• Run multiple long Codex sessions in parallel without losing track of them.
• See session stats at a glance, including active time, idle time, and iteration count.

Install

npm i -g @usulpro/codex-bee

Usage

bee codex passes all remaining arguments through to Codex unchanged:

bee codex
bee codex resume --last --yolo
bee codex "Summarize this repository"

Features

• Does not replace or modify the Codex CLI binary. You keep working with the installed Codex package and all of its features.
• Detects completed turns and can emulate input for any continuation prompt you define.
• Lets you limit repeated automatic iterations by step count or session duration.
• Shows Codex session logs and work statistics in the Bee window.
• Keeps your data on your machine. It does not send or store your prompts, logs, stats, or session data anywhere else.

Modes

| Mode | Behavior | | --- | --- | | Off | Default mode. Bee does not affect Codex, but it keeps showing logs and live stats for the current session. | | Static | Bee inserts the current prewritten prompt into Codex input whenever a turn ends. |

Slash commands

Type / in the Bee composer to open the command list.

| Command | Purpose | | --- | --- | | /duration <duration> | Set a session time limit, for example 90m or 1.5h. | | /sleep <HH:MM> | Stop at an absolute local time, for example 23:30. | | /steps-count <number> | Set the maximum number of continued turns. | | /clear-limits | Clear time and turn limits. | | /stop-script <command> | Run a post-turn verification command. A successful exit stops continuation; failures are summarized for the next prompt. | | /clear-log | Clear the Bee turn log. | | /quit | Exit codex-bee. |

How it works

codex-bee is a transparent wrapper around the real Codex CLI. In the default Codex view, it passes terminal input and output straight through to the live Codex session, so working through Bee feels the same as working with Codex directly. When you open the Bee screen, you are only changing Bee's own session controls such as the mode, limits, and verification command. It does not replace or modify Codex features.

To work correctly, Bee needs Codex hooks to be configured. That means:

• a global or project-local .codex/hooks.json with the required SessionStart, UserPromptSubmit, and Stop hook entries
• codex_hooks = true in the active Codex config or profile

You can set this up globally on your machine or locally in a project, depending on how you run Codex. On startup, Bee checks that the required hook setup is present and warns or offers to create or update the missing hook entry when needed.

At runtime, Bee starts the real Codex process inside an interactive PTY and keeps forwarding terminal traffic while Codex is on screen. Hook events are captured in the background, and Bee watches for the matching session data as the run progresses. To avoid mixing parallel sessions, each wrapper run gets its own CODEX_BEE_RUN_ID, and Bee matches incoming hook captures by run ID, current working directory, and the session metadata carried by the hook payload.

A matched Stop event tells Bee that the current turn has ended. Bee uses that signal for logs and session stats in every mode. In Static mode, it can then apply limits or a verification command, and if continuation is still allowed, it sends the prepared prompt back into Codex input using bracketed paste so multiline prompts stay intact.

Requirements

• Node.js 20+
• Codex CLI installed and authenticated

OS compatibility

| OS | Status | | --- | --- | | Linux (Debian) | Supported | | macOS | On the roadmap | | Windows | Not supported |

Development

pnpm install
pnpm build
pnpm test
pnpm typecheck
pnpm package:check
pnpm ui:demo

For isolated TUI work, see the TUI development notes.

Contributing

Issues and pull requests are welcome:

• Bugs and feature requests: GitHub Issues
• Source code: github.com/usulpro/codex-bee

If a change affects the public workflow, update the README and screenshots in the same pull request.

License

MIT