Non-interrupting mailbox companion for Codex worktrees.
Built by Adem Isler · MIT licensed · macOS and Linux development builds
CodexPigeon lets a human leave repo-local guidance for a Codex task without injecting into the active chat turn.
It gives each selected repo/worktree a .codex-mailbox/ folder. The app and CLI
append human messages to INBOX.md; the Codex agent reads those messages at
safe checkpoints through installed project instructions and hooks, then writes
status back to agent-owned files.
The product invariant is strict:
- no active chat steering
- no chat message injection
- no turn interruption or turn start APIs
- no App Server write APIs
- no app writes to agent-owned
OUTBOX.mdorRECEIPTS.md
This repository is intended to be inspectable. The mailbox protocol is plain Markdown, runtime files are repo-local, and all Codex App Server access is restricted to read/status/discovery methods.
The current release is a working MVP for local macOS and Linux development. Signed packages can be added later without changing the protocol.
The README screenshot is captured from demo mode with synthetic workspace paths and synthetic mailbox content. It does not show private Codex state.
| Area | Included |
|---|---|
| Desktop app | Electron + React + Vite app with mailbox, receipts, outbox, install, and diagnostics views |
| CLI | codexpigeon doctor, install, send, watch, snapshot, and automation commands |
| Mailbox core | Parser, serializer, installer, validation, file ownership, and repeat scheduling |
| Codex integration | Read-only App Server client for thread and hook discovery |
| Hooks | Project-local hook runtime copied into trusted workspaces |
| Templates | Managed AGENTS.md, .codex/hooks.json, and .codex-mailbox/ templates |
| Tests | Mailbox behavior, installer boundaries, hook runtime, and App Server allowlist coverage |
| Without CodexPigeon | With CodexPigeon |
|---|---|
| You must interrupt an active chat to add context | You leave a mailbox note for the next safe checkpoint |
| Guidance can get mixed into conversational flow | Guidance is stored as repo-local working state |
| Follow-up reminders are manual | Optional repeats append normal inbox messages while the app/CLI is running |
| App Server boundaries are easy to blur | Mutating App Server methods are rejected by design |
Requirements:
- Node.js 22+
- pnpm 11+
- Python 3 for installed project hooks
- Codex CLI/App Server for live thread discovery
pnpm install
pnpm typecheck
pnpm test
pnpm build
pnpm install:macThis creates:
~/.local/bin/codexpigeon
~/.local/bin/codexpigeon-desktop
/Applications/CodexPigeon.app # preferred when /Applications is writable
~/Applications/CodexPigeon.app # fallback when /Applications is not writable
Then run:
codexpigeon doctor
codexpigeon-desktopRun the browser development shell:
pnpm devOpen:
http://127.0.0.1:5173/
Browser mode uses a Vite-local Node API and cannot open a native folder picker. Type an absolute repo/worktree path in the right inspector.
Run the full Electron runtime:
pnpm --filter @codexpigeon/desktop dev:electronRun sanitized demo mode for screenshots:
http://127.0.0.1:5173/?demo=1
During development:
pnpm --filter @codexpigeon/cli start -- doctor
pnpm --filter @codexpigeon/cli start -- install --workspace /path/to/worktree
pnpm --filter @codexpigeon/cli start -- send --workspace /path/to/worktree "Check the mailbox before final response."
pnpm --filter @codexpigeon/cli start -- send --workspace /path/to/worktree --repeat-every 5m "Please re-check the release gate."
pnpm --filter @codexpigeon/cli start -- watch --workspace /path/to/worktree
pnpm --filter @codexpigeon/cli start -- snapshot --workspace /path/to/worktree
pnpm --filter @codexpigeon/cli start -- automation list --workspace /path/to/worktree
pnpm --filter @codexpigeon/cli start -- automation stop --workspace /path/to/worktree auto_...After pnpm build, the compiled CLI is exposed from
packages/cli/dist/index.js and from the local macOS wrapper installed by
pnpm install:mac.
Installing CodexPigeon into a repo/worktree creates or updates:
AGENTS.md
.codex/hooks.json
.codex/hooks/codexpigeon_mailbox_hook.py
.codex-mailbox/README.md
.codex-mailbox/.gitignore
.codex-mailbox/INBOX.md
.codex-mailbox/STATE.json
Existing AGENTS.md content is preserved. CodexPigeon replaces only the managed
block between:
<!-- CODEXPIGEON_MAILBOX_START -->
<!-- CODEXPIGEON_MAILBOX_END -->Existing .codex/hooks.json files are parsed and merged. Non-CodexPigeon hook
groups are preserved.
Agent-owned files are not written by the app/CLI:
.codex-mailbox/OUTBOX.md
.codex-mailbox/RECEIPTS.md
The installed hook creates those agent-owned files when Codex runs in the trusted workspace, and snapshots treat missing agent-owned files as empty.
Each thread/worktree should have its own mailbox:
1 thread = 1 worktree = 1 .codex-mailbox/
Ownership is strict:
| File | Owner |
|---|---|
INBOX.md |
App/CLI writes only |
OUTBOX.md |
Codex agent writes only |
RECEIPTS.md |
Codex agent writes only |
STATE.json |
App-owned technical state |
HOOK_STATE.json |
Hook-owned throttle/runtime state |
See Mailbox Protocol for message examples and status derivation.
CodexPigeon permits only these App Server methods:
initializethread/listthread/readthread/loaded/listhooks/list
The client rejects active-turn methods such as turn/steer, turn/start,
thread/inject_items, and turn/interrupt.
Mailbox content is treated as prompt-like human guidance, not executable shell content.
| Document | Purpose |
|---|---|
| Architecture | Package boundaries and data flow |
| Setup | Local setup and development runtime |
| Mailbox Protocol | Markdown file format and ownership rules |
| Security Model | Trust boundaries and review checklist |
| Development Guide | Package workflow and checks |
| Troubleshooting | Common local issues |
| Screenshots and Assets | Sanitized asset capture rules |
| Publishing Checklist | GitHub release preparation |
| Release Checklist | Build, smoke test, and handoff steps |
| Platform Roadmap | Packaging and platform plans |
| Design References | UI reference policy |
CodexPigeon is usable today for local macOS and Linux development. The next packaging milestones are signed macOS builds, Linux desktop packages, and a Windows packaging path after the mailbox protocol has more real-world mileage.