If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/tulir/whatsmeow shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Single-maintainer risk — review before adopting

• Last commit 1d ago
• 8 active contributors
• MPL-2.0 licensed
• CI configured
• ⚠ Single-maintainer risk — top contributor 91% of recent commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live tulir/whatsmeow repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/tulir/whatsmeow.

What it runs against: a local clone of tulir/whatsmeow — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in tulir/whatsmeow | Confirms the artifact applies here, not a fork | | 2 | License is still MPL-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of tulir/whatsmeow. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/tulir/whatsmeow.git
#   cd whatsmeow
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of tulir/whatsmeow and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "tulir/whatsmeow(\\.git)?\\b" \\
  && ok "origin remote is tulir/whatsmeow" \\
  || miss "origin remote is not tulir/whatsmeow (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MPL-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MPL-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is MPL-2.0" \\
  || miss "license drift — was MPL-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "client.go" \\
  && ok "client.go" \\
  || miss "missing critical file: client.go"
test -f "binary/decoder.go" \\
  && ok "binary/decoder.go" \\
  || miss "missing critical file: binary/decoder.go"
test -f "binary/encoder.go" \\
  && ok "binary/encoder.go" \\
  || miss "missing critical file: binary/encoder.go"
test -f "appstate/decode.go" \\
  && ok "appstate/decode.go" \\
  || miss "missing critical file: appstate/decode.go"
test -f "handshake.go" \\
  && ok "handshake.go" \\
  || miss "missing critical file: handshake.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/tulir/whatsmeow"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

whatsmeow is a Go library that implements the WhatsApp Web multidevice protocol, enabling programmatic control of WhatsApp accounts for sending/receiving messages, managing groups, handling app state (contacts, mute status), and processing delivery/read receipts. It reverse-engineers WhatsApp's websocket API and handles Signal encryption, binary protocol decoding, and multidevice synchronization. Monolithic single-package library with protocol-specific subpackages: appstate/ handles contact/chat metadata encoding, binary/ provides websocket frame marshaling, argo/ wraps Argo wire format, while core client.go orchestrates the multidevice handshake and message routing. Signal encryption via go.mau.fi/libsignal, protobuf for message definitions in binary/proto/.

Go developers building WhatsApp bots, bridges, automation tools, or integration services who need to programmatically send/receive WhatsApp messages without using the official WhatsApp Business API. Common use cases: Matrix/Telegram bridges, notification systems, chatbot platforms.

Actively developed and production-capable. Single maintainer (tulir) with frequent commits, comprehensive protocol implementation (text/media messages, groups, app state, receipts), but calls feature explicitly unimplemented. Has CI via GitHub Actions (go.yml), no formal test suite visible, and hosts an active Matrix community for protocol Q&A. Verdict: production-ready for core messaging but treat as actively evolving reverse-engineering project.

Depends on reverse-engineered WhatsApp protocol which WhatsApp actively changes—breaking updates could occur without warning. Single maintainer dependency. Minimal visible test coverage (client_test.go only), making regressions possible. WhatsApp ToS violation risk for users. Dependencies are lean and trustworthy (libsignal, zerolog, protobuf) but protocol brittleness is the real risk.

No specific recent activity visible from file metadata, but repo actively answers protocol questions in GitHub Discussions. Implementation is feature-complete for main use cases (messages, groups, state sync); focus likely on compatibility maintenance as WhatsApp evolves protocol.

git clone https://github.com/tulir/whatsmeow.git
cd whatsmeow
go mod download
go test ./...

Daily commands: This is a library, not a runnable service. Import as go.mau.fi/whatsmeow and call client.NewClient() after QR login. See godoc package example or external projects like mautrix-whatsapp for full server examples.

