CoMate

中文说明

CoMate is a fully local companion app for Codex Desktop. It indexes images generated by Codex, links them with local session metadata and prompts, and gives you a clean private gallery plus a capability map for understanding what Codex can do on your machine.

Highlights

• Browse Codex Desktop generated images in a polished local gallery.
• Search, filter by date or prompt state, and jump between generation sessions.
• Inspect prompts, image metadata, file paths, and source folders.
• Copy selected images directly to the macOS clipboard.
• Review local Codex capabilities across Skills, Plugins, MCP, Commands, Automations, and Issues.
• Runs locally with no login, analytics, telemetry, or cloud sync.

Why

Codex Desktop can generate useful images across many sessions. CoMate makes those local images easier to review, search, and open without uploading anything or depending on a cloud service.

Privacy

• Fully local.
• No login, API key, analytics, or telemetry.
• No network connection is required for your image library.
• Reads only local Codex Desktop data on your machine.
• Stores its own local SQLite index under ~/.comate by default.

Codex Desktop Data

CoMate is built for the Codex desktop app, not Codex CLI. By default it reads:

~/.codex/generated_images
~/.codex/session_index.jsonl
~/.codex/sessions

You can override paths with environment variables:

CODEX_HOME=/path/to/codex-data
COMATE_HOME=/path/to/comate-data
COMATE_DB=/path/to/comate.sqlite

Install

npm install

Run Locally Without the Desktop App

You can use CoMate directly from source without installing the Electron app:

npm run start:local

Then open:

http://127.0.0.1:4388

4388 is the default local web port. If that port is already in use, choose another one:

COMATE_WEB_PORT=4392 npm run start:local

Development

Run the web UI and API in development mode:

npm run dev

Default development URLs:

• Web UI: http://127.0.0.1:4388
• API: http://127.0.0.1:4389

Development mode uses Vite for the web UI and a separate API process. If the web port is occupied, Vite may print a different temporary URL; the production local command above keeps CoMate on a single COMATE_WEB_PORT.

Desktop App

Run the Electron desktop app:

npm run desktop

Build unsigned macOS artifacts:

npm run package:mac

Artifacts are written to release/.

Unsigned macOS builds are also produced by the Package macOS App GitHub Actions workflow. Pushes to main run CI, and v* tags can publish release artifacts.

Production Web Mode

npm run start:local

Test

npm test
npm run build

GitHub Actions

This repository includes:

• CI: runs tests and production builds on push and pull requests.
• Package macOS App: manually packages unsigned macOS .dmg and .zip artifacts, and publishes a GitHub Release for v* tags.

macOS Gatekeeper

Current public builds are unsigned. If macOS blocks launch, right-click the app and choose Open, or allow it from System Settings > Privacy & Security.

Signed and notarized releases require Apple Developer credentials and are not configured by default.

License

MIT