Codex Messenger

Codex Messenger is a Windows and macOS desktop Electron app inspired by MSN Messenger 7. It wraps a local Codex session in a Messenger-style interface: every Codex agent, project, or recent thread appears as a contact or conversation window with XP-era visuals, MSN sounds, Wizz/Nudge, file and image sending, camera capture, voice clips, profile pictures, status messages, and an authentic local Tic Tac Toe activity.

Developed by Anis AYARI and Codex.

French is the default language in the app, with English, Spanish, and Japanese available from the login screen. The website opens in English; use its language selector to open the French version.

Important: Codex Messenger is only a local front-end client for codex app-server. It is not Codex itself, does not own your Codex conversations, and should not be treated as a backup or storage layer for Codex data. Use it at your own risk.

Interface Preview

Quick Install

Official downloads are available from codexmessenger.net. Click DOWNLOAD and choose the platform in the popup:

• macOS v0.0.4: open the GitHub release page and choose the .dmg.
• Windows v0.0.4: open the GitHub release page and choose the Windows installer .exe.

The website download popup points to the official GitHub release page instead of proxying installer files through the static site.

Option 1: Windows installer

1. Open the Releases page.
2. Download Codex-Messenger-Setup-0.0.4.exe, or use the Windows button on codexmessenger.net.
3. Run the installer.
4. On first launch, confirm that Codex is detected or manually select the path to codex, codex.cmd, or codex.exe.

If Windows SmartScreen shows a warning, that is expected for an unsigned app. Continue only if the file comes from the official GitHub release.

If Codex Messenger is already installed, use the launcher or the Windows app entry to check for updates or uninstall the front client. Uninstalling Codex Messenger must not be used to delete Codex conversations, project files, or Codex CLI data.

Option 2: macOS app

1. Open the Releases page.
2. Download the macOS .dmg for your Mac architecture, or use the macOS button on codexmessenger.net.
3. Open Codex Messenger.app.
4. On first launch, confirm that Codex is detected or manually select the path to codex.

The macOS build is unsigned. After copying the app to Applications and trying to open it, macOS may block the first launch. Open System Settings → Privacy & Security → Open Anyway, then confirm Open for this app from the official GitHub release. See Apple's first-launch instructions.

Option 3: portable Windows build

Download Codex-Messenger-0.0.4.exe from the releases page and run it directly. No installer is required.

Option 4: from source

Requirements:

• Node.js 22.12 or newer (required by the locked Electron 41.10.7 and Electron rebuild toolchain).
• npm.
• Codex CLI installed locally.

git clone https://github.com/anisayari/codex-messenger.git
cd codex-messenger
npm install
npm run check:codex
npm run electron:start

Useful Scripts

# Verify that Codex CLI can be detected
npm run check:codex

# Install/check Codex CLI and start OpenAI login if needed
npm run setup:codex

# Check Codex CLI, npm, and login state without changing the machine
npm run setup:codex:check

# Run the Node test suite
npm test

# Run npm security audit for production and development dependencies
npm run audit:security

# Run release metadata checks
npm run test:release

# Build the Vite renderer
npm run build

# Run tests, release checks, renderer build, and Electron smoke test
npm run ci

# Start the Electron app
npm run electron:start

# Start Electron in development mode with Vite
npm run electron:dev

# Electron smoke test
npm run electron:smoke

# Build Windows installer and portable executable
npm run package:win

# Build unsigned macOS DMG and ZIP for the current architecture
npm run package:mac

# Build unsigned macOS DMG and ZIP for both x64 and arm64
npm run package:mac:all

# Build signed/notarized macOS DMG and ZIP for release
npm run package:mac:release

# Build an unpacked macOS .app for local testing
npm run package:mac:dir

# Distribution aliases
npm run dist:win
npm run dist:mac
npm run dist:mac:release

Launchers are organized by platform:

.\launchers\windows\launch-codex-messenger.ps1
.\launchers\windows\launch-web-preview.ps1

./launchers/macos/launch-codex-messenger.command
./launchers/macos/launch-web-preview.command

The root PowerShell files launch-codex-messenger.ps1 and launch-web-preview.ps1 are compatibility wrappers around the Windows launchers.

The Windows launcher opens a small control panel. It can launch Codex Messenger, check the latest GitHub version, open the update page, or uninstall only the Codex Messenger front client. It leaves Codex conversations and project data untouched.