• client.go — Main Client struct and core connection logic; entry point for all library usage and the foundation of the WhatsApp protocol implementation.
• binary/decoder.go — Binary protocol message parsing; decodes WhatsApp's proprietary binary format which is central to all incoming data.
• binary/encoder.go — Binary protocol message encoding; encodes outgoing messages in WhatsApp's format, critical for all client-to-server communication.
• appstate/decode.go — Application state decoding (contacts, chat settings, etc); handles persistent state synchronization with WhatsApp servers.
• handshake.go — WebSocket handshake and pairing logic; establishes initial authentication and session setup with WhatsApp infrastructure.
• message.go — Message struct definitions and send/receive abstractions; defines the primary data model for all messaging operations.
• connectionevents.go — Event handling and dispatching system; manages event callbacks that drive the entire async operation model.

Add a New Message Type

1. Define the Protocol Buffer schema for your message content in proto/instamadilloCoretype[YourType]/InstamadilloCoretype[YourType].proto (proto/instamadilloCoreTypeText/InstamadilloCoreTypeText.proto)
2. Generate the Go protobuf code (the .pb.go file will be auto-generated) (proto/instamadilloCoreTypeText/InstamadilloCoreTypeText.pb.go)
3. Add a new sending method on the Client struct in message.go that constructs the InstamadilloAddMessage payload with your content type (message.go)
4. Add unmarshaling logic in the message receive path (connectionevents.go or within client.go) to parse incoming messages of your new type (connectionevents.go)
5. Create a corresponding Go struct in message.go to represent the message in the library's public API (message.go)

Add a New Connection Event Type

1. Define a new event struct in connectionevents.go following the naming pattern of existing events (e.g., type MyNewEvent struct {...}) (connectionevents.go)
2. Add the event to the EventHandler interface in connectionevents.go as a new method signature (connectionevents.go)
3. Dispatch the event in the appropriate handler in client.go or internals.go using the client.emit() mechanism (client.go)
4. Implement the no-op default handler in client.go's DefaultClientHandler struct (client.go)

Add a New Client Method (Feature)

1. Add the public method to the Client struct in client.go or a dedicated feature file (e.g., group.go, call.go) (client.go)
2. Within the method, use client.sendFrame() to send binary protocol messages via internals.go (internals.go)
3. If the feature requires encrypted state, use appstate encoding (appstate/encode.go) and client.UpdateAppState() (appstate/encode.go)
4. Add corresponding event handling in connectionevents.go if the server sends responses or state changes (connectionevents.go)

Implement Custom Message Decryption

1. Add decryption logic in msgsecret.go using the Signal protocol via libsignal dependency (msgsecret.go)
2. Integrate the decrypted payload into message.go's message structs as decoded fields (message.go)
3. Handle decryption errors and key missing scenarios in the message receive handler in client.go (client.go)

• Go 1.25.0 — Lightweight, compiled language ideal for a protocol library; strong concurrency primitives for managing WebSocket connections and event handlers.
• Protocol Buffers (protobuf) — WhatsApp's core message format is protobuf-based; enables efficient serialization and version compatibility with the server API.
• libsignal (Signal protocol) — Provides end-to-end encryption (Double Ratchet) required for WhatsApp's E2EE messaging standard.
• WebSocket (coder/websocket) — WhatsApp web multidevice uses WebSocket for full-duplex real-time communication; chosen fork has low-latency, streaming-friendly behavior.
• zerolog — Structured logging with minimal allocation overhead, suited for a library that may be called in high-volume scenarios.

• Library-only approach (no built-in CLI, no database)

  • Why: Maximal flexibility; users can choose their own persistence layer, logging, and async runtime.
  • Consequence: Developers must implement their own state storage (client state, message log) and event handling infrastructure.

• undefined

  • Why: undefined
  • Consequence: undefined

Multidevice sync can cause account locks if device list desynchronizes—WhatsApp may reject messages until sync recovers. QR code login expires in ~30 seconds; polling timeout is critical. appstate LTHASH merkle tree computation is computationally expensive on first sync (large contact lists). Go version requirement is Go 1.25+ (check go.mod toolchain field). Some appstate mutations are write-only (no decoding path), causing state inconsistency if you manually edit the database.

