pi-opensync-plugin

pi-opensync-plugin

A pi extension that syncs sessions to OpenSync dashboards.

Requirements

• pi >= 0.50.0
• OpenSync account (hosted or self-hosted) and API key

Features

• Real-time sync: Sessions and messages sync as you work
• Fork support: Forked sessions create new OpenSync sessions with [Fork::parentId] prefix
• Configurable: Choose what to sync (tool calls, thinking content)
• Non-intrusive: Silent failures, optional debug logging

Installation

• Install as a pi package globally:

  pi install https://github.com/joshuadavidthomas/pi-opensync-plugin
  

• For project-local installation (auto-installs for teammates):

  pi install -l https://github.com/joshuadavidthomas/pi-opensync-plugin
  

• To try without installing:

  pi -e https://github.com/joshuadavidthomas/pi-opensync-plugin
  

• Or you can clone manually:

  git clone https://github.com/joshuadavidthomas/pi-opensync-plugin ~/.pi/agent/extensions/pi-opensync-plugin
  

Configuration

Run /opensync:config in pi to interactively configure the extension.

Two options are required: convexUrl (your OpenSync deployment URL) and apiKey (your OpenSync API key).

Manual Configuration

Create ~/.config/pi-opensync-plugin/config.json:

{
  "apiKey": "osk_your_api_key_here",
  "autoSync": true,
  "convexUrl": "https://your-opensync-deployment.convex.cloud",
  "debug": false,
  "syncThinking": false,
  "syncToolCalls": false
}

Environment Variables

Environment variables take precedence over config file:

Variable	Description
PI_OPENSYNC_API_KEY	Your OpenSync API key (osk_...)
PI_OPENSYNC_AUTO_SYNC	Enable automatic syncing (default: true)
PI_OPENSYNC_CONVEX_URL	OpenSync Convex deployment URL
PI_OPENSYNC_DEBUG	Enable debug logging (default: false)
PI_OPENSYNC_THINKING	Include thinking content (default: false)
PI_OPENSYNC_TOOL_CALLS	Sync tool calls (default: false)

How It Works

The extension listens to pi's lifecycle events and syncs data to OpenSync:

• Session Start: Creates a new session in OpenSync with project info
• User Input: Syncs each user message in real-time
• Assistant Response: Syncs assistant messages with token usage
• Session End: Finalizes the session with duration and totals

Fork Handling

When you fork a session in pi (/fork), the extension:

• Creates a new OpenSync session with title prefix [Fork::parentId]
• Batch-syncs all existing messages from the fork point
• Continues real-time syncing for new messages

This means forked sessions contain the complete conversation history, which is intentional for traceability.

Development

bun install            # Install dependencies
bun run test           # Run tests
bun run test:watch     # Run tests in watch mode
bun run typecheck      # Type check

License

pi-opensync-plugin is licensed under the MIT license. See the LICENSE file for more information.