- name
- signal-history-search
- description
- Search Signal Desktop message history on macOS with sub-second query times. Queries the encrypted SQLite database directly without export overhead.
- license
- MIT
- metadata
- author
- Nicolai Schmid
- version
- 1.0.0
- requires
- scripts
- search
- ./scripts/signal-search
Signal History Search
Direct SQL search against Signal Desktop's encrypted database. Queries complete in under 1 second against live data.
When to use
- You need to quote or summarize prior Signal conversations.
- You already have Signal Desktop installed on macOS.
- You want fast, instant search without export delays.
How it works
- Retrieves the encryption key from macOS Keychain (
Signal Safe Storage) - Decrypts the key using PBKDF2 (same as Signal Desktop)
- Opens the SQLite database directly with SQLCipher
- Runs SQL queries against
messages and conversations tables - No files are written; searches happen in memory
First run caches the Python environment path (~5-10s setup), subsequent runs are sub-second.
Usage
# List all available chats
signal-search list
# Dump all messages from a specific day
signal-search dump --date "2026-01-25"
# Dump a specific day's chat with one person
signal-search dump --date "2026-01-25" --chat "Dariush"
# Search within a specific chat
signal-search search --query "istanbul" --chat "Monika"
# Search with context (messages before/after matches)
signal-search search --query "flight" --chat "Monika" --context 3
# Regex search across all chats
signal-search search --query "invoice.*\d{4}"
# Literal string search (not regex)
signal-search search --query "100$" --literal
# Case-sensitive search
signal-search search --query "API" --case-sensitive
# Limit number of results
signal-search search --query "meeting" --max-count 10
Commands
| Command | Description |
|---|
list | List all available chats (name and type) |
dump | Dump all messages from a specific day |
search | Search messages |
Dump Flags
| Flag | Short | Description |
|---|
--date <YYYY-MM-DD> | -d | Date to dump (required) |
--chat <name> | -c | Filter to chats containing this string |
Search Flags
| Flag | Short | Description |
|---|
--query <pattern> | -q | Search pattern (regex by default) |
--chat <name> | -c | Filter to chats containing this string |
--context <n> | -C | Show N messages before and after matches |
--max-count <n> | -m | Stop after N matches |
--case-sensitive | -s | Case-sensitive search (default: smart-case) |
--literal | -F | Treat query as literal string, not regex |
Output Format
> [2026-01-15 12:01:11] Monika Schmid | Monika Schmid: Habe Fluge gebucht!
[2026-01-15 12:40:53] Monika Schmid | Me: Schon!
- Lines starting with
> are matches - Format:
[timestamp] Chat Name | Sender: Message - Context lines (if requested) don't have the
> prefix
Performance
| Operation | Time |
|---|
| First run (env setup) | ~5-10s |
| Subsequent searches | <0.5s |
| Full chat search (1000s of messages) | <1s |
Security considerations
- The database key is retrieved from macOS Keychain using
security find-generic-password - No data is written to disk; all searches happen in memory
- The cached Python path is stored in
~/.cache/signal-search/ - Searches happen locally; nothing leaves your machine
Legacy: Export-based search
The old export-based script (signal-history-search) is still available but deprecated. It uses sigexport to create a temporary export, then searches with ripgrep. This is slower (~15-30s) but may be useful if the direct DB access fails.
# Old method (slower, requires full export)
signal-history-search search --chat "Name" --query "pattern"
Troubleshooting
- "Failed to get keychain password": Ensure Signal Desktop has been opened at least once and you've granted keychain access
- "Signal Desktop not found": Check that
~/Library/Application Support/Signal exists - First run slow: This is normal; nix-shell is setting up the Python environment with SQLCipher bindings
- "nix-shell: command not found": Install Nix package manager