The app launchers open an installed or packaged app directly; its login screen handles Codex detection and configuration. Source mode finds a supported Node runtime, installs local project dependencies when needed, and starts Electron with a visible console. The macOS launcher selects the bundle matching the Mac architecture, including when invoked through Rosetta. The web preview launchers reserve port 5174 and open the browser after Vite starts; they report a busy port and close their server when stopped. The full application requires Electron for Codex integration, filesystem access and native windows.

Updates

Codex Messenger checks for updates on startup:

• Codex Messenger front: compares the local app version with the latest stable GitHub release.
• Codex app-server: checks the local codex --version output and compares it with the public @openai/codex npm package.

When an update is available, an Update button appears at the top of the main window. You can also open File -> About Codex Messenger... or File -> Check for updates to see the current version and run a manual check.

The Codex Messenger front update button downloads the latest stable GitHub release asset for the exact platform and architecture and verifies its SHA-256 digest. On Windows, automatic installation requires valid installed-app and installer signatures from the same publisher. Unsigned releases such as v0.0.4 reveal the verified installer in Explorer for manual installation, with a clear message and a responsive interface. On macOS, automatic replacement requires a validated app signed by the same team, Gatekeeper acceptance and a rollback backup; unsigned builds open the verified DMG for manual installation. Concurrent requests schedule a single installation. The Codex app-server update button runs npm install -g @openai/codex@latest.

Uninstall

Use Windows Apps settings, the original installer entry, or:

.\launchers\windows\launch-codex-messenger.ps1

Then click Uninstall.

The uninstaller is intended to remove only the Codex Messenger front client, shortcuts, and application files. It should not remove:

• Codex conversations.
• Codex CLI configuration or caches.
• Your project folders.
• Files outside the Codex Messenger install directory.

The Windows installer refuses to remove an application directory containing unrelated files. Move those files somewhere safe before retrying; this guard also applies before upgrading an older installation.

Features

• Windows XP / MSN Messenger 7 inspired interface.
• One desktop window per Codex conversation.
• Connection to codex app-server from the Electron main process.
• No API keys exposed to the renderer.
• Codex response language selection: French by default, plus English, Spanish, and Japanese.
• Language definitions centralized in shared/languages.js so new languages can be added quickly.
• Codex contacts for the main agent, reviewer, designer, local projects, custom agents, and recent threads.
• Custom agents created from Add a Contact, with name, group, status, icon, color, and dedicated instructions.
• Demo mode from the Help menu, with isolated showcase agents, a showcase project, and seeded demo threads that do not list real Codex conversations.
• Messenger-style grouped contact list.
• Generated avatars for agents, projects, and recent conversations.
• Conversation windows focused on the selected contact.
• Project threads displayed as MSN-style tabs above the transcript, with drag reorder and delete controls.
• Streaming responses identified by item, plus commands, diffs, web search, plans, tool results, reasoning summaries and subagent activity.
• Server-side conversation search, paginated occurrences, context compaction and confirmed removal of the last exchange with a real history refresh.
• Interactive questions, modern command/file/permission approvals and MCP typed forms/URL confirmations.
• Server-advertised models, efforts, service tiers, permission profiles and Plan/Default collaboration modes.
• Account/quotas, skills, apps/MCP connections, OAuth, goals and archive/restore in the retro Codex properties dialog.
• Real command/exec terminal with streaming, input, resize and stop under the conversation’s permissions.
• Rate-limit reset credits require explicit confirmation; retries reconcile the same attempt identifier.
• MSN sounds for new messages and Wizz/Nudge.
• Local MSN 7 sound pack: new message, new email, Wizz/Nudge, online presence, ring, phone, typing, and task complete.
• MSN Messenger 7.5.0322 assets extracted from the archived Microsoft installer: PNG, GIF, JPG, bitmaps, icons, UI resources, and integrity manifests.
• 79 original MSN emoticon icons extracted pixel for pixel; 69 shortcuts attested by Microsoft are available in the picker. Ten icons without an attested shortcut and the 42 earlier raw exports are preserved.
• Extracted MSN CAB packages: 15 official winks, 4 dynamic backgrounds, and preserved MSN Search resources under public/msn-assets/msn75/packages.
• Winks can be sent from the Activities panel; Codex can also trigger them with [wink:...] markers.
• Wizz when Codex finishes or when an unread message stays unattended for too long.
• Send files and images to Codex.
• Local camera snapshot before sending.
• Bounded local voice clip recording, with microphone cleanup and explicit errors.
• Real Codex V3 voice calls using the app-server websocket, PCM16 audio, transcripts, mute and hang-up; availability depends on the account/server.
• Profile picture, status, and personal message.
• Local two-player Tic Tac Toe activity; no simulated game opponent presented as Codex.
• Fifteen original Flash winks rendered by local Ruffle 0.6.0, with their embedded audio, a close control and static previews for reduced motion. Original fixed backgrounds and four decoded dynamic-background posters; MSN-specific background callbacks are not emulated.
• Windows packaging with NSIS installer and portable executable.

