comate

KO | EN

gitlite — search

#javascript #hacktoberfest #react #ai #golang #go #docker #cli #kubernetes #vue #security #pytorch #ios #open-source

(★ 12)

A fully local companion gallery for images generated by the Codex desktop app.

comate Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# CoMate

[中文说明](./README.zh-CN.md)

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.

![CoMate screenshot](https://raw.githubusercontent.com/mate-matt/comate/main/docs/images/comate-screenshot.png)

## 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:

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

You can override paths with environment variables:

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

## Install

```bash
npm install
```

## Run Locally Without the Desktop App

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

```bash
npm run start:local
```

Then open:

```text
http://127.0.0.1:4388
```

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

```bash
COMATE_WEB_PORT=4392 npm run start:local
```

## Development

Run the web UI and API in development mode:

```bash
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:

```bash
npm run desktop
```

Build unsigned macOS artifacts:

```bash
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

```bash
npm run start:local
```

## Test

```bash
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

comate

comate Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

comate

comate Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README