Bly

A career agent that runs your job search out of your own inbox — on your own machine.

Your job search doesn't live in a tracker. It lives in a hundred threads across months: an approach you meant to answer, a process that went quiet at stage three, a recruiter who has now written twice about two different roles at the same company.

Every tool that tries to fix this asks you to re-enter what your mailbox already knows. Bly does the opposite — it reads the mailbox, and the board falls out of it.

Named after Nellie Bly, the reporter who went and checked things herself. Which is the difference between this and a pattern-matcher.

Bly is free and open source, and it is software you run, not a service you sign into: your mail, the database it builds, and everything derived from it stay on your machine.

Install

npm i -g @yellow-pine/bly

Requires Node 24+.

Get going

bly connect      # 1. your Google account, in your browser
bly sync         # 2. reads your mail — the last 90 days first; safe to re-run
bly serve        # 3. your board, on localhost

bly connect needs a Google OAuth client of your own — about five minutes, once, so the credential to your mailbox is issued to you and never passes through anyone else's servers. bly connect prints that walkthrough itself, and bly status tells you what's missing at any point, in the order to fix it.

Ingest a Takeout export instead

If you'd rather skip the OAuth flow, export your mail from Google Takeout — select Mail, delivery format .zip, export type mbox — and point Bly at the file instead of connecting Gmail:

export BLY_INBOX=mbox
export BLY_MBOX_PATH=~/Downloads/Takeout/Mail/"All mail Including Spam and Trash.mbox"
bly sync         # reads the file; safe to re-run, e.g. after a fresh export

bly connect and its OAuth walkthrough aren't needed here; bly sync reads the whole file each time and skips anything it's already seen, so re-running after a bigger re-export only costs the messages that are actually new. A message it can't make sense of (no Message-ID, no From, no usable date) is counted and named, never silently dropped.

The commands

| | | | --- | --- | | bly connect | Authorise Bly against your Gmail account. Connecting a different account switches to it — two connected mailboxes never merge, and it says which one you are on | | bly sync | Fetch new mail into the local log. The first run mirrors the last 90 days, so your board appears without waiting on a decade of mail; every later run fetches another chunk of older mail until the whole mailbox is mirrored. --since=YYYY-MM-DD starts that first window earlier, --full fetches everything now, --max-pages=N does a chunk at a time. Resumable throughout | | bly serve | Open the full interface on localhost: board, today, brief, and your own corrections | | bly board | Print the board to the terminal, grouped by stage | | bly today | Only what needs you: waiting on you, or gone quiet | | bly status | What's configured and what isn't | | bly logout | Delete the stored Google token. Your local database is untouched | | bly reset | Empty the local database, keeping your Google connection. Dry run by default; --yes does it |

What it will not do

These are structural, not settings. An agent reading attacker-controlled email on a personal machine has to be boxed in by what it cannot reach, not by what it is asked nicely to avoid.

• Never sends anything. Bly writes drafts. A human presses send, every time. There is no configuration that changes this.
• Never writes to your mailbox. Read-only scopes plus drafts. No labels, no flags, no folders. Your inbox is a source, not somewhere Bly keeps state.
• Never overwrites your judgement. Stage, next action, notes and fit are yours. They're recorded as overrides with who and when, and re-derivation reads around them.
• Never leaves your machine. Your mail, the database it builds, and everything derived from it stay in ~/.bly — and nothing ever crosses the network to us, because Bly has no server to phone. The only hosts it contacts are Google's, to read your own mail.

Where things live

~/.bly/db-<mailbox>/    your database — mail, roles, your corrections; one per connected mailbox
~/.bly/mailboxes/       which mailbox each database belongs to (hashed), and which one is active
~/.bly/credentials.json your Google token (0600)
~/.bly/client.json      your OAuth client

Connect a second account and it gets a second database directory — nothing merges, and the board you see is whichever mailbox you connected or synced last. bly status names it.

To start over with an empty database, run bly reset: it removes the stores and the registry and keeps your Google token and OAuth client, so there is no browser round trip to do again. The bare command is a dry run that lists exactly what would go; bly reset --yes does it.

rm -rf ~/.bly also works and removes everything Bly holds — there is no copy anywhere else. It is not free, though: the directory also holds your Google credentials, so the next run starts with bly connect from scratch. bly reset exists so you never have to pay that.

Your AI subscription, not ours

Bly runs inference through your own Claude subscription, on your machine, under your own credentials — which Bly never sees, stores, or proxies. It also runs against a Claude Console API key (ANTHROPIC_API_KEY) if you'd rather, and falls back to a deterministic, model-free mode that needs no credentials at all.

About the AI

Bly uses AI models to read and summarise your mail, and models get things wrong. Treat every verdict, draft and summary as a first pass to check — not a decision that's been made for you.

Contributing

Issues and pull requests are welcome. The contributing guide covers the setup (npm ci and you're running — there are no credentials to provision), where code goes, the handful of structural rules a change has to respect, and where to read next about why the code is shaped the way it is.

Found a security issue? Don't open a public issue — see the security policy.

By participating you agree to the Code of Conduct.

Licence: Apache-2.0. Home: bly.fyi — the demo and the setup guide, and nothing that could ever hold your mail.