codex-sync

Sync your OpenAI Codex CLI sessions to OpenSync dashboard. Track coding sessions, analyze tool usage, and monitor token consumption across projects.

GitHub: github.com/waynesutton/codex-sync-plugin

npm: npmjs.com/package/codex-sync

OpenSync Ecosystem

| Project | Description | Links | | ---------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | OpenSync | Dashboards for AI coding sessions | Website / GitHub | | opencode-sync-plugin | Sync OpenCode sessions | GitHub / npm | | claude-code-sync | Sync Claude Code sessions | GitHub / npm | | droid-sync | Sync Factory Droid sessions (community built) | GitHub / npm | | codex-sync | Sync Codex CLI sessions | GitHub / npm | | cursor-opensync-plugin | Sync Cursor sessions | GitHub / npm |

Installation

npm install -g codex-sync

Upgrading

To upgrade to the latest version:

npm update -g codex-sync

Check your current version:

codex-sync --version

Quick Start

1. Get Your API Key

1. Log into your OpenSync dashboard
2. Go to Settings
3. Click Generate API Key
4. Copy the key (starts with osk_)

2. Configure the Plugin

codex-sync login

Enter when prompted:

• Convex URL: Your deployment URL (e.g., https://your-project.convex.cloud)
• API Key: Your API key from Settings (e.g., osk_abc123...)

3. Add to Codex CLI

codex-sync setup

This automatically adds the notify hook to ~/.codex/config.toml.

Manual setup (if needed):

Add this line to ~/.codex/config.toml:

notify = ["codex-sync", "hook", "agent-turn-complete"]

4. Verify Setup

codex-sync verify

You should see:

  OpenSync Setup Verification

Credentials: OK
   Convex URL: https://your-project.convex.cloud
   API Key: osk_****...****

Codex CLI Config: OK
   Config file: ~/.codex/config.toml
   Hook: codex-sync

Connection Test: OK
   Connected to OpenSync

Sessions Directory: OK
   Found 5 recent session(s)

Ready! Start Codex and sessions will sync automatically.

Sessions will now sync automatically when you use Codex CLI.

CLI Commands

| Command | Description | | ------------------------------ | ------------------------------------ | | codex-sync login | Configure Convex URL and API Key | | codex-sync setup | Add hooks to Codex CLI config | | codex-sync verify | Verify credentials and config | | codex-sync synctest | Test connectivity and sync a session | | codex-sync sync | Sync recent sessions | | codex-sync sync --all | Sync all sessions | | codex-sync sync --limit N | Sync last N sessions | | codex-sync status | Show connection status | | codex-sync config | Show current configuration | | codex-sync config --json | Show config as JSON | | codex-sync set <key> <value> | Update a config value | | codex-sync logout | Clear stored credentials | | codex-sync hook <event> | Handle Codex hook events (internal) | | codex-sync --version | Show version number | | codex-sync --help | Show help |

See full command reference for detailed usage.

How It Works

Codex CLI stores sessions as JSONL files in ~/.codex/sessions/. The plugin uses the notify hook to trigger sync when Codex finishes a turn, then parses the session file to extract:

• Session metadata (project path, model, timestamps)
• User prompts and assistant responses
• Tool calls and results
• Token usage (input, output, cached, reasoning)
• Estimated cost

The data is sent to your OpenSync backend via the sync API.

Configuration Options

| Option | Type | Default | Description | | --------------- | ------- | ------- | --------------------------- | | autoSync | boolean | true | Automatically sync sessions | | syncToolCalls | boolean | true | Include tool call details | | syncThinking | boolean | false | Include thinking traces | | debug | boolean | false | Enable debug logging |

Set options with:

codex-sync set syncToolCalls false
codex-sync set debug true

Environment Variables

You can also configure via environment variables:

export CODEX_SYNC_CONVEX_URL="https://your-project.convex.cloud"
export CODEX_SYNC_API_KEY="osk_your_api_key"
export CODEX_SYNC_AUTO_SYNC="true"
export CODEX_SYNC_TOOL_CALLS="true"
export CODEX_SYNC_THINKING="false"
export CODEX_SYNC_DEBUG="false"

What Gets Synced

| Data | Description | | ------------------- | ------------------------------------------------------- | | Session metadata | Project path, working directory, git branch, timestamps | | User prompts | Your messages to Codex | | Assistant responses | Codex's responses | | Tool calls | Shell commands, file operations, and their results | | Token usage | Input, output, cached, and reasoning token counts | | Model info | Which model was used (gpt-5-codex, etc.) | | Cost estimate | Estimated session cost based on token usage |

Privacy

• All data goes to YOUR Convex deployment login profile if you're using opensync.dev the cloud version.
• Run convex locally for the 100% sefl host
• Sensitive fields can be redacted
• Full file contents are not synced, only paths
• Thinking traces are off by default
• You control what gets synced via configuration

Troubleshooting

# Check status and connection
codex-sync status

# View current config
codex-sync config --json

# Enable debug mode
codex-sync set debug true

# Full reset
npm uninstall -g codex-sync
rm -rf ~/.config/codex-sync
npm install -g codex-sync
codex-sync login
codex-sync setup

Common Issues

Hook not triggering:

• Make sure Codex CLI is updated: npm update -g @openai/codex
• Verify hook is in config: cat ~/.codex/config.toml | grep notify
• Check debug logs: codex-sync set debug true

Connection errors:

• Verify Convex URL is correct (no trailing slash)
• Check API key starts with osk_
• Test connection: codex-sync synctest

Sessions not appearing in dashboard:

• Wait a few seconds for sync to complete
• Check sessions exist: ls ~/.codex/sessions/
• Manual sync: codex-sync sync --limit 5

Need Help?

• Report bugs: GitHub Issues
• OpenSync docs: opensync.dev/docs
• Codex CLI docs: developers.openai.com/codex

Requirements

• Node.js 18 or later
• OpenAI Codex CLI (npm install -g @openai/codex)
• A deployed OpenSync backend

Links

OpenSync

• OpenSync Dashboard
• OpenSync Repository

codex-sync (this package)

• GitHub Repository
• npm Package
• Issues and Support

Related Plugins

• claude-code-sync / npm
• opencode-sync-plugin / npm
• droid-sync / npm

License

MIT