add-signal skill

Add Signal Channel

Adds Signal support via a native adapter that speaks JSON-RPC to a signal-cli daemon — no Chat SDK bridge, only Node.js builtins. NanoClaw links to Signal as a secondary device on your existing phone: no new number, no bot API. Your assistant sends and receives as the number on the phone that scans the link.

Apply

1. Install signal-cli

NanoClaw talks to Signal through signal-cli, which has no bot API of its own. Install it if it isn't on PATH yet — Homebrew on macOS, the native release binary on Linux (neither needs Java). If it's already installed this is a no-op:

command -v signal-cli >/dev/null 2>&1 || bash setup/install-signal-cli.sh

2. Copy the adapter and its registration test

Fetch the channels branch and copy the Signal adapter and its registration test into src/channels/ (overwrite — the branch is canonical):

src/channels/signal.ts
src/channels/signal-registration.test.ts

3. Register the adapter

Append the self-registration import to the channel barrel (skipped if the line is already present). This one line is the skill's only reach-in into core:

import './signal.js';

4. Install the QR-rendering dependency

The device-link step renders the linking URL as a terminal QR via qrcode. Pinned to exact versions — the supply-chain policy rejects ranges and latest:

qrcode@1.5.4
@types/qrcode@1.5.6

The adapter itself consumes only Node.js builtins, so there is no adapter package to install — qrcode is purely for rendering the link during setup.

5. Build and validate

Build first: it guards the adapter's typed core-API consumption. Then run the one integration test.

pnpm run build

pnpm exec vitest run src/channels/signal-registration.test.ts

signal-registration.test.ts imports the real channel barrel and asserts the registry contains signal. It goes red if the import './signal.js'; line is deleted or drifts, or if the barrel fails to evaluate — so the channel genuinely would not register. The adapter has no npm dependency to guard; its typed core-API consumption is covered by the build. End-to-end delivery against a real Signal account is verified manually once the service runs.

Link your Signal account

This is the whole credential step. signal-cli opens a device-link handshake, prints a sgnl://linkdevice… URL, and renders it as a scannable QR. You scan it once from the phone that already runs Signal; that phone's number becomes the account NanoClaw sends and receives as — no number is registered.

The device-link runs signal-cli, so it must be reachable first — on PATH, or at $SIGNALCLIPATH. If step 1's install didn't land, the link step has nothing to drive; confirm it's present before linking (re-run step 1 if this fails):

command -v signal-cli >/dev/null 2>&1 || [ -x "$SIGNAL_CLI_PATH" ]

Tell the user:

Link NanoClaw to your Signal account:
1. On the phone that runs Signal, open Signal → Settings → Linked Devices → Link New Device.
2. Scan the QR code shown below — or open the `sgnl://linkdevice…` link printed under it on that phone.
3. Wait for confirmation. The linking URL expires after ~3 minutes; re-run this step for a fresh one.

Run the device-link. It blocks until you scan, then reports the linked phone number back as the account — that number is both your owner handle and the conversation address the wiring step needs:

pnpm exec tsx setup/index.ts --step signal-auth

ownerhandle and platformid both come back as the bare phone number (e.g. +15551234567). Your assistant reaches you through Signal's Note to Self, so the owner conversation is addressed by your own number — not a per-contact UUID.

Persist the account

Store the linked number so the adapter binds the right account on start, then sync it into the container env:

SIGNAL_ACCOUNT={{platform_id}}

Restart

Restart the service so it loads the Signal adapter and binds the account you just linked, and wait for its CLI socket before wiring:

bash setup/lib/restart.sh

Wiring

DMs

After the service starts, send any message to the Signal number from your personal Signal app. The router auto-creates a messaging_groups row. Then:

pnpm exec tsx scripts/q.ts data/v2.db \
  "SELECT id, platform_id FROM messaging_groups WHERE channel_type='signal' ORDER BY created_at DESC LIMIT 5"

Pass the id to /init-first-agent or /manage-channels to wire it to an agent group.

Groups

Add the Signal number to a group from your phone, send any message, then wire the resulting row the same way. Each group gets its own session with the default shared mode (one session per agent + messaging group). Create the wiring with ncl — the host service must be running (ncl connects to it over a Unix socket):

# Engage mode/pattern default to the Signal adapter's declared channel defaults
ncl wirings create --messaging-group-id mg-GROUPID --agent-group-id ag-AGENTID

Grant user access

New Signal users (including the owner's Signal identity) are silently dropped with notmember until granted access. After the user's first message appears in messaginggroups (host service running):

ncl users create --id "signal:UUID" --kind signal --display-name "<name>"
ncl roles grant --user "signal:UUID" --role owner
ncl members add --user "signal:UUID" --group ag-AGENTID

Find the UUID from messaginggroups.platformid or the users table.

Next Steps

If you're in the middle of /setup, return to the setup flow now. Otherwise wire this channel with /init-first-agent (or /manage-channels).

Channel Info

• type: signal
• terminology: Signal has "chats" (1:1 DMs) and "groups." The owner reaches their own assistant through Note to Self.
• platform-id-format:
• Owner DM (Note to Self): the bare phone number + (e.g. +15551234567) — your own messages route back as inbound with isFromMe, addressed by your number.
• Third-party DM: signal:{UUID} — the sender's Signal ACI, not their phone number.
• Group: signal:{base64GroupId} — base64-encoded GroupV2 ID.
• how-to-find-id: The owner number comes back from the device-link step above. For third parties or groups, send a message to the bot, then query messaging_groups.
• supports-threads: no
• typical-use: Personal assistant via Signal DMs or small group chats
• default-isolation: One agent per Signal account. Multiple chats with the same operator can share an agent group; groups with other people should typically get their own agent group (the default shared session mode already gives each messaging group its own session).

Features

• Markdown formatting — bold, italic / italic, code , code fence , ~~strike~~, ||spoiler|| (converted to Signal's offset-based text styles).
• Quoted replies — replyTo* fields populated from Signal quotes.
• Typing indicators — DMs only (Signal doesn't support group typing).
• Note to Self — messages you send to your own account from another device route to the agent as inbound with isFromMe: true.
• Voice attachments — detected but not transcribed by default; the agent receives a [Voice Message] placeholder. Run /add-voice-transcription for local transcription.

Not supported yet: outbound file attachments (logged and dropped), edit/delete messages, reactions.

Alternatives

Register a dedicated number instead of linking

The device-link above joins Signal as a secondary device on an existing number. If you'd rather give the assistant its own number, register a dedicated SIM or VoIP number that NanoClaw owns entirely. This path takes a captcha, an SMS (or voice) verification, and an optional profile name.

VoIP numbers: Signal requires SMS verification before voice. Some VoIP providers are blocked even for voice calls. If registration fails with an auth error, try a different provider or a physical SIM.

Step 1: Solve the CAPTCHA