Skip to main content

​
Codex CLI Plugin

The codex-sync plugin syncs your OpenAI Codex CLI sessions to OpenSync. It reads the JSONL session logs that Codex produces and pushes them to your dashboard. Source identifier: codex-cli

​
Installation

Install globally with npm:
Or with yarn:
Verify the installation:

​
Setup

1

Generate an API key

Log in to opensync.dev, go to Settings, and click Generate API Key. Copy the key (starts with osk_).
2

Run login

Enter your Convex URL and API key when prompted:
  • Convex URL: https://polished-penguin-622.convex.cloud (for hosted) or your self-hosted URL
  • API Key: The key you copied from Settings
3

Verify the connection

​
Config file

Credentials are stored in ~/.codex-sync/config.json:

​
Commands

​
codex-sync login

Stores your Convex URL and API key.

​
codex-sync status

Shows connection info and sync stats:

​
codex-sync sync

Manually triggers a sync of all sessions from ~/.codex/.

​
codex-sync logout

Clears stored credentials.

​
How syncing works

  1. Codex CLI writes JSONL session logs to ~/.codex/.
  2. The plugin parses these logs, extracting session metadata, messages, token counts, and model information.
  3. Each session is pushed to /sync/session with source: "codex-cli".
  4. Messages are pushed to /sync/message with role, content, and per-message token data.
  5. Deduplication is handled via externalId, so re-syncing is safe.

​
What gets synced

​
Supported models

All OpenAI models used through Codex CLI are supported: Cost calculations use these prices at the time of sync.

​
Troubleshooting

​
No sessions syncing

  1. Check that Codex CLI is installed and has been used: ls ~/.codex/
  2. Verify plugin status: codex-sync status
  3. Confirm your API key is valid in the dashboard Settings.
  4. Run codex-sync sync to force a manual push.

​
Token counts missing

Older versions of Codex CLI may not include token counts in their JSONL logs. Update Codex CLI to the latest version:

​
Permission errors

The plugin needs read access to ~/.codex/. Check permissions:

​
Updating

​
Uninstalling

Synced sessions remain in your dashboard after uninstalling.