Job Hunt Agent

An agentic job-search system built in Claude Code, where the rules the
agent must follow are checks in code, not sentences in a prompt. It
tailors a one-page resume to each job description, scores fit on an
auditable rubric, scrapes postings, drafts recruiter emails (never sends
them), and tracks every application through to an outcome on a dashboard.

Run it inside Claude Code. On first use the agent interviews you once
to build a reusable "base template" from your real experience. After that,
paste a job description and get a tailored, ATS-checked one-page PDF back.

Why it is built this way

Most "AI resume" tools optimise for generating text. This one optimises for
not shipping a mistake, because a fabricated bullet or a two-page resume
sent to a real employer cannot be recalled. The design rules that follow
came from real failures during the author's own run, each turned
into a mechanical check the moment it happened. The full list is in
docs/05_DESIGN_DECISIONS.md.

• Guardrails as code. A resume is "done" only when verify_resume.py
  passes: one page, no dashes, enough real content, no unheld title claim,
  ATS-parseable, no ligature glyphs. The agent cannot mark work finished by
  saying so.
• Provenance over trust. Every bullet in a built resume must trace to a
  phrase that literally appears in the candidate's source files. In the
  author's build the builder refuses to compile otherwise; this template
  ships the rule and the PDF verifier, and the provenance check is the first
  item on the porting list in docs/06_FEATURES.md.
  "Never invent a bullet" is meant to be a check, not a rule to remember.
• Two scores, never blended. fit measures how well the background
  matches the JD; odds measures the chance of clearing that employer's
  screen. A wide gap means "apply via referral", not "skip".
• Score what you actually read. Scored on a stub JD, roles looked
  better than on the full posting (the less the agent knew, the higher it
  scored). Fit is now capped by how much JD text existed at scoring time,
  and the cap lifts automatically when the real posting is recovered.
• Human in the loop where it matters. The agent drafts emails; the user
  sends. The agent builds resumes; the user approves from a phone. Nothing
  outbound happens without a person pressing the button.
• Measured on outcomes, not activity. The scoreboard's North Star is
  interviews per ten applications, with cohorts by score band, employer tier
  and channel, and a validation test that refuses to draw a conclusion
  under 25 resolved applications.

Features at a glance

The full list, with a status for each (ships in this repo, operating rule,
or documented from the author's build), is in
docs/06_FEATURES.md. The short version:

Beyond the shipped set, the author's build adds a validation gate on every
status transition, JD-quality caps on fit, employer-tier odds adjustments,
Gmail-alert discovery with queue caps and a 7-day no-JD clock, a location
taxonomy module, ghost-job signals, an outcome tracker that reads employer
replies, a scoreboard whose only North Star is interviews per ten
applications, pending-action deadlines, a health check and per-run tracing.
Each is described in the features doc with the order that worked for
porting them.

What you get

• A locked one-page HTML/PDF resume template (templates/resume_base.html).
  Layout and CSS never change; only the content does.
• A bullet-library + per-job-spec model (scripts/build_resume.py,
  scripts/resume_specs.py). Tailoring = selecting, ordering and rephrasing
  your real bullets toward a JD's own words. Nothing fabricated.
• A mechanical QA gate (scripts/verify_resume.py): fails a resume for
  more than one page, em/en dashes, too few bullets, too thin, banned
  filler, an unheld job-title claim, unverified [estimate] markers,
  non-ATS-parseable layout, or ligature glyphs that break literal keyword
  matching.
• A one-page PDF compiler with auto-fit (scripts/compile_pdf.py).
• An onboarding interview (ONBOARDING.md) the agent runs to set this
  up from your existing resume, then asks about salary, roles and locations.
• A fit-check rubric the agent scores each JD against before tailoring,
  recorded on the job with scripts/score.py (fit vs. odds, plus a
  re-derivable breakdown).

Optional pipeline (no keys needed to start)

• A job scraper (scripts/scrape.py) that pulls postings from public
  Greenhouse / Lever / Ashby boards, filtered by your title and location
  keywords. No API key.
• A local tracker (scripts/track.py, SQLite) that every other piece
  reads from and writes to.
• Gmail draft creation for recruiter outreach (scripts/gmail_auth.py)
  — drafts only, it never sends.
• A Telegram digest of your review queue (scripts/telegram_setup.py).
• A web approval dashboard (dashboard_app/, Supabase + Vercel) —
  Approve / Pass / Mark-applied from your phone, synced back to the tracker.
• Setup guides for every key, one step at a time
  (docs/01_SETUP_API_KEYS.md).

Optional interview prep

• An interview-prep report generator (docs/04_INTERVIEW_PREP_GUIDE.md):
  when you have an interview booked, the agent researches the company,
  rebuilds every candidate claim from your real profile, and compiles a
  thorough prep PDF - resume walkthrough, STAR stories, domain frameworks,
  a company and competitor deep dive, likely questions with answer frames,
  and a strategic teardown. Every fact carries a confidence badge.

Quick start

1. Install prerequisites:

   • Python 3.10+
   • Google Chrome (used to render the PDF)

   pip install -r requirements.txt
   

2. Copy the config templates:

   cp config/profile.example.json config/profile.json
   cp config/resume_rules.example.json config/resume_rules.json
   

3. Open this folder in Claude Code and say:

   "Set up my base resume."

   The agent follows ONBOARDING.md: asks for your current resume (or
   interviews you from scratch), fills the template, builds your bullet
   library, then asks about current/expected salary, notice period, target
   roles and preferred locations.

4. After onboarding, paste any job description and say "tailor my resume
   for this."

5. (Optional) Turn on tracking and discovery:

   python scripts/track.py init
   cp config/job_sources.example.json config/job_sources.json   # edit companies + keywords
   python scripts/scrape.py --dry-run
   

   See docs/03_PIPELINE_OVERVIEW.md, then docs/01_SETUP_API_KEYS.md for
   Telegram / Gmail / the dashboard.

Files map

Privacy

.gitignore excludes everything with real personal data: config/*.json
(except .example. templates), candidate_profile/* (except examples),
data/, resumes/, cover_letters/, JDs/, and all API credentials.
Before pushing, run git status and confirm none of the real files are
staged.