Skip to content
Adem Isler
Back to projects
Developer toolingOpen-source MVP

CodexPigeon

A repo-local mailbox that lets people guide long-running Codex work without interrupting the active conversation or injecting a new turn.

Role
Product design, protocol design, desktop app, and CLI development
Source
Public repository
Started
Last repository update
Core stack
  • Electron
  • React
  • TypeScript
  • Node.js
  • Codex App Server
Table of Contents

Overview

CodexPigeon is a non-interrupting mailbox companion for Codex worktrees. It gives a person a place to leave repo-local guidance while an agent is working, without steering the active turn, injecting chat messages, or calling mutating App Server methods.

The mailbox is ordinary Markdown stored with the worktree, making the protocol inspectable and independent from a proprietary conversation surface.

The problem

Long-running coding work creates a timing problem. A person may notice a new constraint or want to remind the agent about a release gate, but interrupting the current conversation can distort the active task or force an immediate context switch.

Guidance needs a durable delivery path and a safe checkpoint.

Protocol

Each worktree receives a .codex-mailbox directory with strict ownership rules:

  • INBOX.md is written by the desktop app or CLI;
  • OUTBOX.md and RECEIPTS.md are written by the Codex agent;
  • STATE.json belongs to the application;
  • hook runtime state remains separate.

The recommended invariant is one thread, one worktree, and one mailbox. Managed blocks are merged into existing project instructions instead of overwriting them.

Product surface

CodexPigeon includes:

  • an Electron desktop application for inbox, receipts, outbox, installation, and diagnostics;
  • a CLI for sending, watching, inspecting, and scheduling repeat messages;
  • project-local hooks and templates;
  • read-only App Server discovery;
  • mailbox parsing, serialization, and ownership validation.

The App Server client allows only initialization and read/status methods. Active-turn operations such as steering, starting, injection, and interruption are rejected by design.

My role

I defined the mailbox protocol and safety boundary, built the desktop and command-line products, implemented the installation and file-ownership rules, and prepared the public documentation and test coverage.

Current status

CodexPigeon is an open-source MVP for macOS and Linux development workflows. The next milestones are signed packages and broader platform packaging, without changing the underlying Markdown protocol.