Contact book for agents

Bring your contacts together in one private book.

PeopleBlade builds one contact book on your computer from your address book, accounts, and exports. Your agent searches it, keeps notes, and tells you which import each contact came from.

There is no app to open. Your agent runs PeopleBlade's commands against a private database on your computer.

bun add --global @hraness/peopleblade@0.12.0

Free and MIT licensed
macOS and Linux
Bun 1.3.14 or newer

See how it works Try it in a minute

import sources: 15; PeopleBlade imports from 15 sources: two on your Mac, five signed-in accounts through Ghostget, three official data exports, and five kinds of file you choose.
commands, each with JSON output: 100+; Every command accepts --json, and errors come back in one JSON format.
needed on your computer: No account; Local commands run without an account, a password, or a network request.
of chat or email text stored: 0 words; PeopleBlade's provider imports never keep, search, research from, or upload message text. It reads the archives you supply to find who you talked to and when.

How it works

Bring your contacts together.

PeopleBlade builds one contact book from what you already have. On a Mac it reads Apple Contacts and iMessage. Through Ghostget, a separate sign-in tool, it reads Google Contacts, Gmail interactions, Beeper, WhatsApp, and Substack subscribers. It also imports the official exports from LinkedIn, Instagram, and X, and contact files such as CSV and vCard.

Every source and its limits

Every contact lists the imports it came from. An exact email or phone match joins two records once you accept it, or automatically if you opt in. A shared name alone never does.

Import what you already have
On a Mac, this reads Apple Contacts without writing back. On Linux, start from a file with contacts import or linkedin import. Each source has its own command.
Terminal
```
peopleblade contacts sync
```
Accept the matches
Each suggestion shows the email address or phone number two records share. Accept or reject it, and undo an accepted match later with identity separate.
Terminal
```
peopleblade identity suggest
```
Ask your agent
Your agent runs the same commands and reads the JSON. It can search, sort by last contact, add notes, and set reminders.
Terminal
```
peopleblade query --search "Fieldwork Studio" --json
```

What you can do

Find people and keep the context.

Each part of a personal CRM is a command your agent can run.

Find people: Search names, organizations, titles, and contact details across every import. Filter by source or tag, and sort by last contact.
Keep notes: Add dated Markdown notes to a person, search them, and edit them with a full history of changes.
Follow up: Set a reminder with a due date, or a keep-in-touch cadence such as every six weeks. reminders due lists who needs a message.
Correct a detail: Edit a name, title, or organization. Later imports never overwrite your edit, and you can reset it to the imported value.
Research a person: Your agent can check one person's exact GitHub and Bluesky profiles and run cited public checks. PeopleBlade saves a finding only when it matches details you already hold.

Agents

Let your agent work with your contacts.

Claude Code, Codex, or any agent that runs shell commands can use PeopleBlade. You sign in to your sources; your agent works with the imported book.

You ask your agent; it runs peopleblade query on your computer and answers with Maya Chen's sources. — Your agent runs the same commands you would and reads their JSON. It needs no password, browser session, or message text.

The peopleblade command

Search, import, match, keep notes, and set reminders. Any agent that can run a terminal command can use it.

peopleblade people show 1 --json

A private file with one person's background

Background and cited public research for one person, in a private file your agent can read. Your notes and other contacts stay out of it. Soulscrape, a Hraness app for research on people, reads the same file.

Write the file Soulscrape

The /api/v1 connector

For agent platforms that can't run a command. A device you approve reads the contact details you upload with cloud sync, and you can revoke it at any time.

Approve a device

See an example search result

For example: “Who do I know at Fieldwork Studio?”

$ peopleblade query --search "Fieldwork Studio" --json
{
  "items": [
    {
      "id": 1,
      "displayName": "Maya Chen",
      "primaryEmail": "maya@example.com",
      "primaryPhone": "+1 415 555 0142",
      "interactionCount": 13,
      "lastInteractionAt": "2026-09-03T10:30:00.000Z",
      "sources": ["apple", "imessage", "linkedin"]
    }
  ],
  "total": 1
}

What your agent runs and reads back: output from PeopleBlade 0.12.0 after importing three fictional sources and accepting one suggested match, shortened to the main fields. The second Maya Chen, who shares only the name, stays a separate person.

Get started

Try it in a minute

You need Bun 1.3.14 or newer on macOS or Linux. Run the install command at the top of this page, then create your contact book and check that it works. A new book reports zero contacts, with no account and no network request.

Read the guide

peopleblade init
peopleblade stats

Then import your first source, peopleblade contacts sync on a Mac or peopleblade linkedin import FILE.zip anywhere, and connect signed-in accounts when you want Google, Gmail, WhatsApp, Beeper, or Substack.

Package and release details

Public CLI · npm 0.12.0

The CLI is on npm as @hraness/peopleblade 0.12.0, for Bun on macOS and Linux. Your contact book is a SQLite file on your computer, and you need a web account only for the optional device sync, cloud sync, /api/v1 connector, and hosted research.

View on npm Read the release guide

Sync

Sync only when you choose.

The master copy stays on your computer, and each way out is something you turn on.

Every field each command sends

Your computer keeps the master copy; device sync is encrypted, cloud sync sends contact details, checks send what they state. — Your contact book is a SQLite database on your computer. Data leaves it only when you run a command that sends something: device sync, cloud sync, a research check on public profiles, an exposure check against breach and public-record sources, or a Hunter work-email lookup. Each of those commands states what it sends.

