@aalzubidy/pi-signal

Connect pi to Signal Messenger for two-way messaging. Send a Note-to-Self message from your phone → pi receives it, the LLM processes it, and pi replies back automatically.

Only Note-to-Self messages are processed. Messages from other senders are silently ignored for security.

Installation

Prerequisites: signal-cli in PATH, Java 25+, Signal app on your phone.

# 1. Clone the repo and run the setup wizard
git clone https://github.com/aalzubidy/pi-signal.git
cd pi-signal
bash scripts/setup.sh                  # guides you through Java check, device linking, systemd service

# 2. Set your phone number (setup.sh may have auto-configured this)
export PI_SIGNAL_ACCOUNT=+1234567890   # or add to ~/.bashrc

# 3. Install the pi package locally
pi install ./pi-signal

# 4. Ensure one instance of pi is the primary - DO NOT SET IT ON PROFILE LEVEL
# Then restart pi or run /reload
export PI_SIGNAL_PRIMARY=true && pi

Send a Note-to-Self from your phone. pi receives it (👀), processes it, and replies automatically (✅).

How It Works

Phone (Note-to-Self) → signal-cli daemon (SSE in-memory) → pi extension
    → 👀 reaction → LLM processes → auto-reply → ✅ reaction

The extension connects directly to the signal-cli daemon's SSE endpoint over HTTP — no log file on disk (messages are streamed in-memory).

Commands (/model, /abort, /clear, /stats, /ping, /help) are handled locally without LLM. Everything else is forwarded to the LLM.

Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | PI_SIGNAL_ACCOUNT | Yes | — | Your Signal number in E.164: +1234567890 | | PI_SIGNAL_PRIMARY | No | false | Set "true" on the ONE instance handling Signal messages | | PI_SIGNAL_DAEMON_URL | No | http://127.0.0.1:8080 | Daemon URL for JSON-RPC and SSE | | PI_SIGNAL_STATS | No | short | Stats mode: off, short, or full | | PI_SIGNAL_QUIET_DAEMON | No | false | Silence daemon stdout in journalctl |

Commands (from Signal)

| Command | Purpose | |---|---| | /model <name> | Switch model (fuzzy match) | | /abort | Stop current generation | | /clear | New session | | /stats [short\|full\|off] | Toggle usage stats | | /ping | Test connectivity | | /help | Show available commands |

TUI Commands (in pi)

/signal-setup, /signal-start, /signal-stop, /signal-status, /signal-model, /signal-abort, /signal-stats

Tools (LLM-accessible)

• signal_send — Send a Signal message to a phone number (E.164)
• signal_status — Check connection status and health

Multiple Instances

Set PI_SIGNAL_PRIMARY=true on one pi instance. Other instances ignore Signal messages.

Troubleshooting

sudo systemctl status signal-receive.service
sudo journalctl -u signal-receive -f
curl -s http://127.0.0.1:8080/api/v1/check
# /signal-status in pi

See skills/signal/SKILL.md for full troubleshooting.

Files

pi-signal/
├── package.json
├── README.md
├── LICENSE
├── extensions/
│   └── signal.ts                # Main extension
├── skills/
│   └── signal/SKILL.md          # Full setup & troubleshooting guide
└── scripts/
    ├── setup.sh                 # Interactive setup wizard
    ├── signal-receive-loop.sh   # Native daemon manager
    └── signal-receive.service   # systemd unit template

License

MPL-2.0 — see LICENSE.