scout

A personal job-scouting system that runs on your own machine. It polls company job boards, reads every job description, scores each posting against your profile with evidence-checked AI judgment, and surfaces the handful worth your attention — on a local dashboard, in a morning digest, and as phone pushes for the rare posting that deserves one.

Built by a candidate who got burned by silent failures, so the design is paranoid in your favor: every decision must carry evidence. A disqualifying clause kills a posting only with the exact sentence stored as proof. A score cap applies only when its justifying quote is really in the job description. High scores are re-derived by a stronger model before they can page you. When any stage stops producing, the pipeline notices and tells you, loudly.

What it will never do

• Apply to anything, email anyone, or post anywhere on your behalf
• Scrape behind logins or bypass any access control
• Send your personal data anywhere except your own configured alerts
• Trust a model's claim it cannot verify against the posting's own text

What you need

• A Mac (macOS scheduling built in; Linux works with cron — see SETUP.md)
• Python 3.11+ and six small packages (pip install -e . installs them)
• The Claude Code CLI, signed in
• Cost honesty: with a Claude subscription (Pro/Max), scoring is covered by your plan and the system self-pauses at your usage window. With an API key instead, a full job-description read costs roughly $0.05–0.08; a 2,000-posting first backlog is real money (~$100–160). The quota command shows a running notional total either way.

The five-minute version

git clone https://github.com/ammarphp/scout scout && cd scout
python3 -m scout.cli interview --resume my_resume.txt
python3 -m scout.cli validate
python3 -m scout.cli seed --probe
python3 -m scout.cli poll
python3 -m scout.cli sched install   # 6 polls/day + digest + health checks

Your entire identity lives in one folder: candidate/ — eight plain files you can read and edit (your story, your deal-breakers, your scoring rules, your targets, your resume variants, your company list). The engine reads that folder and nothing else; it ships with a complete fictional example (candidate-example/) that boots out of the box.

Setting up with an AI assistant: hand SETUP.md to Claude, ChatGPT, or any capable assistant with terminal access and say "set this up for me." It is written to be executed step by step, with a verification after every step. Your own resume and answers are the only parts it will need from you.

Documentation

• SETUP.md — step-by-step install, written for humans and AI assistants
• ARCHITECTURE.md — how the pipeline works and why it is built this way
• docs/ — deeper operational notes

Respect for the sites it reads

scout reads only public, unauthenticated job-board APIs (the same JSON your browser fetches), at most one request per second per host, with honest caching. It never scrapes behind a login. If an ATS vendor objects to access patterns, open an issue. This project is not affiliated with any ATS vendor, job board, or employer, and comes with no warranty; see LICENSE.

Privacy

Everything stays on your machine: the database, your profile, every score. The only optional outbound surfaces are the ones you configure — ntfy pushes, your own SMTP digest, and an optional heartbeat gist with a strict redaction list.