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)	GitHub / npm
codex-sync	Sync Codex CLI 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