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

npm install -g claude-code-sync

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

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. Add to Claude Code

Option A: Use the setup command (recommended)

claude-code-sync setup

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

Option B: One-liner (copy and paste)

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

4. Verify Setup

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:

# 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:

# 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 <key> <value> | Update a config value | | claude-code-sync hook <event> | 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 |

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 |

Set options with:

claude-code-sync set syncThinking true

Environment Variables

You can also configure via environment variables:

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

# 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

Need Help?

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

OpenSync

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

claude-code-sync (this package)

• GitHub Repository
• npm Package
• Issues and Support

opencode-sync-plugin

• GitHub Repository
• npm Package

License

MIT