A Go library and CLI that lets your program act as a linked Signal
secondary device. Cryptography flows through Signal's official Rust
libsignal via a thin cgo binding; protocol plumbing
(websockets, REST, prekey lifecycle, sealed sender, groups v2) is
implemented in Go.
From source (Linux, macOS, or Windows/MSYS2):
git clone https://github.com/thehappydinoa/signal-go
cd signal-go
task setup # once per clone: tools + git hooks
task libsignal # once: build or download libsignal_ffi.a
task build # → bin/signal-go
./bin/signal-go link -store ./.signal-dataPre-built binaries — GitHub Releases.
As a library — import "github.com/thehappydinoa/signal-go/pkg/signal".
You still need libsignal_ffi.a; see the getting-started guide.
Full walkthrough: docs/guides/getting-started.md.
flowchart TB
classDef pub fill:#d6f5d6,stroke:#3a7d3a,color:#000
classDef proto fill:#dde7ff,stroke:#3a5fb8,color:#000
classDef crypto fill:#ffe7c2,stroke:#a3661a,color:#000
classDef store fill:#f5d6e8,stroke:#a13a78,color:#000
pub[pkg/signal<br/><i>public API</i>]:::pub
bot[pkg/bot<br/><i>OnText / OnRegex / OnCommand</i>]:::pub
proto["Protocol layer<br/>(provisioning · web · ws · prekeys · chat)"]:::proto
crypto[internal/libsignal<br/><i>cgo + libsignal_ffi.a</i>]:::crypto
store["Persistence<br/>(account · store · sqlstore · seal)"]:::store
bot --> pub
pub --> proto
pub --> store
proto --> crypto
crypto --> store
Full breakdown: docs/diagrams/architecture.md.
| Topic | Link |
|---|---|
| Build, link, Windows setup | docs/guides/getting-started.md |
| Creating a Signal bot | docs/guides/creating-a-bot.md |
| Cutting a release | docs/guides/releasing.md |
| Testing strategy | docs/guides/testing.md |
| Bot examples | examples/ |
| Architecture diagrams | docs/diagrams/ |
| Security + threat model | docs/security.md |
| Architecture decisions | docs/adr/ |
| Changelog | CHANGELOG.md |
| Roadmap | ROADMAP.md |
Read CONTRIBUTING.md and CLAUDE.md, then run
task setup && task libsignal && task test && task lint before opening a PR.
Security issues: SECURITY.md — do not file public GitHub issues for vulnerabilities.
AGPL-3.0-only. signal-go statically links AGPL-licensed libsignal;
network deployments must comply with AGPL §13. See ADR 0009.
Not affiliated with or endorsed by Signal Messenger LLC.
Upstream libsignal is "use outside of Signal is unsupported"; we pin to a fixed tag.