@openwaggle/pi-waggle

Pi-native Waggle package built on top of @openwaggle/waggle-core.

Full documentation · OpenWaggle · Issues

@openwaggle/pi-waggle is the Pi-native Waggle package.

Use it when you want Waggle mode inside a Pi runtime. It includes the reusable @openwaggle/waggle-core policy dependency, registers the default /waggle and /standard commands, renders Pi-native Waggle messages, and stores Waggle mode state with Pi custom messages.

Install

npm

npm install @openwaggle/pi-waggle @earendil-works/pi-coding-agent @earendil-works/pi-tui

pnpm

pnpm add @openwaggle/pi-waggle @earendil-works/pi-coding-agent @earendil-works/pi-tui

Yarn

yarn add @openwaggle/pi-waggle @earendil-works/pi-coding-agent @earendil-works/pi-tui

Bun

bun add @openwaggle/pi-waggle @earendil-works/pi-coding-agent @earendil-works/pi-tui

@earendil-works/pi-coding-agent and @earendil-works/pi-tui are peer dependencies. Install versions compatible with the range in the package manifest.

Pi users normally install @openwaggle/pi-waggle alone for Waggle mode. Install @openwaggle/waggle-core directly only when your code imports core helpers itself.

Pi Extension Entry

The ./extension subpath exposes the default Pi extension factory:

import piWaggle from '@openwaggle/pi-waggle/extension'

export default piWaggle

The package manifest also declares the built Pi extension entry so Pi package loading can discover it from the installed package.

Commands

The default extension registers:

| Command | Behavior | |---------|----------| | /waggle | Opens the default Waggle control flow or enables a preset. | | /waggle <preset-id> <prompt> | Enables the preset and starts from the provided prompt. | | /waggle off | Disables Waggle mode for the current branch. | | /standard | Disables Waggle mode for the current branch. |

Command parsing helpers are also exported:

import { parsePiWaggleCommandArgs } from '@openwaggle/pi-waggle/commands'

const intent = parsePiWaggleCommandArgs('code-review review this diff')

Runtime State And Messages

Pi Waggle uses Pi custom message types under the pi-waggle.* namespace:

import {
  PI_WAGGLE_MODE_STATE_CUSTOM_TYPE,
  PI_WAGGLE_TURN_CUSTOM_TYPE,
  PI_WAGGLE_USER_REQUEST_CUSTOM_TYPE,
  parsePiWaggleModeState,
  parsePiWaggleTurnDetails,
} from '@openwaggle/pi-waggle/protocol'

Use these helpers when projecting or rendering Pi Waggle state. Do not seed a parallel metadata tree outside Pi session data.

Custom Loop Integration

Advanced Pi integrations can use the loop helpers directly when they need custom metadata, message creation, or completion handling:

import { createPiWaggleExtension } from '@openwaggle/pi-waggle/loop'
import type { WaggleConfig } from '@openwaggle/waggle-core'

export function createCustomWaggle(config: WaggleConfig) {
  return createPiWaggleExtension({
    config,
    createTurnMetadata: ({ turnNumber, agentIndex }) => ({ turnNumber, agentIndex }),
    buildTurnMessage: ({ turn }) => ({
      customType: 'example.waggle-turn',
      content: `Turn ${String(turn.turnNumber + 1)}: ${turn.agent.label}`,
      display: false,
      details: { turnNumber: turn.turnNumber, agentLabel: turn.agent.label },
    }),
    onTurnComplete: () => ({ continue: true }),
  })
}

Most users should start with the default extension export. Reach for loop helpers only when you are embedding Waggle into a custom Pi package.

Boundary Rules

@openwaggle/pi-waggle is Pi-specific. It may import Pi SDK packages and @openwaggle/waggle-core, but it should not be used as an OpenWaggle renderer dependency or browser-only extension UI package.

For runtime-neutral policy, use @openwaggle/waggle-core. For OpenWaggle visual extensions, use @openwaggle/extension-sdk.

Compatibility

| Requirement | Supported line | |-------------|----------------| | Node.js | 22.19 and newer | | Pi coding agent | Compatible 0.80.x peer range from the package manifest | | Pi TUI | Compatible 0.80.x peer range from the package manifest | | Module format | ESM and CommonJS | | Pi Waggle documentation | 0.1 |

Reference And Support

• Complete API reference
• npm package
• Package changelog
• Report an issue

Troubleshooting

Pi does not discover the extension. Install the package in the Pi package environment and confirm the package manifest exposes ./dist/extension.js through its pi.extensions entry.

Commands render but state does not persist. Preserve the pi-waggle.* custom messages in Pi session data and avoid a parallel host-owned state tree.

Peer dependency warnings appear. Install Pi coding-agent and TUI versions compatible with the exact peer ranges in the package manifest.

There are no migrations within the 0.1 documentation line. Future incompatible changes will receive a new versioned documentation line and migration guide.

License

MIT