CVfast — AI Recruiter built with Claude Code

Two intake modes

Same brief, same scorer, same dashboard — pick the source that fits the role. Most engagements use both: web first to find people who aren't applying, inbox to triage the ones who are.

A · Web research

Claude + `web_search`

Claude browses public profiles, press mentions and platform pages, returns 25 candidates as JSON. Reproducible from a cron.

make research          # → candidates/claude-run-NN.json

B · Inbox scan

Gmail attachments → JSON

Read-only Gmail scope. Pulls PDF / DOCX CVs, extracts text, asks Claude to fill the same candidate shape. Never sends mail.

make inbox-auth        # one-time OAuth
make inbox-scan        # → candidates/inbox-run-NN.json

The pipeline

STEP 01

Brief

A YAML file: skills, target arcs, filters, signals, red flags. Edit this first.

STEP 02

Intake

Web research or inbox scan — both produce the same candidate JSON shape.

STEP 03

Score

Deterministic local Python — arc 40, content 25, recency 15, cuisine 10, geo 10. No LLM in the ranking.

STEP 04

Outreach + review

Claude drafts ~90-word emails per top-10. You approve in dashboard.html, then send.

Quick start

1. Get the code

git clone https://github.com/azizsaif1967-afk/aziz-saif-story.git
cd aziz-saif-story/eatcookjoy-recruiter
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env       # paste ANTHROPIC_API_KEY

2A. Web research mode

make research              # Claude + web_search
make score                 # rank
make outreach              # draft top-10 emails
make serve                 # http://localhost:8765/dashboard.html

2B. Gmail inbox-scan mode

Five-minute Google Cloud Console setup, then one OAuth click. Full walkthrough in INBOX_SCAN.md.

Create a Google Cloud project, enable the Gmail API.
Create an OAuth client (type: Desktop app), download the JSON.
Save it as gmail-credentials.json in eatcookjoy-recruiter/ (gitignored).
Run make inbox-auth — your browser opens, you sign in once.
Run make inbox-scan — it reads matching CVs and writes candidates/inbox-run-NN.json.
Then make score CANDIDATES=candidates/inbox-run-01.json && make outreach && make serve.

Privacy. The Gmail scope is gmail.readonly — the script literally cannot send, label, archive or delete anything. gmail-credentials.json and gmail-token.json never leave your machine; both are gitignored. CV text is sent to the Anthropic API for field extraction. Revoke any time at myaccount.google.com/permissions.

One role brief in. Ranked shortlist + personalised outreach out.