Coding tools · Overview

Connect completion events to bluebell

bluebell provides a generic completion-event protocol, not a fixed list of supported tools. You select the completion signal for your tool’s current version; bluebell handles storage and notifications.

A common boundary

Adapters only translate events

  1. Read the tool callback
  2. →
  3. Select completion events
  4. →
  5. Create a stable ID
  6. →
  7. Invoke bluebellctl

An adapter does not access CloudKit, connect to Watch, or decide how a device vibrates. It only passes the tool’s completion event to bluebell.

Completion semantics

An event does not always mean the work is finished

Signal Can it be treated as completion?
Waiting for user approval No. The Agent may still continue.
A tool call ends No. This is usually just one step in a turn.
A subtask ends Usually not. The main task may still be running.
An interactive process exits Not as a general rule. A session may be closed manually or exit unexpectedly.
Vendor-defined turn complete / Stop / idle A candidate, but verify the current version and the behavior of child sessions, continuation, and retries.

Recommended order

Local first, then multiple devices

  1. Keep bluebell Mac running.

    Copy the current CLI path from the app.

  2. Run a bluebellctl --local test.

    Confirm that a recent notification appears, isolating local setup from CloudKit and device-notification issues.

  3. Inspect a real tool callback.

    Check fields, event counts, and differences between main and child sessions. Do not read or upload unnecessary conversation content.

  4. Connect the adapter and keep using --local.

    Complete a real task and confirm that it produces one logical completion.

  5. Once dedupeKey is stable, remove --local.

    Enable remote delivery on Mac, observe the queue, then verify on real devices.

Current examples

Find an adapter guide for your tool

01Claude Code Use a Stop hook and read callback JSON from stdin. →02Codex CLI Use the agent-turn-complete JSON argument passed to notify. →03 Codex app Configure a Stop hook for local tasks and read session and turn IDs. →04OpenCode Use a plugin event to handle session.idle and message IDs. →05Pi Use the extension’s agent_settled event to notify after automatic continuation ends. →

Older versions

Back up before migrating old Bluebell hooks

The new version does not automatically change or remove configuration written by older versions. Back up your files first. Remove only entries clearly belonging to old Bluebell helpers, plugins, or extensions; preserve other hooks on the same event.

Reconnect using the actual bluebellctl path shown in the app. A source name in history does not mean that the tool is still built in or installed.