PeopleBlade is a contact book that runs on your computer and gathers the people you know from separate accounts into one private record you can search, review and annotate. A colleague's work email might sit in Google Contacts, her number in a WhatsApp chat, your last conversation in Beeper, and the record of how you met in a LinkedIn connection. PeopleBlade brings those into one entry for her.
The record is a SQLite database on your own machine. Every imported detail keeps the source it came from, two records join into one person only after you review the match or turn on a strict exact-match pass, any join can be undone, and your notes stay local. Cloud sign-in is optional, and the complete contact book never has to leave your computer.
Who PeopleBlade is for
PeopleBlade is for one person organizing the relationships they already have, either in a visual workspace in the browser or through their own coding agent. The command line tool returns JSON, so an agent can search contacts, read a person's details and prepare cited public research with the same commands you would run. The agent acts with your authorization, and PeopleBlade runs no hosted service that acts on its own.
It runs with Bun on macOS and Linux. Apple Contacts and iMessage imports need macOS.
Use something else if you need a shared team CRM, a public contacts API for other apps, or a tool that sends invitations or messages in bulk. PeopleBlade has no general contacts API, MCP server or OAuth app for third parties. It does not send invitations or automated outreach. Its one sending command is described below, and it sends a single file to a single person after you confirm.
What it does today
A first session on a Mac can look like this. With --json, the first four commands print JSON, and none of them needs an account or a network connection:
peopleblade init --json # create the private database
peopleblade contacts sync --json # read Apple Contacts, never write back
peopleblade imessage sync --json # participant emails and phone numbers only
peopleblade identity suggest --limit 25 --json # possible duplicates, for you to review
peopleblade ui # print a local address for the workspaceThe workspace runs on a loopback address on your own machine, and you open it with a private access file the command creates. It shows searchable, filtered pages of people, their details and your Markdown notes, with edit history. It does not sync to the cloud or contact anyone.
The source list today includes Apple Contacts, iMessage, Google Contacts, Beeper, WhatsApp, LinkedIn, Instagram and X archive metadata. Several of those come from files you download yourself. LinkedIn connections come from LinkedIn's official data export, Instagram from its official Accounts Center archive, and X from your own archive file. The PeopleBlade guide covers the setup for each one.
A few rules hold across every source:
- Names never join people on their own. Exact provider details such as an email address or a WhatsApp ID can anchor a person. Fuzzy candidates stay separate until you review them. An optional pass can join records that share one exact email, or one exact phone number when the names are compatible, and every join can be undone.
- Message text is not kept. The iMessage import reads participant emails and phone numbers and never reads message bodies. Provider imports record who you talked to, not what was said.
- Your notes stay on your machine. Optional cloud sync uploads a smaller copy of your contacts for a private web dashboard. It leaves out your notes, raw source records, message bodies, provider credentials and local file paths.
Live accounts go through Ghostget
Google Contacts, Beeper and WhatsApp are live accounts, and reading them needs a signed-in session. PeopleBlade does not hold those sessions and never drives a browser itself. It hands each read to Ghostget, a separate command line tool that you install and sign in to yourself.
PeopleBlade treats Ghostget as a dependency that has to prove what it is each time. Before any call, it checks that the installed ghostget executable reports the exact release PeopleBlade was reviewed against, and refuses to run otherwise. For imports, it asks only for named read operations, such as listing contacts or searching them. When a result comes back, PeopleBlade checks that the operation, adapter version and contract fingerprint match what it expected, and parses the result again before anything is written to your database. If any of those have changed, the read stops with a message that explains what drifted, and nothing is saved. PeopleBlade does not retry on its own.
For Google Contacts, the authorization asks for read-only contact scopes, and the sync does not read Gmail messages. The Beeper import reads contacts and search results and, on Apple silicon Macs, can add counts of direct-message activity without message text. LinkedIn works the same way at a smaller scale: after you import your official export, one command can read the Contact info panel of a single first-degree connection through Ghostget. It reads one profile per command, never lists your connections, reads no messages and sends no invitations.
How PeopleBlade uses Ghostget walks through that path in more detail.
What it will send, and what it will not
PeopleBlade never exposes Beeper sends or other Beeper actions. It sends through your messaging accounts in one case only, which grows out of its privacy tools.
The exposure tools help you see how much of your own information is already public, and then fix it. You run them yourself and record consent first (--scope self for your own record). A contact enters scope only with explicit consent you record for them, and a do-not-contact mark blocks the tools for that person. Findings record which kinds of detail are exposed and where, not the exposed values, and they never sync to the cloud. The results are not a background check and are not meant for employment, credit, housing or insurance decisions.
From a consented assessment, usually your own, exposure attest writes a signed summary that holds counts and digests, no personal details. The person who receives it can verify the signature with exposure attest-import. You can hand the file over any way you like, and if you want PeopleBlade to deliver it, the one sending command is:
peopleblade exposure attest-send /private/path/posture.json \
--to PERSON_ID --provider imessage --confirm --jsonIt delivers that one file as a single attachment to that contact's one matching iMessage or WhatsApp conversation, and refuses if it finds no match or more than one. It runs only after you allow attachment sending in Ghostget, through a one-time permission that expires after 24 hours, and pass --confirm. Ghostget records each send in a journal before it runs, and sending the same file to the same person again does not send it twice. If the outcome is uncertain, PeopleBlade waits for you to check what happened and does not try again.
Where PeopleBlade is going
Two of the product's own lines are "Keep everyone you know in one private book" and "built for agents." The intent is a single record of your relationships that you own, that your agent can read with your permission, and that never asks you to hand your agent a browser or your passwords.
More sources are meant to join the same way the current ones did: each live account through a reviewed Ghostget read, each export through a strict parser for the official file. X live mutuals and Telegram are next in line. Neither has a date.
Limits and status
X live mutuals are blocked. They are waiting for a reviewed Ghostget capability, and there is no fallback to the X API or to reading pages in a browser. Telegram support is waiting for the first real Telegram Desktop export to test against. Beeper sends are not supported. LinkedIn connections come only from your official export, and the Contact info read covers one first-degree connection per command; LinkedIn hides that panel for other profiles, and PeopleBlade does not guess.
Live Google, Beeper and WhatsApp imports, the LinkedIn Contact-info read and exposure attest-send need Ghostget installed separately at the exact supported release. The core local commands and the official archive imports do not. Cloud sync is one-way and optional; it is not a backup of your full contact book or a two-way address book sync. The command line package is free and MIT licensed; the web application is not open source.
Latest release: v0.5.0. Install the command line tool with bun add --global @hraness/peopleblade@0.5.0.