Job hunting is repetitive work. Job Hunter automates the parts that don't need you: scraping listings across major job boards, scoring each one against your profile, tailoring your resume per application, and drafting cover letters. You handle the conversations.
Works interactively inside Claude Code or Codex (VS Code extensions), or runs fully autonomous via LLM API for unattended pipelines and GitHub Actions.
- Discovers jobs across supported job boards, aggregators, and company career pages — filtered by your titles, regions, and exclusions
- Scores each listing against your career context so you know what to prioritize
- Tailors your resume per job and generates a cover letter, ready for PDF export
- Tracks applications with a dashboard and analytics so nothing slips through
Windows/macOS, no terminal: download the installer from the latest release, run it, and the dashboard opens. Unsigned — Windows SmartScreen and macOS Gatekeeper require an extra click through on first run (see SETUP.md).
Any OS, via terminal — requires Python 3.12 or 3.13:
uv tool install job-hunter-kitStandard install supports both agent and llm-api modes. See the complete
beginner-friendly SETUP.md for
PATH troubleshooting, API-key links, and agent permissions.
Once installed, updates are one click in the dashboard (job-hunter dash →
"Update now") — no terminal needed for either install path.
job-hunter init my-workspace
cd my-workspace
job-hunter doctorOpen the workspace in VS Code with Claude Code or Codex, then run /setup onboard, /setup context, /setup stories, and /setup resume. job-hunter doctor validates config and reports exact fixes.
| Mode | What runs | When to use |
|---|---|---|
agent |
Python prepares context; Claude Code or Codex (VS Code) skills handle scoring, tailoring, and writing | Interactive daily review |
llm-api |
Full autonomous pipeline; LLM APIs called inside Python | Unattended runs and GitHub Actions |
Set mode: in config/job_hunter.yml. Default is agent.
job-hunter hunt --region primary
job-hunter dash # desktop appIn agent mode, open the workspace in VS Code with Claude Code or Codex and use:
/job-hunter batch
/job-hunter one <url>
/job-hunter finalize
In llm-api mode, job-hunter hunt runs scrape → score → tailor → cover letter → PDF → tracker in one pipeline.
- Run
job-hunter dash, open onboarding, and enable Student mode. - Choose target roles and locations; internships, working-student roles, thesis positions, graduate programs, and trainee roles are selected automatically.
- Run
job-hunter hunt, then review the posting-type-filtered Candidates feed.
Student scoring emphasizes verified education, coursework, projects, internships, and transferable skills. Posting types and the automatic score threshold remain editable.
- Run
job-hunter dash, open onboarding, and enable Include startups. - Choose regions and titles; Startup.jobs, Y Combinator Jobs, Start Munich (Germany), and up to 100 verified package startups per enabled country join discovery.
- Run
job-hunter hunt, then filter Candidates by the startup or scaleup chip.
For company career pages that need a real browser, add your own companies or
opt in to the shared catalog in the Company Hunt tab's Manage Companies
view in job-hunter dash, then click Run Company Hunt. Results land in
outputs/state/jobs.db, the same store the normal hunt uses.
The native web dashboard includes Settings, Companies, paginated Applications and Candidates, Company Hunt (its own top-level tab), Insights, and Analytics. Settings and Companies use revision-guarded saves with one-level Undo. Company Hunt is one button — it continues an interrupted run automatically, otherwise checks whatever's new or changed; recent successful pages are skipped by default and every company result is persisted immediately. Bundled catalog companies (Manage Companies → Shared Catalog) are opt-in per company or per sector; companies you add yourself stay enabled by default.
job-hunter init <workspace>— create a workspacejob-hunter doctor— check setup healthjob-hunter hunt— discover and enrich jobsjob-hunter tailor— tailor resume for one or more job postingsjob-hunter finalize— validate and commit durable outputs (README, config, profile, job/LinkedIn outputs, jobs.db);--pushto also push. Same action as the dashboard's Finalize buttonjob-hunter dash— open the desktop app in a native window (Applications, Insights, Analytics)job-hunter applications update <job> <status>— update an application's lifecycle status from a scriptjob-hunter hunt --from-db-candidates— process pending company-hunt candidates inllm-apimodejob-hunter update— update workspace assets, skills, and workflows after a package upgradejob-hunter update --skills-onlyor--workflows-only— targeted refreshjob-hunter version— version and upgrade guidance
Bundled skills use hidden job-hunter internal ... commands. They are not part of normal user workflow.
Your data stays yours. Product updates must not overwrite config/, profile/, outputs/, or .env. Deterministic choices live in config/job_hunter.yml; career and writing guidance lives in profile/career_context.md; all job and application state lives in outputs/state/jobs.db.
See DATA_CONTRACT.md for the full contract.
Job Hunter never submits applications, posts on LinkedIn, or contacts anyone automatically. It writes files under outputs/ for you to review. job-hunter finalize and job-hunter update only touch system-owned paths — see the data contract above.
uv sync --extra dev
uv run pytest tests/ -q --tb=short
uv run ruff format --check job_hunter tests scripts
uv run ruff check job_hunter tests scripts
uv run ty check job_hunter tests
uv buildMIT licensed. See CONTRIBUTING.md.
- docs/architecture.md — package structure and module boundaries
- DATA_CONTRACT.md — user vs. system-owned files
- docs/config.md — every
config/job_hunter.ymlkey - docs/sources.md — job boards, career pages, search providers
- docs/agent-mode.md — how agent mode works
- docs/llm-api-mode.md — how LLM API mode works
- docs/workspace-updates.md — what
job-hunter updatedoes - docs/testing.md — running and writing tests
- CONTRIBUTING.md — contributor guide
Job Hunter is the evolution of a single experiment: job-hunter-core and job-hunter-template worked as one system to prove the pipeline, the workspace model, and the agent skill layer — everything this package ships today.