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

``bash
npm install -g codex-sync
`

Upgrading

To upgrade to the latest version:

`bash
npm update -g codex-sync
`

Check your current version:

`bash
codex-sync --version
`

Quick Start

$3

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

$3

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

`bash
codex-sync setup
`

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

Manual setup (if needed):

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

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

$3

`bash
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 | Update a config value |
| codex-sync logout | Clear stored credentials |
| codex-sync hook | 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:

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

Environment Variables

You can also configure via environment variables:

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

`bash


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
`

$3

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

$3

- 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

$3

- OpenSync Dashboard
- OpenSync Repository

$3

- GitHub Repository
- npm Package
- Issues and Support

$3

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

License

MIT