droid-sync

Sync your Factory Droid coding sessions to OpenSync in real-time.

Installation

npm install -g droid-sync

Setup

# Configure credentials and register hooks
droid-sync login

# Verify connection
droid-sync status

Core Architecture

Factory Droid  →  hooks (stdin JSON)  →  CLI parses  →  SyncClient  →  Convex Backend

Source Files

| File | Purpose | | ------------------- | ---------------------------------------------------------------------- | | src/cli.ts | CLI entry point: login, logout, status, verify, hook <event> | | src/hooks.ts | Event handlers (primary: Stop) | | src/api.ts | SyncClient class - HTTP requests to Convex backend | | src/config.ts | Configuration loading/saving | | src/transcript.ts | JSONL transcript parsing, incremental message extraction | | src/types.ts | TypeScript type definitions |

Event Flow

The plugin uses the Stop event for all syncing:

1. Stop → Creates/updates session with metadata (project, git branch, model, tokens, duration), parses transcript, syncs new messages
2. SessionEnd → Clears local sync state (synced message ID cache)

How Hooks Work

When Factory Droid triggers a hook, it:

1. Invokes droid-sync hook <EventName> as a subprocess
2. Pipes JSON context to stdin (sessionId, transcriptPath, cwd, etc.)
3. The CLI reads stdin, parses JSON, dispatches to the appropriate handler

Example hook registration in ~/.factory/settings.json:

{
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "command", "command": "droid-sync hook Stop" }] }
    ]
  }
}

Note: Only the Stop hook is required. SessionEnd only clears local cache.

Data Transformation

The plugin transforms Factory Droid's internal schema to the backend's expected format:

Plugin receives              →  Backend expects
───────────────────────────────────────────────────
sessionId                    →  externalId
messageId                    →  externalId
content                      →  textContent
tool_use blocks              →  parts[{ type: "tool_use", content: {...} }]
assistantActiveTimeMs        →  durationMs
tokenUsage.inputTokens       →  tokenUsage.input
tokenUsage.outputTokens      →  tokenUsage.output

This mapping happens in transformSession() and transformMessage() methods in src/api.ts.

Incremental Sync

Messages are synced incrementally to avoid duplicates:

1. On each Stop event, parse the transcript JSONL file
2. Load previously synced message IDs from state file
3. Extract only new messages not in the synced set
4. Sync new messages via batch API
5. Save updated message IDs to state file

State files: ~/.config/droid-sync/state/{sessionId}.json

Config Storage

| Location | Purpose | | ---------------------------------- | ------------------------------------------------ | | ~/.config/droid-sync/config.json | Primary config (convexUrl, apiKey, sync options) | | ~/.factory/settings.json | Hook registrations | | ~/.config/droid-sync/state/ | Per-session sync state (synced message IDs) | | Environment variables | Override config (DROID_SYNC_*) |

Commands

droid-sync login     # Configure credentials and register hooks
droid-sync logout    # Clear credentials
droid-sync status    # Show connection status
droid-sync verify    # Test connectivity
droid-sync config    # Show configuration
droid-sync version   # Show version

Configuration

Config file: ~/.config/droid-sync/config.json

{
  "convexUrl": "https://your-project.convex.cloud",
  "apiKey": "osk_your_api_key",
  "autoSync": true,
  "syncToolCalls": true,
  "syncThinking": false
}

License

MIT