Modernisation audit

Release v0.0.4 targets Codex CLI 0.156.1. The public app-server API includes the 0.156.0 features and the 0.156.1 model catalogue hotfix. The CLI remains a separate local installation; update it from the login screen when needed.

• Plan and confirmed defects
• All 51 stable changelogs, sources and integrity
• API migration and feature coverage
• Backend audit and MSN UI audit
• Authentic asset inventory
• Validation evidence

Configured Codex MCP/apps/plugins remain enabled by default. For an explicitly isolated test only, set CODEX_MESSENGER_DISABLE_CODEX_CONNECTORS=1. No model or reasoning effort is pinned in project configuration.

Codex Detection

Codex Messenger needs:

• Node.js/npm when Codex CLI must be installed automatically.
• Codex CLI 0.156.1 or newer, installed as @openai/codex.
• A completed OpenAI login through codex login.

From source, run:

npm run setup:codex

For a read-only readiness check:

npm run setup:codex:check

The app login screen also checks these prerequisites. If npm is missing, it opens the Node.js download page. If Codex CLI is missing or older than 0.156.1, it can run npm install -g @openai/codex. If OpenAI login is missing, it opens a terminal for codex login.

Codex Messenger looks for Codex in this order:

1. The path entered on the login screen.
2. The CODEX_MESSENGER_CODEX_PATH environment variable.
3. A supported Codex on the system PATH, using where codex on Windows or which codex on macOS/Linux.
4. Common installation locations and installed NVM versions when the inherited app PATH points to an older bundled CLI. The official npm package’s native executable is used when Node is absent from that PATH.

On Windows, if npm returns an extensionless shim such as C:\Users\you\AppData\Roaming\npm\codex, the app automatically checks codex.cmd, codex.exe, and codex.bat.

Manual PowerShell fallback:

$env:CODEX_MESSENGER_CODEX_PATH="C:\Users\you\AppData\Roaming\npm\codex.cmd"
npm run electron:start

Manual macOS/Linux fallback:

export CODEX_MESSENGER_CODEX_PATH="$(which codex)"
npm run electron:start

If detection fails inside the app:

1. Click Browse.
2. Select codex, codex.cmd, codex.exe, or an equivalent binary.
3. Click Test.
4. Connect again.

Configuration

Useful environment variables:

# Manual path to Codex CLI
$env:CODEX_MESSENGER_CODEX_PATH="C:\path\to\codex.cmd"

# Optional default profile email for first launch
$env:CODEX_MESSENGER_DEFAULT_EMAIL="you@example.com"

# Default working directory for Codex
$env:CODEX_MESSENGER_WORKSPACE="C:\Users\you\Desktop\projects"

# Root scanned for local projects
$env:CODEX_MESSENGER_PROJECTS_ROOT="C:\Users\you\Desktop\projects"

# Delay before unread Wizz reminder, in milliseconds
$env:MSN_UNREAD_WIZZ_MS="300000"

macOS/Linux:

# Manual path to Codex CLI
export CODEX_MESSENGER_CODEX_PATH="/opt/homebrew/bin/codex"

# Optional default profile email for first launch
export CODEX_MESSENGER_DEFAULT_EMAIL="you@example.com"

# Default working directory for Codex
export CODEX_MESSENGER_WORKSPACE="$HOME/Desktop/projects"

# Root scanned for local projects
export CODEX_MESSENGER_PROJECTS_ROOT="$HOME/Desktop/projects"

# Delay before unread Wizz reminder, in milliseconds
export MSN_UNREAD_WIZZ_MS="300000"

Local Data

In development, temporary uploads are stored inside the project folder.

In packaged builds, settings, uploads, and profile pictures are stored in Electron's user data directory. This avoids writing inside app.asar.

Codex conversations remain managed by Codex and your local Codex setup. Codex Messenger reads and sends messages through codex app-server; it is not the source of truth for conversation storage.

Packaging

npm install
npm run package:win

Generated Windows files are written to release/windows/:

• Codex-Messenger-Setup-0.0.4.exe: Windows installer.
• Codex-Messenger-0.0.4.exe: portable build.
• win-unpacked/: unpacked folder for local testing.

Builds and GitHub downloads use the same canonical filenames. The published SHA256SUMS and artifact manifests refer to those exact names.

The build is not signed. For broad public distribution, add Windows code signing.

macOS unsigned local build:

