pi-toolkit

A focused extension pack for Pi that adds encrypted Bark notifications and compact image-paste placeholders.

Features

Bark notifications

• End-to-end encrypted delivery by default
• Automatic notification when a Pi task fully settles
• One-shot 30-second ringing for important tasks
• LLM-generated completion recaps with a local fallback
• Global credentials with project-level, non-secret preferences
• Official api.day.app and self-hosted Bark Server support
• Manual toolkit_notify tool for agent-initiated notifications
• Defense-in-depth secret redaction

Image paste placeholders

• Replaces clipboard image paths with readable [Image N] markers
• Sends the original images to vision-capable models
• Restores image associations from session history
• Cleans up unused temporary clipboard files
• Wraps existing custom editors instead of replacing them

pi-toolkit is independent of UniPi. It does not depend on @pi-unipi/*, register /unipi:* commands, or use ~/.unipi.

Requirements

• Node.js 22.19 or later
• @earendil-works/pi-coding-agent 0.84 or later

Installation

npm

pi install npm:@aerok/pi-toolkit

GitHub

pi install git:github.com/wayne1943x/pi-toolkit

Local checkout

git clone https://github.com/wayne1943x/pi-toolkit.git
cd pi-toolkit
npm install
pi install .

Restart Pi after installation, or run /reload in the current session.

Quick start

1. Run:

   /toolkit:bark-setup

2. Paste the test URL shown in the Bark app. The setup wizard extracts the device key.

3. Configure Bark app encryption with the values generated by the wizard:

   | Bark setting | Value | |---|---| | Algorithm | AES128 | | Mode | CBC | | Padding | pkcs7 | | Key | Generated 16-character value; press K to copy | | IV | Generated 16-character value; press I to copy |

4. Send the encrypted test notification.

5. Confirm activation only if the device displays the readable test sentence. Do not confirm if Bark displays Decryption Failed.

The wizard does not save or activate new encryption credentials until this device-side check succeeds.

Bark commands

| Command | Description | |---|---| | /toolkit:bark-setup | Configure the Bark server, device key, delivery defaults, and encryption | | /toolkit:bark-test | Send a test using the active encryption mode | | /toolkit:bark-toggle | Quickly enable, disable, toggle, or inspect Bark notifications | | /toolkit:bark-encryption-rotate | Generate and verify a new encryption Key and IV | | /toolkit:bark-urgent | Toggle continuous ringing for the next completed task only | | /toolkit:bark-notify-settings | Configure notification events, encryption mode, and recap behavior | | /toolkit:bark-recap-model | Select the model used to generate completion recaps |

All Bark commands use the toolkit:bark-* namespace so other pi-toolkit extensions can add their own command groups later.

Quick enable and disable

Toggle global Bark notifications with no arguments:

/toolkit:bark-toggle

Use an explicit action when the desired result must be unambiguous:

/toolkit:bark-toggle on
/toolkit:bark-toggle off
/toolkit:bark-toggle status

Add --project to target the current project's non-secret enabled override:

/toolkit:bark-toggle --project
/toolkit:bark-toggle --project on
/toolkit:bark-toggle --project off
/toolkit:bark-toggle --project status

Enabling is refused until the inherited Bark server, device key, and encryption credentials are valid. Disabling clears any armed urgent notification. Status reports global, project, and effective values without changing configuration.

Default completion notification

When agent_settled fires, pi-toolkit sends:

| Field | Default | |---|---| | Title | Pi · <session name>, or Pi Toolkit — Task Complete when unnamed | | Body | One-sentence LLM recap, with a local fallback | | Group | Pi | | Sound | anticipate | | Level | active | | Encryption | Enabled after encrypted setup is completed |

agent_settled runs after Pi has finished retries, continuations, and compaction, making it the most reliable standalone task-completion event.

Important tasks

Before submitting an important task, run:

/toolkit:bark-urgent

The footer displays:

☎ next task: 30s ring

The next agent_settled notification includes Bark call=1, which repeats the selected ringtone for approximately 30 seconds. The state is then cleared, even if delivery fails, so an unrelated later task cannot ring unexpectedly.

Run the command again before task completion to cancel it. Urgent state is session-only and does not register or override Pi's /fast command.

Encrypted delivery

pi-toolkit implements Bark's documented encryption format:

• AES-128
• CBC mode
• PKCS#7 padding
• 16-byte Key
• 16-byte fixed IV
• Base64-encoded ciphertext

The title, body, group, sound, icon, level, and call fields are included in the encrypted JSON payload. Delivery fields required by Bark are also sent outside the ciphertext when necessary for routing and processing.

Bark Server and Apple Push Notification service can observe delivery metadata such as the device key, ciphertext, interruption level, and whether continuous ringing was requested. They cannot read the encrypted title or body.

Use the following command to rotate both the Key and IV:

/toolkit:bark-encryption-rotate

The old configuration remains active until the new encrypted test is readable on the device and explicitly confirmed.

Plaintext mode

Encrypted delivery can be disabled globally from:

/toolkit:bark-notify-settings

Disabling encryption requires a second confirmation because Bark Server and Apple Push Notification service will be able to read notification content. Projects cannot override encryption mode or downgrade themselves to plaintext.

Automatic events

| Event | Default | Description | |---|---:|---| | agent_settled | On | The task is fully complete | | agent_end | Off | Every low-level agent response; may be noisy | | session_shutdown | Off | The Pi session is closing | | ask_user_prompt | Off | An ask-user extension is waiting for input | | permission_request | Off | A permission extension is waiting for approval |

Configure these events with /toolkit:bark-notify-settings.

LLM recap

Completion notifications use Pi's provider-neutral model adapter to summarize the final assistant response into one sentence.

• Enabled by default
• Uses the current session model by default
• A fixed model can be selected with /toolkit:bark-recap-model
• Input is limited to 2,000 characters
• Output is limited to 100 tokens
• Requests time out after 10 seconds
• Model, authentication, network, and empty-output failures fall back to a local sanitized summary

Sensitive values are redacted before text reaches the recap model. Model output is sanitized again before encryption and at the Bark transport boundary.

Agent notification tool

Agents can send an explicit Bark notification through the same global configuration:

toolkit_notify({
  title: "Build Complete",
  message: "All checks passed.",
  priority: "normal"
})

Priority mapping:

| Toolkit priority | Bark level | |---|---| | low | passive | | normal | active | | high | timeSensitive |

high deliberately does not map to critical, avoiding an unexpected bypass of silent or focus modes.

Configuration

Global configuration

~/.pi/agent/pi-toolkit/bark.json

This file contains the Bark server URL, device key, encryption Key and IV, defaults, and global event settings. It is written atomically with file mode 0600; its parent directory uses mode 0700.

Project configuration

<project>/.pi/pi-toolkit/bark.json

Project configuration may override non-secret preferences such as enabled state, group, sound, icon, level, events, and recap settings. It cannot contain or override the server URL, device key, encryption mode, encryption Key, or IV.

Image paste placeholders

Paste an image into the Pi TUI using Pi's standard shortcut:

• macOS and Linux: Ctrl+V
• Windows and WSL: Alt+V

Instead of showing a long temporary path, the editor displays:

[Image 1]
[Image 2]

The marker remains in the prompt so it can be referenced naturally, while the corresponding image is submitted as image content.

Additional behavior:

• Numbering restarts from [Image 1] after each successful submission.
• PNG, JPEG, WebP, and GIF are supported.
• Session restore and input history reconnect markers to their original images.
• Removing an unsubmitted marker cleans up its temporary file.
• Submission is blocked and editor text is restored if the active model does not support image input.
• Existing custom editor components remain composable.

Do not install a second copy at ~/.pi/agent/extensions/image-placeholders; duplicate installations would wrap the editor twice.

Security model

• Notification text is sanitized before recap, before encryption, and at the Bark transport boundary.
• Redaction covers common passwords, API keys, tokens, authorization headers, private keys, Bark URLs, cloud-token formats, the configured Bark device key, and the configured encryption Key and IV.
• Matching values are replaced with [REDACTED].
• Encryption credentials are displayed only in an interactive setup overlay and are not added to the Pi conversation.
• Copying a Key or IV places a secret on the system clipboard; overwrite it after configuring the Bark app.
• The Bark device key must still be sent to the configured Bark Server as a routing credential.
• Redaction is defense in depth, not a guarantee that arbitrary unlabeled secrets can always be recognized. Avoid including credentials in prompts and final responses.
• Pi extensions execute local code with the user's permissions. Review packages before installation.

Development

npm install
npm run check
npm pack --dry-run

The test suite covers configuration migration, encrypted payload compatibility, secret redaction, setup confirmation, one-shot urgent notifications, Bark API behavior, and image placeholder lifecycle handling.

License

MIT. See LICENSE and NOTICE.