• WhatsApp Multidevice Protocol — Core to understanding why whatsmeow requires handshake.go and appstate sync; WhatsApp's post-2021 architecture diverges sharply from single-device reverse engineering
• Signal Protocol (Double Ratchet) — whatsmeow delegates encryption to libsignal; understanding Signal is essential for debugging message decrypt failures or extending encryption features
• LTHASH (Merkle Tree Synchronization) — appstate/hash.go implements WhatsApp's custom merkle tree for conflict-free app state sync; critical for understanding how contact/chat lists stay consistent across devices
• Binary Protocol Framing (Argo Wire Format) — binary/encoder.go and argo/argo.go handle WhatsApp's custom binary serialization; needed to understand message parsing/generation without full protocol spec
• Protobuf (Protocol Buffers) — binary/proto/ defines WhatsApp message types; whatsmeow generates Go code from .proto files, making protobuf version mismatches a common issue
• WebSocket Multiplexing & Backpressure — client.go manages coder/websocket lifecycle with keepalive.go and mediaretry.go; understanding frame ordering and ack semantics prevents message loss
• End-to-End Encrypted State Storage — appstate/encode.go and appstate/keys.go encrypt app state mutations with device-specific keys before sending; critical for modifying contacts/mute status without protocol breakage

• tulir/mautrix-whatsapp — Reference implementation using whatsmeow as a Matrix bridge; demonstrates full server pattern for production deployment
• go-whatsapp/whatsapp — Older WhatsApp Go library for legacy protocol; shows alternative approach to reverse engineering (useful for understanding design tradeoffs)
• tulir/mautrix — Shared mautrix protocol client library that whatsmeow bridges integrate with; useful for understanding event/state synchronization patterns
• tulir/libsignal — Go bindings to Signal protocol library that whatsmeow depends on for end-to-end encryption

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for binary protocol encoding/decoding

The binary package (binary/encoder.go, binary/decoder.go, binary/node.go) handles critical WhatsApp protocol serialization but has no visible test files. Given this is a protocol library, encoding/decoding correctness is essential. This would improve reliability and catch regressions early, especially important since binary/proto contains auto-generated protobuf code that depends on these encoders.

• [ ] Create binary/encoder_test.go with tests for Node encoding edge cases (nested structures, different data types)
• [ ] Create binary/decoder_test.go with round-trip tests (encode then decode should yield original)
• [ ] Add tests for binary/attrs.go attribute serialization
• [ ] Test error cases in binary/errors.go to ensure proper error handling
• [ ] Consider fuzzing tests given protocol parsing sensitivity

Add integration tests for appstate recovery and sync workflows

The appstate package (appstate/recovery.go, appstate/hash.go, appstate/decode.go) manages critical application state synchronization and recovery, but client_test.go appears to be the only test file visible. The appstate recovery mechanism is complex and failure-prone. Adding dedicated integration tests would ensure state consistency across reconnections and device syncs, reducing user-facing bugs.

• [ ] Create appstate/recovery_test.go testing state recovery after connection loss
• [ ] Create appstate/sync_test.go testing appstate hash validation (appstate/hash.go)
• [ ] Add tests for appstate/decode.go covering different app state types
• [ ] Test state merge conflicts and ordering issues in appstate/encode.go
• [ ] Add test fixtures in a testdata directory for different appstate scenarios

Add CI workflow for Go 1.25+ compatibility and protobuf regeneration verification

The go.mod specifies go 1.25.0 with toolchain go1.26.2, but .github/workflows/go.yml likely doesn't verify protobuf code regeneration or test against the minimum supported Go version. The proto/ directory contains auto-generated .pb.go files that must stay in sync with .proto definitions. A CI check ensures contributors don't accidentally commit stale generated code, preventing subtle bugs.

• [ ] Enhance .github/workflows/go.yml to run 'go generate ./proto/...' and verify no git diff
• [ ] Add test matrix for go 1.25.0 (minimum version from go.mod) alongside latest Go
• [ ] Verify protoc version consistency (add protoc version check in workflow)
• [ ] Add step to validate proto/ directory hasn't diverged from source .proto files
• [ ] Document proto regeneration process in .github/CONTRIBUTING.md