npm install
npm run package:mac

Generated macOS files are written to release/macos/:

• Codex-Messenger-0.0.4-arm64.dmg or Codex-Messenger-0.0.4-x64.dmg.
• Codex-Messenger-0.0.4-arm64.zip or Codex-Messenger-0.0.4-x64.zip.
• mac-arm64/ or mac/: unpacked app folder for local testing.

The unsigned macOS build includes camera and microphone usage descriptions for the snapshot and voice clip features, but it is not notarized or Developer ID signed.

macOS signed/notarized release build:

npm install
npm run package:mac:release

Release prerequisites:

• A Developer ID Application certificate for team T99D3SZXLB installed in the login keychain.
• Notarization credentials provided through one of these supported methods:
  • APPLE_API_KEY, APPLE_API_KEY_ID, and APPLE_API_ISSUER.
  • APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, and APPLE_TEAM_ID=T99D3SZXLB.
  • APPLE_KEYCHAIN_PROFILE=codex-messenger, optionally with APPLE_KEYCHAIN.

One-time notary profile setup:

xcrun notarytool store-credentials codex-messenger --apple-id "<apple-id>" --team-id T99D3SZXLB

For public distribution outside the Mac App Store, use package:mac:release, not the unsigned local build.

Static Website Deployment

The static showcase site lives in codexmessenger.net/.

Its DOWNLOAD button opens a platform chooser popup with:

• macOS v0.0.4: GitHub Releases.
• Windows v0.0.4: GitHub Releases.

The deploy workflow is .github/workflows/deploy-codexmessenger-net.yml. It reads the latest GitHub release, patches the GitHub release URL in codexmessenger.net/index.html, and uploads the static files to the VPS. The VPS no longer stores installer copies under /downloads/.

Before publishing the website, verify the GitHub release page contains both platform artifacts:

• Windows: a .exe asset, preferably a *Setup*.exe.
• macOS: a .dmg asset, preferably the arm64 build.

See codexmessenger.net/README-deploy.md for the VPS/nginx details.

Integrity Checks

Before publishing or making release changes:

npm run check:codex
npm test
npm run audit:security
npm run test:release
npm run build
npm run electron:smoke

For the same checks in one command:

npm run ci

To verify a generated executable:

& ".\release\windows\win-unpacked\Codex Messenger.exe" --smoke-test

Windows smoke tests may print Electron logs such as Gpu Cache Creation failed. The smoke test is considered successful when the command exits with code 0.

Troubleshooting

codex is not detected

Run npm run setup:codex, set CODEX_MESSENGER_CODEX_PATH, or select the binary from the login screen.

OpenAI login is missing

Run:

codex login

or click Login OpenAI on the Codex Messenger login screen, then click Test.

Double-clicking index.html

index.html is a Vite entry point and should not be opened directly through file://. Use:

npm run dev

or:

npm run electron:start

SmartScreen blocks the installer

The app is unsigned. Verify that the executable comes from the official GitHub release, then choose More info and Run anyway.

unknown variant workspace-write

This means an old Codex Messenger build sent a turn sandbox policy as workspace-write. Current codex app-server expects workspaceWrite, readOnly, externalSandbox, or dangerFullAccess for turn/start. Update Codex Messenger to a build that sends app-server policy variants correctly; existing saved settings using CLI-style values are still accepted and converted at runtime.

Service and Liability Notice

Codex Messenger is an experimental open-source front client for local Codex usage. It is provided "as is", without warranty of any kind.

By installing or using it, you understand that you are responsible for your own machine, projects, Codex configuration, credentials, generated output, and data backups. The project, its contributors, Anis AYARI, and Codex cannot be held responsible for damages, data loss, project corruption, security issues, downtime, costs, or any other consequence arising from installation, update, uninstall, or use of the software.

This project is not affiliated with Microsoft, MSN, Windows Live Messenger, or OpenAI. Names and visual references are used only to describe the intended retro interface style and Codex client behavior.

License

MIT. See LICENSE.

Profil isolé pour les tests desktop

La variable CODEX_MESSENGER_USER_DATA_DIR accepte un dossier absolu réservé aux tests. Electron y écrit ses paramètres, cache, captures et journaux sans modifier le profil habituel. Pour un smoke test, utilisez par exemple CODEX_MESSENGER_USER_DATA_DIR="$(mktemp -d /tmp/codex-messenger-smoke.XXXXXX)" npm run electron:smoke. Supprimez ce dossier temporaire après le test. Cette variable ne remplace pas le compte Codex : les tests de protocole isolés utilisent leur propre processus enfant sans compte.