Hire 10 promoters from 1,040 CVs — in one terminal command.

What this process replaces

A recruiter or HR ops manager spending three to five days opening 1,040 CVs one by one — copying name, visa, languages, and experience into a spreadsheet, then guessing which ten to call. This pipeline does the same job in minutes, with the same answer every time, and hands you a dashboard your hiring manager can actually search.

The architecture

What's in the toolkit

A tiny, working Python repo. No frameworks, no servers, no SaaS account. Read the CLAUDE.md once inside Claude Code and it knows the entire workflow.

Quick start

npm install -g @anthropic-ai/claude-code
cd Hr-recuritement-ai-process/promoter_screener
claude                              # reads CLAUDE.md automatically
/setup                              # one-time install + key
# drop Indeed + WhatsApp CVs into ~/Downloads/promoter_cvs
/screen                             # runs everything, reports top 10
# open output/dashboard.html

Or run the pipeline directly

pip install -r requirements.txt
python run_screener.py
# → output/dashboard.html         searchable, sortable, top 10 in gold
# → output/candidates.xlsx        every candidate, every field
# → output/top10_shortlist.pdf    clean shortlist for your manager
# → output/candidates.json        raw structured data

The scoring model

Four hard must-haves drive ranking. Candidates are sorted first by how many of the 4 they meet, then by score. The whole table lives in analyze.py → score_candidate; change a number, save, re-run.

Tiers

A meets all 4 must-haves  ·  B meets 3  ·  C meets 2  ·  D weak fit

The Top 10 (set by TOP_N in config) are highlighted in gold across the dashboard, Excel, and PDF.

Two engines, one pipeline

AI_ENGINE = "rules"

AI_ENGINE = "llm"     # or "auto"
ANTHROPIC_MODEL = "haiku"   # or "sonnet"

Cost tip for 1,000+ CVs

Set LLM_RESCORE_ONLY_TOP = 60. The free rules engine scores every CV instantly, then Claude only re-analyses the 60 strongest. You get LLM accuracy where it matters while paying for a fraction of the calls.

Reuse it for any role

The whole toolkit is one folder. To screen for a different role:

• Edit job_description.txt — the JD the AI re-reads each run.
• Update the keyword banks at the top of analyze.py (HYPERMARKETS, SALES_TERMS, OWN_VISA_TERMS, IMMEDIATE_TERMS).
• Adjust the WEIGHTS dict if must-haves change.
• Drop the new role's CVs in the folder. Re-run.

That's it. The dashboard, Excel, and PDF auto-rebuild against the new criteria.

Run the screener — right here, in your browser

Want just the tool, no write-up? Open the clean screener app →

This is the real engine, not a video. Drop your own CVs (PDF · DOCX · TXT) into the box below — or paste CV text — and the page reads each file, extracts the fields, scores every candidate against the JD using the exact keyword + weight model from analyze.py, and renders the searchable shortlist dashboard. No upload to any server, no API key — everything runs locally in your browser. No CVs handy? Click Run 22 sample CVs to see a full run instantly.

How this got built — the actual conversation

No spec doc, no Jira ticket. Three Q&A rounds with the agent took the role from "I need 10 promoters" to a working pipeline verified on 22 sample CVs. The exchange below is the real transcript.

npm install -g @anthropic-ai/claude-code
cd promoter_screener
claude        # reads CLAUDE.md automatically
/setup        # one-time
# drop Indeed + WhatsApp CVs into ~/Downloads/promoter_cvs
/screen       # runs everything, reports top 10
# open output/dashboard.html

Three rounds. Working pipeline. The build conversation is the requirements doc — nothing else got written down.

Follow-up workflow — Daily Tier A catcher

One real-world question after the first run was: "Catch net-new Tier A Promoter candidates from Gmail and Indeed.ae every weekday before my hiring review, ranked by visa and hypermarket fit." Same scoring model, scheduled. This is now built and runnable — the files below ship in promoter_screener/, and python catch_tier_a.py --demo runs the whole flow end-to-end with no credentials. The mind tree below is the design it implements.

How it reuses what's already built

• Same scorer. Imports analyze_rules() / score_candidate() from analyze.py — one source of truth for ranking.
• Same JD & same store. Reads job_description.txt and diffs against the very same output/candidates.json the screener writes, so it only ever alerts on net-new people.
• Shipped files: catch_tier_a.py, gmail_poll.py, indeed_pull.py, diff.py, digest.py, the /catch-tier-a slash command, and a ready-to-copy GitHub Actions cron template.
• No new model logic. If you tune weights in analyze.py for the screener, the catcher inherits it automatically the next morning.
• Runs with zero credentials. Gmail / Indeed / WhatsApp connectors degrade gracefully to local folders + a saved digest, so it works before you wire up any API keys.

# Zero setup — seeds fresh sample CVs and runs the whole flow:
python catch_tier_a.py --demo

# Real run — pull since last night, send the digest to WhatsApp + email:
python catch_tier_a.py --since "yesterday 17:00" --digest whatsapp+email

# Or inside Claude Code:
/catch-tier-a since=yesterday digest=whatsapp+email

The whole recruiting agent on one screen

Screening is step 3 of a bigger loop. Here's the end-to-end flow an end user actually follows — you type one brief in Claude Code, the agent runs five steps, and a single Google Sheet is the live database behind all of it.

Open the full interactive demo → Try the live CV screener HR Skill & workflows reference

Where this fits in the full HR workflow

This page covers the screening half of HR Workflow 01. The mind-tree on the home page shows the full loop — from AI-written JD and Indeed posting through to a LiveKit voice agent confirming the Zoom slot in EN/AR/HI. Screening is the link in the middle that turns 1,040 raw CVs into the 10 calls worth making.

See all 10 SMB AI workflows → See the full recruiting-agent demo See the chef-recruiter variant