Never sends messages automatically. It keeps unfinished Codex and Claude Code sessions in your menu bar until you deal with them.
Codex Draft Inbox is a local-first Codex plugin with a companion macOS menu bar app. It gathers running, completed, and drafted Codex and Claude Code sessions into one inbox and keeps them there until you explicitly mark them as handled.
It is designed for people who run several agent tasks at once. You can draft the next message in one Codex session, switch to other work, and return later. When a task finishes, the menu bar app retains its title, draft, and execution state so you do not forget to continue after reading the result.
- Shows Codex and Claude Code sessions together and groups them with their own logos when the official apps are detected at build time.
- Adds a user session to the inbox as soon as it starts; any non-empty draft bound to a real Codex session also appears.
- Shows the real session title and current draft, or a reminder when there is no draft.
- Separates the message currently being processed, queued messages waiting to be sent, and the next draft in the input box while a task is running.
- Follows Codex sidebar titles; internal subagents, exec sessions, and unbound temporary drafts do not enter the list.
- Uses yellow for running or draft-only sessions, green for a completed turn, red for failures, and orange for stopped turns.
- Sorts Codex and Claude Code sessions together by recent activity; newly completed tasks move to the top, briefly highlight, and can open the panel automatically.
- Marks completed tasks as unread until they are opened through the plugin with Open Task / Resume Session.
- Retains archived, deleted, hidden, and temporarily unconfirmed Codex sessions and labels their state beside the title.
- Returns an older item to the top when it receives a new turn or draft.
- Opens the corresponding Codex session or resumes a Claude Code session in Terminal.
- Removes an item only when you click Handled. Opening it, reading it, clearing its draft, or finishing the task does not remove it.
- Keeps the archived Handle All action and adds Clear All, which removes only conversations that are not running and have neither queued messages nor a draft.
- Hides draft content from notifications by default; notification previews can be enabled from the bottom of the panel.
- Follows the macOS system language by default, with Simplified Chinese and English overrides in the panel. Notifications use the same language.
- Starts automatically after macOS login.
- Shows progress during manual refresh and queues one follow-up refresh if a background sync is already running.
- Stores all state locally, uploads no drafts, and never sends a message automatically.
This is not a single UI extension embedded in the Codex window. It is a set of local components that work together:
Codex hooks + local session state ─┐
├─ Python sync engine ─ pending.json ─ macOS menu bar app
Claude Code hooks ─────────────────┘ ├─ Open task
└─ Mark handled
.codex-plugin/plugin.json,hooks.json, andskills/form the Codex plugin.scripts/draft_inbox.pyreads session titles, drafts, and the latest turn state, then maintains the local inbox.macos-app/is a native SwiftUI menu bar app.SMAppService.mainAppprovides login startup on macOS 13 and later. A legacy LaunchAgent is stopped and moved out of~/Library/LaunchAgentsduring upgrades.
| Component | Requirement |
|---|---|
| Operating system | macOS 13 Ventura or later |
| Codex | Codex desktop client or CLI with plugin and local session-state support |
| Claude Code | Optional; requires SessionStart, UserPromptSubmit, Stop, StopFailure, and SessionEnd hooks |
| Python | /usr/bin/python3, Python 3.9 or later |
| Build tools | Xcode Command Line Tools with Swift 6 and codesign |
The menu bar app currently supports macOS only. Codex's local state format is a client implementation detail, so future client changes may require corresponding updates here.
The build script reads the Codex/ChatGPT and Claude app icons installed on the current Mac and copies them into the local build artifact. This repository does not redistribute third-party brand assets. When an app is not detected, the UI uses a generic application icon without affecting inbox behavior.
The Codex plugin and menu bar app are separate components. Install the plugin through the marketplace. Download the app from GitHub Releases or build it from source.
git clone https://github.com/Zhangs-11/codex-draft-inbox.git
cd codex-draft-inboxAdd this repository as a Codex marketplace, then install the plugin:
codex plugin marketplace add Zhangs-11/codex-draft-inbox
codex plugin add codex-draft-inbox@codex-draft-inboxStart a new Codex session after installing or upgrading so Codex reloads the skill and hooks.
Download the latest Codex-Draft-Inbox-v<version>-macos-universal.zip and matching .sha256 file from Releases. The package contains both arm64 and x86_64 builds for Apple silicon and Intel Macs. Verify it in the download directory, replacing <version> with the actual version:
shasum -a 256 -c Codex-Draft-Inbox-v<version>-macos-universal.zip.sha256Extract it, then run:
cd "Codex Draft Inbox v<version>"
./scripts/install_release.shTo enable Claude Code integration at the same time:
./scripts/install_release.sh --with-claudeThe current release uses a local ad-hoc signature. It is an open-source preview build and is not notarized with an Apple Developer ID. The universal binary has been statically checked for both architectures and installed on Apple silicon; execution on physical Intel hardware remains unverified. Release packages do not redistribute third-party logos and therefore use generic group icons. Source builds attempt to use official icons from apps installed on the local Mac.
./scripts/install_macos_app.shThe script:
- builds and signs
~/Applications/Codex Draft Inbox.app; - registers login startup through macOS
SMAppService; - launches the menu bar app.
If the Swift toolchain is missing, run:
xcode-select --installInstall the menu bar app first, then run:
/usr/bin/python3 ./scripts/install_claude_hooks.pyThe installer updates only the five hook types used by this project in ~/.claude/settings.json and preserves all other settings and hooks. Restart Claude Code for the changes to take effect.
After installation, a conversation-bubble icon and inbox count appear in the menu bar:
- Start a task in Codex or Claude Code.
- Switch to another session. In Codex, you can prepare the next draft in advance.
- Click the menu bar icon to view every session that still needs attention.
- Click Open Task to return to the original session and continue from its latest result.
- Click Handled only when no further follow-up is needed.
If a Codex session is later archived or deleted, it remains in the inbox with the corresponding label. Deleted and hidden sessions cannot be opened but can still be marked as handled.
Inside Codex, you can also ask which sessions remain unhandled or request that a specific item be opened or cleared. The plugin's draft-inbox skill reads the same local list.
| Capability | Codex | Claude Code |
|---|---|---|
| Session title | Reads local Codex session data | Builds a preview from the latest submitted message |
| Current submitted message | Reads the active turn rollout | Reads the UserPromptSubmit hook |
| Queued messages | Reads the Codex local queue in order | No corresponding terminal queue interface |
| Unsent draft | Reads the existing Codex client draft | Cannot read terminal input; drafts must be saved from the menu bar card |
| Execution state | Reads the latest turn rollout state | Synchronized by Claude Code lifecycle hooks |
| Open session | Uses codex://threads/<id> |
Uses claude --resume <session-id> for completed sessions; running sessions only activate Terminal |
Runtime files are stored under:
~/.codex/draft-inbox/pending.json
~/.codex/draft-inbox/pending.json.bak
~/.codex/draft-inbox/observed.json
~/.codex/draft-inbox/claude.json
~/.codex/draft-inbox/settings.json
The app has read-only access to Codex's local draft state, session SQLite database, queue database, and rollout logs so it can obtain titles, real session IDs, the current submitted message, queued messages, and execution state. It never writes to Codex databases. Current and queued messages remain only in the local inbox file and never appear in system notifications. Apart from checking for a new version once per day, it does not connect to external services. The version check accesses only the GitHub Releases API and never uploads inbox items, drafts, or session content. It never sends drafts automatically. Notifications hide draft content by default; when Show drafts in notifications is enabled, they include only a truncated preview. The app keeps the latest valid backup before updating the inbox and restores it if the primary state file is corrupted.
Starting with v0.2.3, the menu bar app checks GitHub Releases every 24 hours. When a new version is available, an update notice appears at the top of the panel. You can also click Check for Updates at the bottom. The app only opens the corresponding GitHub Release page and never downloads or installs an update silently.
Starting with v0.2.4, only tasks previously confirmed in the Codex user-session table are marked as deleted if they later disappear. Legacy temporary IDs that never became real sessions are removed automatically. Claude Code subagents and automated sessions with an explicit internal worker protocol are also excluded from the inbox.
Starting with v0.3.0, Codex and Claude Code use one list sorted globally by recent activity. When a running task completes, the panel can open automatically without taking keyboard focus, and the completed card briefly receives a green animated highlight. Clicking elsewhere on the desktop closes the panel. Auto-open on completion can be disabled at the bottom of the panel.
Starting with v0.3.1, the app listens for mouse clicks in other apps and on the desktop during automatic display and closes the panel itself instead of relying only on the default behavior of a transient macOS popover.
Starting with v0.3.2, newly completed tasks show an unread state. Codex follows the client's native blue dot, so opening the session from either the sidebar or plugin marks it as read. Claude Code has no corresponding field, so the plugin clears the state after Resume Session succeeds. Viewing an automatic popup does not count as reading. A later task in the same session becomes unread again when it completes. Failed and stopped tasks use separate states and do not trigger a success notification. Upgrade installation waits for the old process to exit and verifies that the new app has started.
Starting with v0.3.3, the inbox panel closes immediately after Open Task / Resume Session successfully initiates navigation. If opening fails, the panel stays visible and shows the error so you can retry.
Starting with v0.4.0, the menu bar app supports Follow System, Simplified Chinese, and English language settings. The local selection takes effect immediately across the panel, states, errors, accessibility labels, and system notifications. Session titles and draft text remain unchanged.
Starting with v0.4.1, running tasks display the current submitted message, messages received by Codex and queued for sending, and the input-box draft separately. Drafts support the current composer-prompt-drafts-v2 format and legacy v1. Multiple queued messages follow Codex's queue_order and automatically move from Waiting to Send to Processing when execution begins. Processing is hidden after a task completes, fails, or stops.
Starting with v0.4.2, settings include a Handle All action that removes every archived inbox item in one local batch operation. The action remains visible but is disabled when the archived count is zero or an operation is already running. Active, deleted, hidden, unknown-state, and Claude Code items are unaffected.
Starting with v0.4.3, settings also provide a separate Clear All action for Codex and Claude Code conversations that are not running and have neither queued messages nor a draft; the archived action keeps its original behavior.
On first installation or migration from the legacy LaunchAgent, macOS may show a login-item notification because the menu bar app registers itself to start after login. This is a macOS transparency notice and cannot be suppressed by the app. Later updates do not create another legacy background item after migration is complete.
Versions v0.2.2 and earlier do not include update checks. Download a newer release manually and rerun the installer; existing inbox data and settings are preserved. Update notices apply to the menu bar app. Upgrade the Codex plugin separately through the marketplace. For source installations, run:
git pull
codex plugin marketplace upgrade codex-draft-inbox
codex plugin add codex-draft-inbox@codex-draft-inbox
./scripts/install_macos_app.shWhen Claude Code integration is enabled, menu bar app upgrades keep using the synchronization script bundled inside the app, so the hooks do not need to be reinstalled.
By default, the uninstaller removes the app, login item, legacy LaunchAgent, Claude hooks, and public marketplace plugin while preserving local inbox data:
./scripts/uninstall.shTo also delete inbox data and settings under ~/.codex/draft-inbox/:
./scripts/uninstall.sh --purge-dataThe uninstaller removes only this project's Claude hooks and preserves all other hooks and settings in settings.json.
python3 -m unittest discover -s tests -v
python3 scripts/draft_inbox.py list --json
./scripts/test_macos_app.shGitHub Actions repeats compatibility tests under Python 3.9, Python 3.13, and Swift 6. Plugin developers can also use Codex's built-in plugin-creator skill to validate the plugin manifest.
- The menu bar app does not support Windows or Linux.
- Claude Code text that has not been submitted from the terminal cannot be read.
- State colors describe the latest turn, not whether you have read it.
- Changes to Codex's local client-state format may require updates here.
- Running Claude Code sessions can only activate Terminal, not target the exact terminal window.
- macOS may temporarily hide the icon when menu bar space is limited. Hold
Commandand drag it farther to the right. - The current distribution uses a local ad-hoc signature rather than Apple Developer ID notarization. If macOS blocks the first launch, allow it under System Settings → Privacy & Security.
This license covers only the code in this repository. OpenAI, Codex, Anthropic, and Claude names and marks belong to their respective owners. This project is not affiliated with, sponsored by, or endorsed by OpenAI or Anthropic.