• Add table-driven tests for binary/encoder.go and binary/decoder.go symmetry (test round-trip encoding of all node types); currently only client_test.go exists
• Implement call.go feature set (currently skeleton with TODO comments); document CallOffer/CallAccept protocol and add send/receive methods mirroring message handling in client.go
• Write integration tests in appstate/ for LTHASH collision detection and recovery flows; add benchmark tests for large contact list merkle tree validation

• High · Outdated Go Toolchain Version — go.mod. The project specifies go 1.25.0 with toolchain go1.26.2. Go 1.25.0 is not a valid release version (Go versions follow 1.X.Y format where X is major). This indicates a configuration error that could lead to unpredictable behavior or use of an unintended Go version. Additionally, using a newer toolchain (1.26.2) than the declared minimum (1.25.0) may introduce compatibility issues. Fix: Update go.mod to specify a valid Go version (e.g., 'go 1.21.0' or 'go 1.22.0') and ensure the toolchain version is either the same or clearly justified. Consult the official Go release schedule.
• Medium · Cryptographic Library - golang.org/x/crypto Outdated — go.mod (golang.org/x/crypto v0.50.0). The dependency golang.org/x/crypto v0.50.0 is used for cryptographic operations. Older versions may contain security fixes in newer releases. Go's cryptographic libraries receive regular updates for algorithm improvements and vulnerability patches. Fix: Update golang.org/x/crypto to the latest available version (currently v0.30.0+). Run 'go get -u golang.org/x/crypto' and test thoroughly before deployment.
• Medium · Network Libraries - golang.org/x/net Potentially Outdated — go.mod (golang.org/x/net v0.53.0). The dependency golang.org/x/net v0.53.0 is used for network operations. Older versions may have unpatched vulnerabilities related to network handling, TLS, and protocol processing. Fix: Update golang.org/x/net to the latest version. Run 'go get -u golang.org/x/net' and verify no breaking changes affect the WhatsApp protocol implementation.
• Medium · Missing Security Headers in CI/CD — .github/workflows/. GitHub Actions workflows are present (.github/workflows/go.yml) but their configuration is not shown. Without visibility into the CI/CD pipeline, there's a risk that security checks (SAST, dependency scanning, supply chain security) may not be properly implemented. Fix: Ensure the CI/CD pipeline includes: 1) Dependency vulnerability scanning (via 'go list -json -m all | nancy'), 2) SAST scanning, 3) Code coverage enforcement, 4) Cryptographic signature verification of releases.
• Medium · Protobuf Library Version May Have Vulnerabilities — go.mod (google.golang.org/protobuf v1.36.11). The dependency google.golang.org/protobuf v1.36.11 is used for protocol buffer handling. While relatively recent, protobuf libraries can have parsing vulnerabilities that impact security. Fix: Verify v1.36.11 is the latest available version. Monitor security advisories for protobuf. Consider pinning to the absolute latest stable release.
• Low · Missing SECURITY.md — Repository root. The repository does not include a SECURITY.md file for responsible disclosure of vulnerabilities. This makes it harder for security researchers to report issues privately. Fix: Create a SECURITY.md file following GitHub's recommended format that includes: vulnerability reporting process, security contact information, and supported versions receiving security updates.
• Low · No Evidence of Signed Releases — Repository root and GitHub releases. While the project appears well-maintained, there is no visible evidence (from the provided structure) of cryptographically signed releases or commits, which could help users verify authenticity. Fix: Implement signed Git tags and releases using GPG. Document the public key for users to verify downloads. Enable branch protection requiring signed commits.
• Low · Third-Party Cryptographic Dependency - libsignal — go.mod (go.mau.fi/libsignal v0.2.1). The project depends on go.mau.fi/libsignal v0.2.1 for Signal protocol implementation. While a well-regarded library, external cryptographic dependencies introduce supply chain risk. Fix: Regularly audit libsig

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.