Coding tools · 05

Pi

Use the Pi extension event agent_settled to send a completion to bluebell after automatic retries, compaction, and queued continuation have all finished.

Current official lifecycle

Use agent_settled, not agent_end

agent_end marks the end of one underlying run. Pi may still retry, retry after compaction, or process queued messages. agent_settled waits until those automatic actions are no longer continuing, making it a better completion candidate.

Step 1

Create a bluebell extension

bluebell.ts
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { execFile } from "node:child_process";
import { basename } from "node:path";

const CLI = "/Applications/bluebellMac.app/Contents/Helpers/bluebellctl";

export default function (pi: ExtensionAPI) {
  pi.on("agent_settled", (_event, ctx) => {
    const sessionID = ctx.sessionManager.getSessionId();
    const leafID = ctx.sessionManager.getLeafId();
    if (!sessionID || !leafID) return;

    execFile(CLI, [
      "emit",
      "--source", "Pi",
      "--workspace-name", basename(ctx.cwd) || "Pi",
      "--session-id", sessionID,
      "--turn-id", leafID,
      "--dedupe-key", `pi:${sessionID}:${leafID}`,
      "--local",
    ], { timeout: 3000 }, () => {});
  });
}

Replace CLI Replace the path with the one copied from the app. The example uses Pi’s session UUID and current leaf entry ID as a stable identity without reading conversation contents. Failure of execFile will not block Pi either.

Step 2

Choose one installation location

Location Scope
~/.pi/agent/extensions/bluebell.ts All Pi projects for the current user.
.pi/extensions/bluebell.ts Only the current project, which must be trusted.
pi -e /absolute/path/bluebell.ts A single temporary test.

Do not install both global and project versions. After saving in an automatically discovered directory, use /reload to reload the extension.

Step 3

Test normal completion and automatic continuation

  1. Keep bluebell Mac running. Complete a short task without retries and confirm that only one local Pi event appears.
  2. Send a second prompt in the same session. Confirm that the leaf ID changes and a new event appears.
  3. Test a workflow involving automatic retry, compaction, or a queued follow-up. Confirm that it notifies only after the final settled event.
  4. Trigger the same session and leaf identity again. Confirm that bluebell returns duplicate instead of adding a notification.
  5. After verification, remove the extension’s --local and check Mac remote delivery and real devices.

Sources

Pi official references