claude-code-sync


Sync your Claude Code sessions to OpenSync dashboard. Track coding sessions, analyze tool usage, and monitor token consumption across projects.

GitHub: github.com/waynesutton/claude-code-sync

npm: npmjs.com/package/claude-code-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 claude-code-sync
`

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
claude-code-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...)

Where to find these values:

- Cloud (opensync.dev): Create an account at opensync.dev, go to Settings > API Access > Plugin Setup to find your Convex URL and create an API key
- Self-hosted: Use the same process on your own OpenSync deployment

$3

Option A: Use the setup command (recommended)

`bash
claude-code-sync setup
`

This automatically configures the hooks in ~/.claude/settings.json.

Option B: One-liner (copy and paste)

`bash
mkdir -p ~/.claude && cat > ~/.claude/settings.json << 'EOF'
{
"hooks": {
"SessionStart": [{ "hooks": [{ "type": "command", "command": "claude-code-sync hook SessionStart" }] }],
"SessionEnd": [{ "hooks": [{ "type": "command", "command": "claude-code-sync hook SessionEnd" }] }],
"UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "claude-code-sync hook UserPromptSubmit" }] }],
"PostToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "claude-code-sync hook PostToolUse" }] }],
"Stop": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "claude-code-sync hook Stop" }] }]
}
}
EOF
`

$3

`bash
claude-code-sync verify
`

You should see:

`
OpenSync Setup Verification

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

Claude Code Config: OK
Config file: ~/.claude/settings.json
Hooks registered: claude-code-sync

Ready! Start Claude Code and sessions will sync automatically.
`

Sessions will now sync automatically when you use Claude Code.

Upgrading

To upgrade to the latest version:

`bash


Close Claude Code first (important for hooks to reload)

Then upgrade the package

npm update -g claude-code-sync

Verify the new version

claude-code-sync --version

Check your configuration is still valid

claude-code-sync verify
`

If you encounter issues after upgrading:

`bash


Re-run setup to ensure hooks are configured

claude-code-sync setup

Test connectivity

claude-code-sync synctest
`

CLI Commands

| Command | Description |
| ------------------------------------ | ------------------------------------------- |
| claude-code-sync login | Configure Convex URL and API Key |
| claude-code-sync setup | Add hooks to Claude Code settings |
| claude-code-sync verify | Verify credentials and Claude Code config |
| claude-code-sync synctest | Test connectivity and create a test session |
| claude-code-sync logout | Clear stored credentials |
| claude-code-sync status | Show connection status |
| claude-code-sync config | Show current configuration |
| claude-code-sync config --json | Show config as JSON |
| claude-code-sync set | Update a config value |
| claude-code-sync hook | Handle Claude Code hook events (internal) |
| claude-code-sync --version | Show version number |
| claude-code-sync --help | Show help |

See full command reference for detailed usage, troubleshooting, and examples.

Hook Events

The plugin captures these Claude Code events:

| Event | Description |
| ------------------ | ------------------------------------- |
| SessionStart | Fires when a coding session begins |
| SessionEnd | Fires when a session terminates |
| UserPromptSubmit | Fires when you submit a prompt |
| PostToolUse | Fires after each tool execution |
| Stop | Fires when Claude finishes responding |

$3

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

Set options with:

`bash
claude-code-sync set syncThinking true
`

Environment Variables

You can also configure via environment variables:

`bash
export CLAUDE_SYNC_CONVEX_URL="https://your-project.convex.cloud"
export CLAUDE_SYNC_API_KEY="osk_your_api_key"
export CLAUDE_SYNC_AUTO_SYNC="true"
export CLAUDE_SYNC_TOOL_CALLS="true"
export CLAUDE_SYNC_THINKING="false"
`

What Gets Synced

| Data | Description |
| ------------------- | ------------------------------------------------------- |
| Session metadata | Project path, working directory, git branch, timestamps |
| User prompts | Your messages to Claude |
| Assistant responses | Claude's responses |
| Tool calls | Which tools were used and their outcomes |
| Token usage | Input and output token counts |
| Model info | Which Claude model was used |
| Cost estimate | Estimated session cost |

Privacy

- All data goes to YOUR Convex deployment
- Sensitive fields are automatically 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

claude-code-sync status

View current config

claude-code-sync config --json

Full reset

npm uninstall -g claude-code-sync
rm -rf ~/.config/claude-code-sync
npm install -g claude-code-sync
claude-code-sync login
``

See troubleshooting guide for more solutions.
See docs

$3

If you run into issues or have questions:

- Report a bug or request a feature: GitHub Issues
- Check existing issues for solutions to common problems

Requirements

- Node.js 18 or later
- Claude Code CLI
- A deployed OpenSync backend

Links

$3

- OpenSync - Beautiful dashboards for OpenCode and Claude Code sessions
- OpenSync Repository

$3

- GitHub Repository
- npm Package
- Issues and Support

$3

- GitHub Repository
- npm Package

License

MIT