JobHunter — a multi-agent assistant for remote job hunting

A system of agents that discovers remote job postings, scores them against your profile and writes tailored materials for each one — while the decision to hit send always stays with the human.

Built for a concrete problem: hunting for international remote work from Latin America, where the real obstacle isn't your profile, it's information. The market advertises "LatAm friendly" far more generously than it can actually hire.

---

The problem it solves

Over a real run of 3,571 job postings, the system found 199 in the target role. Many of those said they accepted LatAm but required residency in one specific country:

Job posting	Looked like	Reality
Fintech, $5,000–8,000/month band	"LatAm"	"Are you authorized to work lawfully in Mexico?"
Global board, 84/100 match	"Anywhere in the World"	Generic board label; the company hires in 6 countries, none of them in LatAm
Communications company	"Remote"	"This role will be remote, and based in Colombia"

19 of 30 rejections came down to that. The filter that matters isn't the skills match, it's "can this company legally hire me?"

So the system leans on sources that declare eligibility by country, and verifies the rest before spending time on an application.

---

Architecture

The profile is the hub, not a pipeline stage: every agent reads from it.

STRATEGY (periodic)      COACH ⇄ PROFILE

OPERATIONS (daily)
   SCOUT ────► EVALUATOR ──► WRITER ───► APPLIER* ───► TRACKING
   discovers   scores vs.    CV + letter human         records
   and dedupes profile       per posting reviews/sends outcomes

FEEDBACK
   TRACKING ──insights──► EVALUATOR   (re-prioritizes what converts)
                      ├─► WRITER      (repeats winning angles)
                      └─► COACH ───► updates PROFILE

   (*human-in-the-loop: the system prepares everything; the person makes the final click)

Six specialized agents, each with a clean context and a single folder it may write to:

Agent	Role	Writes to
profile	Source of truth; ingests the CV, interviews the user, keeps the Q&A dictionary	profile/, knowledge/
scout	Discovers postings from APIs and feeds, normalizes and dedupes	pipeline/1-scout/
evaluator	Scores against the profile; classifies eligibility and time-zone overlap	pipeline/2-evaluator/
writer	CV and cover letter per posting; never invents	drafts/
coach	Skill gaps vs. the market, backed by evidence from the scored postings	coach/
analyst	Funnel metrics → insights.md, which feeds back into the others	tracking/

Handoffs happen through files, not through ephemeral context: every stage leaves its output and a log.md. That makes the system auditable — open any folder and you can see what each agent did and why.

---

Design decisions

Human-in-the-loop, not auto-submit. The system fully automates discovering, scoring and writing; the person makes the final click. The reasons: tailored applications convert 2–5× better than generic ones (~7–9% vs ~2–3% interview rate), bulk auto-submission violates the ToS of the big platforms, and CAPTCHAs block it anyway. Same time saved, better outcome, no risk of a banned account.

Verified eligibility beats score. A perfect-match posting from a company that can't hire you is worth zero. The evaluator classifies each one green/yellow/red and demands evidence for green.

Time-zone overlap, not geography. Nothing is dropped for being in the wrong country — only for lacking real synchronous overlap. An async-first European role can work; one with a daily stand-up at 10 AM CET can't, if that's 4 AM where you are.

Honesty is structural. The system has hard rules it cannot break: it never invents experience or tools, never inflates language levels, never fakes a location. That isn't only ethics — a KYC mismatch freezes your payment after you've done the work, and an invented tool falls apart in the first sprint.

---

Job sources

With an official API or feed (integrated): Remotive · Remote OK · We Work Remotely (RSS) · Arbeitnow · Jobicy · Himalayas · Get on Board · corporate ATSs (Greenhouse, Lever, Ashby).

⭐ Get on Board is the most valuable one here: it declares, per posting, which countries the company can hire in. That kills the false positive before you apply.

No API — a decision tree, from least to most intrusive:

1. Look for a "hidden" feed (RSS, sitemap.xml, an internal JSON endpoint, an ATS behind the site)
2. Email alerts → parse them (zero scraping, zero friction with the ToS)
3. Respectful public reading, only if robots.txt and the Terms allow it
4. Assisted manual capture for anti-bot sites

Good-citizen rules: check robots.txt and the Terms before reading; store only metadata and the link; at most one run per day per source; never automate behind a login or work around a CAPTCHA. See docs/job-sources.md.

---

Usage

Requires Claude Code and Python 3.9+. No external dependencies: the scripts use only the standard library, and PDFs are rendered by the Chrome you already have.

# 1. Discover job postings
python scripts/fetch_jobs.py

# 2. Narrow the run down to postings that can actually hire you
python scripts/filter_candidates.py

# 3. Turn the markdown drafts into PDFs
python scripts/md_to_html_cv.py && python scripts/make_pdfs.py

Inside Claude Code:

Command	What it does
/run-day	Daily cycle: discover → score → write → digest
/review	Walks the digest with you and assists the applications (you approve and send)
/coach	Skill-gap analysis against the market
/stats	Funnel metrics: which platforms and roles convert

Setup

1. Drop your CV and supporting material into profile/materials/
2. Run the profile agent to build your master profile and preferences
3. Add your target companies to platforms/target-companies.json (their ATS token)
4. Replace the [YOUR CITY], [YOUR COUNTRY] and [YOUR NAME] placeholders in the agents with your own details

Privacy note: this repository holds the architecture and the tooling, not personal data. The profile, the drafts and the tracking data are generated locally and should not be published — they contain your CV, credentials, salary expectations and live applications. The .gitignore excludes them.

---

Layout

scripts/          fetch_jobs.py · filter_candidates.py · md_to_html_cv.py · make_pdfs.py
.claude/agents/   the six specialized agents
.claude/commands/ /run-day · /review · /coach · /stats
docs/             the source registry and the LatAm platform guide

Generated locally and kept out of the repo: profile/, knowledge/, pipeline/, drafts/, tracking/, coach/, digests/.

---

License

MIT