Signal Channel for NanoClaw

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 $SIGNAL_CLI_PATH. 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

owner_handle and platform_id 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 not_member until granted access. After the user's first message appears in messaging_groups (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 messaging_groups.platform_id 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 +<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