🎯 The Problem
Job hunting on LinkedIn is a job in itself. Open the search, read twenty postings where fifteen don’t apply, tailor your CV for the ones that do, write a different message for every recruiter, and repeat it all the next day. It’s exactly the kind of manual, repetitive process I automate for companies, so I decided to automate it for myself.
That’s how jobhunter was born, an open source Python CLI that today has stars, forks and real users filing issues on GitHub. This post is the case study of how it works under the hood.
🤖 The Architecture, a 4-Agent Pipeline
The heart of the system isn’t one giant prompt but four specialized agents passing work down a chain, each with a clear responsibility.
- Filter agent. Analyzes every scraped posting and decides whether it’s relevant to your profile, extracting structured data (role, stack, work mode, company). It has the biggest impact on the quality of everything downstream.
- CV Writer. Generates a CV tailored to each relevant offer with ReportLab, highlighting the experience that specific vacancy asks for.
- Email Writer. Writes the recruiter message in about 100 words. Short, specific, and free of generic templates.
- Optimizer. Learns from each run and adjusts the search query based on your profile and results history.
Scraping uses Playwright with persistent sessions to avoid re-authenticating on every run, and delivery goes through Gmail SMTP with TLS.
⚖️ The Decisions That Mattered Most
The human approves, the agent prepares. The most important design decision wasn’t technical but product. jobhunter has a dry-run mode and everything ends in a human review before anything is sent. An agent that blindly applies on your behalf is spam with extra steps. An agent that leaves you six applications ready to review turns an hour of repetitive work into five minutes of judgment.
Deterministic filters before AI. Company blacklists, deduplication of already-seen offers and time filters run before spending a single token. The LLM only sees what’s worth analyzing, and that keeps the cost per run in cents.
Pick the model per task. The user chooses which Gemini model to use (flash, lite or pro). Filtering hundreds of postings doesn’t need the most expensive model; writing the CV does benefit from a better one. It’s the same cost-optimization lesson I apply in production.
📬 What Happened When I Published It
Releasing it as open source under MIT changed the project. Users arrived running it on operating systems I had never tested, issues came in with cases I hadn’t imagined, and forks adapted it to other countries. Maintaining it forced me into what no private project demands, CI with GitHub Actions, pre-commit hooks, installation docs for three platforms, and saying no to features that don’t fit.
The most valuable lesson wasn’t technical. It was discovering that maintaining a tool other people use is a different skill from building it.
🔭 What’s Next
The next step is publishing the Filter agent’s evaluation harness, a hand-labeled golden set of job postings to measure with numbers how well it classifies relevance, wired into CI. If the most critical agent in the pipeline can’t be measured, it can’t be improved.
The code lives at github.com/dev-gaspar/jobhunter and the full docs on the project landing page. If you try it, an issue with your experience is worth gold.