{"id":2141,"date":"2026-10-03T18:00:00","date_gmt":"2026-10-03T16:00:00","guid":{"rendered":"https:\/\/www.pcjv.de\/?p=2141"},"modified":"2026-10-04T14:58:50","modified_gmt":"2026-10-04T12:58:50","slug":"go-signal","status":"publish","type":"post","link":"https:\/\/www.pcjv.de\/?p=2141","title":{"rendered":"go-signal: Signal on the command line, in pure Go"},"content":{"rendered":"\n\n

I wanted to send and read Signal messages from a script, and let an AI agent do the same, without running a Java runtime next to it. signal-cli<\/a> is the established tool, but it needs a JVM. So on 25 September I started go-signal<\/a>, a Signal client for the command line written in Go. It ships as a single static binary for Linux, macOS and Windows, and since the second release it contains no Rust or C either.<\/p>\n\n\n\n\n

\n
\"The<\/figure>\n<\/div>\n\n\n

What it looks like<\/h2>\n\n\n\n

go-signal runs as a linked device next to your phone, like Signal Desktop. You link it once by scanning a QR code; afterwards contacts and groups sync, and it can send and receive on its own:<\/p>\n\n\n\n

go-signal link --name laptop          # scan the QR code on your phone\ngo-signal send +491234567890 -m \"Hello from go-signal\"\ngo-signal send self -m \"Note to self\" --attach notes.pdf\ngo-signal receive --follow -o json    # one JSON document per event\ngo-signal groups create \"Weekend\" --member @alice.42<\/code><\/pre>\n\n\n\n
Besides text and attachments it handles replies, mentions, edits, reactions, remote deletes, read receipts, stickers, polls and pinned messages. It lists contacts and identities, with trust on first use: if someone’s safety number changes, sending to them stops until you run identities trust<\/code>. Over the last few days the group commands caught up with the phone app. You can create, rename and update groups and change avatars, admins, bans and invite links, and you can join, accept or cancel your own requests. The commands are noun\u2013verb (groups ban<\/code>, profile update<\/code>) with plain and JSON output and documented exit codes. Exit code 3, for example, means the phone has unlinked the device. It is deliberately not a drop-in replacement for signal-cli; I use signal-cli’s source as the reference for protocol behaviour, not for the interface.<\/p>\n\n\n\n
Signal for agents<\/h2>\n\n\n\n
The part I use most is go-signal mcp serve<\/code>. It makes the account available to AI agents such as Claude Code over the Model Context Protocol<\/a>. While the server runs, it receives into an inbox, so the agent can look up contacts and groups, list messages, wait for new ones and fetch attachments.<\/p>\n\n\n\n
# read-only: the agent can read but not send\nclaude mcp add signal -- go-signal mcp serve --read-only\n\n# may message one person and one group, attachments only from ~\/signal-out\nclaude mcp add signal -- go-signal mcp serve \\\n  --allow-recipient +491234567890 --allow-recipient group:<id> \\\n  --attach-dir ~\/signal-out<\/code><\/pre>\n\n\n\n
Giving an agent your messenger needs some care, so the defaults are strict. The tools that send reject every recipient unless you allow them with --allow-recipient<\/code> ('*'<\/code> allows everyone). --read-only<\/code> drops those tools completely, and --confirm<\/code> has the client ask before every send. The server also tells the agent that message content comes from other people and is data, not instructions. --on-message<\/code> starts a program when a message arrives in a chat you choose, and mcp doctor<\/code> checks the setup. For scripts that aren’t agents there is daemon serve<\/code>, a local HTTP JSON API with a server-sent event stream and a bearer token.<\/p>\n\n\n\n
The first night<\/h2>\n\n\n\n
go-signal did not have to implement the Signal protocol from scratch. The mautrix-signal<\/a> Matrix bridge contains signalmeow<\/code>, a Signal client library in Go. go-signal wraps it behind its own small facade, so changes upstream stay in one package and the tests can use an in-memory fake client. That made fast progress possible. The first commit was on Friday, 25 September, at 21:10. By 1:30 that night, linking, multiple accounts, sending, receiving, attachments, reactions and receipts worked. The next morning contacts, groups, identities and the first version of the MCP server followed.<\/p>\n\n\n\n
There was one catch. signalmeow does its cryptography through libsignalgo<\/code>, cgo bindings to Signal’s own libsignal<\/a>, which is written in Rust. Every build therefore needed a Rust toolchain, a C compiler and a static library pinned to exactly the version the bindings expect. Cross-compiling for six targets turns that into a chore. It also undoes the main advantage of a Go tool over a Java one.<\/p>\n\n\n\n
Going pure Go<\/h2>\n\n\n\n
Earlier this year, GoCodeAlone\/libsignal-go<\/a> appeared, a pure-Go reimplementation of the libsignal protocol core. It covers PQXDH sessions, the double ratchet with the post-quantum SPQR extension, sender keys and sealed sender, and it is checked byte for byte against the Rust implementation. A real client needs more than that, though. The groups run on zero-knowledge credentials (zkgroup), and contact discovery talks to an SGX enclave, which first has to prove what code it runs. In my fork<\/a> I added those parts over two days, about 35,000 lines:<\/p>\n\n\n\n