Device sync: peopleblade sync carries the whole book, notes included, between your devices, end-to-end encrypted. The sync server stores only ciphertext. Sign in with a PeopleBlade account, then pair a device with a six-digit code.
How device sync works
Cloud sync: peopleblade cloud sync uploads contact details, called the contact projection, to your PeopleBlade account, for devices you approve and for hosted research, an optional service that looks up public details about a contact. It never includes notes or message text.
What cloud sync uploads
Checks you run: Research, exposure checks, and Hunter lookups send only what each command states, such as email hashes or profile URLs.
Read the privacy page

Limits

Know what your agent can access.

Passwords: Your agent never receives your account passwords. You sign in to Ghostget yourself, and PeopleBlade asks it for named read operations.
Message text: PeopleBlade's provider imports never keep, search, research from, or upload message text. It reads the archives you supply to find who you talked to and when.
Sending: The one command that sends through your messaging accounts, exposure attest-send, sends one contact a signed summary of an exposure check, after you allow attachment sending in Ghostget and pass --confirm.

Alternatives

Choose the contact book that fits.

Each alternative covers part of the job. PeopleBlade keeps the master copy on your computer and gives your agent commands to work with it.

Approach	What it gives you	Where PeopleBlade differs
Your phone's address book	A synced list of names and numbers inside one provider's account.	One book across your accounts and exports, with notes, reminders, and the source of each detail, and commands your agent can run.
A hosted CRM	Deal pipelines for sales teams, hosted on the vendor's servers and priced per seat.	The master copy is a SQLite file on your computer, and your agent works through the CLI beside it. The web account page only approves devices and holds credits.
Giving an agent your accounts	Signed-in sessions with your passwords, scrolling your inbox and chats.	Your agent runs PeopleBlade commands. It gets no passwords and no message text, and every match shows the email or phone that two records share.
Notes apps and spreadsheets	Flexible text about people, detached from who they are.	Notes attach to one person, each contact lists the imports it came from, and two records join only when you accept the match.

Dex and Mesh are hosted personal CRMs with apps that sync your accounts and remind you to keep in touch. Monica is an open-source web app you self-host or rent. Clay builds prospect lists for sales teams. PeopleBlade is free, has no app, and keeps your book on your computer for your agent.

FAQ

Questions

Do I need an account?

No. Every local command works without an account, a password, or a network request. You need an account only for device sync, cloud sync, the /api/v1 connector, or hosted research.

Is there an app or a web view of my contacts?

No. PeopleBlade is headless: you or your agent run peopleblade commands, and every command can print JSON. The website has a small account page for approving devices and checking credits, and no contact list.

Which contacts can I bring?

PeopleBlade imports from 15 sources: two on your Mac, five signed-in accounts through Ghostget, three official data exports, and five kinds of file you choose. They are Apple Contacts, iMessage, Google Contacts, Gmail interactions, Beeper, WhatsApp, Substack subscribers, LinkedIn, Instagram, X data archive, Contact CSV, vCard contacts, Outlook contact export, Calendar invitations, and Apple Photos. Apple Contacts and iMessage need macOS. Substack sync handles publications up to 500 subscribers. The sources page lists each one with its limits.

How do signed-in accounts like Google and WhatsApp work?

Through Ghostget, a separate Hraness tool you install and sign in to yourself. PeopleBlade asks it for named read operations and checks each answer before saving anything. Signed-in accounts need Ghostget 0.18.44 or a later 0.18 release. The guide has the setup steps for each account.

How does matching work?

A shared name never joins two people. An exact email or phone match joins them after you accept it, or when you opt in to auto-accept. You can undo an accepted match with identity separate.

What can my agent reach?

An agent that runs the CLI can search your contacts and read and write your notes. It never gets your account passwords, and PeopleBlade keeps no message text for it to read. The one command that sends through your messaging accounts, exposure attest-send, sends one contact a signed summary of an exposure check, after you allow attachment sending in Ghostget and pass --confirm. A platform using the /api/v1 connector reads only the contact details you upload with cloud sync.

What does it cost?

The CLI is free and MIT licensed. Your agent or model may charge separately. Hosted research is optional and has a free preview; paid runs are not open yet.

What do I need to run it?

macOS or Linux with Bun 1.3.14 or newer. Install from the terminal, then point your agent, such as Claude Code or Codex, at the peopleblade command. Apple Contacts and iMessage imports require a Mac.

Your account

Sign in with email

Continue with email code ↗

Other Hraness tools work alongside PeopleBlade. Some are apps for your messages, notes, and research on people; others help run the agents that use them.

Apps for the people, messages, and notes in your life.

SoulscrapeFree agent skill that writes dated dossiers on people, sources cited
TextbutlerAI butler for the iMessage, WhatsApp, and Beeper chats you choose
WordcellMarkdown knowledge base that gives agents the decisions behind code

The layer your agent runs through: sessions, accounts, web reads, and the models behind them.

GhostgetNamed web actions for AI agents: read pages, save media, use connected accounts
GobstopperCompacts long agent sessions into smaller copies, keeping every byte
xcbRoutes coding tasks across the Claude, Codex, and Devin plans you have
AI ChartsModel benchmark scores plotted against cost and tokens per task

Headless personal CRM for everyone you know, built for your agent

Read as Markdown

Bring your contacts together in one private book.

Bring your contacts together.

Import what you already have

Accept the matches

Ask your agent