A personal job-search agent. It reads public ATS APIs every morning, throws away the ~99% that don't fit you, scores what's left against your resume, drafts an application kit for the best few, and emails you a digest.
It never submits an application. It finds, filters, ranks and drafts. You read the digest, edit the cover note, and press submit yourself.
2000 postings → 40 candidates → 5 in your inbox
fetch regex/location LLM screen
/freshness gate + draft
(free, no LLM)
New to Python? Read SETUP.md instead — it's a 13-step guide that assumes you have nothing installed. This README assumes you're comfortable with a terminal.
git clone <your-repo> && cd jobhunt
python -m venv .venv && .venv/Scripts/activate # Windows
# python -m venv .venv && source .venv/bin/activate # macOS/Linux
pip install -r requirements.txt
python -m jobhunt run --mock --scorer keyword--mock runs bundled fixtures through the real parsers — no network.
--scorer keyword swaps the LLM for a dumb token-overlap stub, so the whole
pipeline runs with no secrets configured. You should see:
[2/5] filtering
prefilter: 12 -> 5 (dropped title=5 location=1 stale=1)
[3/5] screening 5 jobs (keyword stub — DEV ONLY)
3 scored >= 7.0
[5/5] digest
wrote out/digest.html
funnel: 12 scanned -> 5 passed filters -> 5 new -> 3 in digest
Open out/digest.html in a browser. That's the email you'd have received.
The keyword scorer is dev-only. It cannot tell a Staff role from a new-grad one and has no idea what the words mean. It exists to prove the plumbing, never to build a digest you'd act on.
Edit companies.yaml. The slug is the last path segment of a company's public
careers board:
| Board URL | ats |
slug |
|---|---|---|
boards.greenhouse.io/stripe |
greenhouse |
stripe |
jobs.lever.co/netlify |
lever |
netlify |
jobs.ashbyhq.com/ramp |
ashby |
ramp |
The shipped list is examples — verify each before trusting the output. Companies migrate between ATS vendors and slugs go dead. A dead slug prints an HTTP status and returns nothing; it never kills the run. Watch the per-board counts on stdout: a board reporting 0 every day is a slug that needs fixing.
Start with 10–15 companies. A list of 200 is mostly noise.
No LinkedIn or Naukri. Neither has a public API and scraping them violates their terms of service. The three ATS endpoints above are documented, unauthenticated, and intended to be read.
config.yaml holds the deterministic gate that runs before any LLM call.
This is the whole cost story — get it right and you spend cents a day.
filters:
include_titles: ['\bsde\b', 'software development engineer', ...]
exclude_titles: ['\b(staff|principal)\b', '\b(manager)\b', ...]
locations: [bangalore, bengaluru, india]
allow_remote: true
max_age_days: 30
score_threshold: 7.0
max_per_digest: 5
sdedoes not match "Software Development Engineer". They share no substring. Use\bsde\bfor the acronym and list the spelled-out variants separately, or you'll silently miss half of Amazon-style postings. There's a test pinning this.
cp .env.example .env # add ANTHROPIC_API_KEY
python -m jobhunt profile --resume resume.pdfPDFs go over as a base64 document block (Anthropic and Gemini both read them
natively — no OCR, no text extraction library). .txt and .md also work and
are the fallback for providers that can't take documents.
This writes profile.json. It's gitignored — read it, fix anything the model
got wrong, and keep it out of version control.
python -m jobhunt run # build the digest
python -m jobhunt run --send # ...and email it
python -m jobhunt run --limit 10 # cost guard while tuning
python -m jobhunt run --no-draft # screen only, skip the expensive passScreening reads hundreds of jobs and wants the cheapest decent model. Drafting runs ~5 times and wants the best one. So they're configured separately:
LLM_PROVIDER=anthropic # sets both stages
SCREEN_PROVIDER=groq # ...override per stage
DRAFT_PROVIDER=anthropic
SCREEN_MODEL=claude-haiku-4-5-20251001
DRAFT_MODEL=claude-sonnet-5| Provider | Value | Key | PDF resumes | Notes |
|---|---|---|---|---|
| Anthropic | anthropic |
ANTHROPIC_API_KEY |
yes | default; uses the official SDK |
| Google Gemini | gemini |
GEMINI_API_KEY |
yes | generous free tier |
| Groq | groq |
GROQ_API_KEY |
no | very fast, free tier |
| OpenAI-compatible | openai-compatible |
GROQ_API_KEY + LLM_BASE_URL |
no | Together, OpenRouter, vLLM |
| Ollama | ollama |
none | no | fully local, OLLAMA_HOST |
Everything except Anthropic goes over plain requests, so you can delete the
anthropic line from requirements.txt and still run the whole thing.
Adding a provider is one class in jobhunt/providers.py
with a complete() method, plus an entry in the PROVIDERS dict.
seen.json is both the dedupe index and the application tracker — a job you've
already been shown is never shown again. It's gitignored: it's yours, and
shipping one would break the first run for anyone who cloned the repo.
python -m jobhunt applied "greenhouse:stripe:5501001" # id is in the digest
python -m jobhunt stats # + CSV exportout/tracker.csv opens in any spreadsheet.
.github/workflows/daily.yml runs it at 06:00 IST
on weekdays. seen.json is carried between runs with actions/cache, not
committed — it's personal, and a seen.json in the repo would mark every job as
already-seen for anyone who cloned it. Nothing personal ever enters git.
Repository secrets to set (Settings → Secrets and variables → Actions):
| Secret | What |
|---|---|
PROFILE_JSON |
the entire contents of your local profile.json |
ANTHROPIC_API_KEY |
(or GEMINI_API_KEY / GROQ_API_KEY) |
SMTP_USER / SMTP_PASS |
Gmail address + App Password, not your login |
MAIL_TO |
where the digest goes |
Optional repository variables: LLM_PROVIDER, SCREEN_PROVIDER,
DRAFT_PROVIDER, SCREEN_MODEL, DRAFT_MODEL.
Trigger it by hand first — Actions → daily job digest → Run workflow, with
dry_run ticked to build the digest artifact without emailing.
Gmail needs an App Password; your normal password stops working once 2FA is on.
jobhunt/
fetch.py Job dataclass, strip_html, 3 pure parsers, fetch_all
prefilter.py title/location/freshness gate — no LLM, no cost
providers.py the swappable provider interface + 5 backends
llm.py screen() / draft() / build_profile() / keyword stub
digest.py HTML email (inline CSS only — Gmail strips <style>)
mailer.py SMTP
store.py seen.json dedupe + tracker + CSV export
mock.py fixtures in each ATS's native JSON shape
cli.py argparse: profile / run / applied / stats
config.yaml filters, thresholds, paths
companies.yaml boards to poll
tests/ 55 tests, no network, no key
HTTP is kept out of the parsers on purpose. Each parse_*(slug, company, body)
takes already-decoded JSON and returns list[Job], which is what makes --mock
exercise the real code path instead of a parallel implementation.
Every job gets job_id = "{ats}:{slug}:{id}" — globally unique, so the same
role posted on two boards is still two rows, and a re-run never duplicates.
- Greenhouse —
contentis HTML-entity-escaped HTML. Unescape before stripping tags and again after, or you ship&into the prompt. - Lever —
createdAtis epoch milliseconds. The full JD is split acrossdescriptionPlain+lists[].text+lists[].content+additionalPlain; concatenate all four or you lose the requirements section and every job looks unqualified. - Ashby — skip
isListed: false; those are unpublished drafts.
python -m pytest tests -qNo network, no API key, no cost. The suite covers:
- each parser against fixtures in its native ATS shape
- the two bugs that cost me an evening each: Lever's epoch-ms timestamps
(fixture dates are generated relative to now, never hardcoded, so they
can't silently age past the freshness gate) and the
\bsde\bregex - prefilter rejects the planted junk: wrong seniority, wrong city, wrong function, a stale posting, an unlisted Ashby draft
- the LLM layer with the provider stubbed: batching splits at the configured size, JD truncation is applied before send, fenced/preamble/object-or-array JSON all parse, scores land on the right job when returned out of order, a failed batch warns and the run continues, and the draft kit always has every key the digest renders
With ~15 boards, a tight config.yaml, Haiku screening and Sonnet drafting,
this lands in the low single-digit rupees per day. The prefilter is what makes
that true: nothing reaches a model until it has already passed title, location
and freshness. Set SCREEN_PROVIDER=groq or gemini and it's free.
Use --limit while tuning filters so a bad regex can't run up a bill.