pi-opensync-plugin

A pi coding agent extension that syncs sessions to OpenSync dashboards.

Requirements

• pi >= 0.65.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 npm:pi-opensync-plugin

For project-local installation (auto-installs for teammates), use the -l flag when calling pi install:

pi install -l npm:pi-opensync-plugin

To try without installing, pass the -e flag to temporarily add it to your extensions for the duration of a session:

pi -e npm:pi-opensync-plugin

For any of the above commands, you can also use the repository URL in place of the NPM package to install:

pi install git:github.com/joshuadavidthomas/pi-opensync-plugin
# or the full URL
pi install https://github.com/joshuadavidthomas/pi-opensync-plugin

For manual installation, clone the repository to any place pi coding agent looks for extensions:

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

Configuration

Once installed, run /opensync:config in pi to interactively configure the extension. At a minimum, the Convex URL and API key from OpenSync is required -- both can be found on the settings page.

The config file is located at ~/.config/pi-opensync-plugin/config.json.

Available Options

Config File	Environment Variable	Description	Default	Required?
apiKey	PI_OPENSYNC_API_KEY	Your OpenSync API key (osk_...)		✅
autoSync	PI_OPENSYNC_AUTO_SYNC	Enable automatic syncing	true
convexUrl	PI_OPENSYNC_CONVEX_URL	OpenSync Convex deployment URL		✅
debug	PI_OPENSYNC_DEBUG	Enable debug logging	false
syncThinking	PI_OPENSYNC_THINKING	Include thinking content	false
syncToolCalls	PI_OPENSYNC_TOOL_CALLS	Sync tool calls	false

How It Works

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

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

Fork Handling

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

1. Creates a new OpenSync session with title prefix [Fork::parentId]
2. Batch-syncs all existing messages from the fork point
3. 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.