lenoben/jobhunter

This takes about 30–45 minutes the first time, and most of it is filling in your profile. You only need a terminal. Every command below is for PowerShell on Windows 10/11; where macOS or Linux differs, it says so.

Windows, not WSL. Run everything on Windows itself. The scheduled task, the Python core and the web UI all share one SQLite file, and SQLite locking is unreliable across the WSL/Windows boundary.

Step 1: Install the tools

Open PowerShell (Start menu → type PowerShell) and install what's missing:

| Tool | Why | Install | Check | |---|---|---|---| | Git | download the project | https://git-scm.com/download/win (the defaults are fine) | git --version | | uv | installs Python 3.12 and the dependencies for you | powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 \| iex" | uv --version | | Node.js LTS | the web UI | https://nodejs.org (the LTS button) | node --version | | Claude Code (recommended) | the AI that runs the search and writes your documents | https://claude.com/claude-code, then run claude once and log in with your Claude subscription | claude --version |

Close and reopen PowerShell after installing, so the new commands are found.

Don't want Claude Code? Skip it and get an API key from an OpenAI-compatible provider instead, for example Google Gemini or Groq (both have a free tier), OpenAI, OpenRouter or Mistral, or run a local model with Ollama. See Your setup, your choices for the trade-offs.

Never set ANTHROPIC_API_KEY. Claude Code runs on your subscription, and the run scripts remove that variable on purpose.

Step 2: Download JobHunter

Pick a folder for it (here D:\projekte), then:

cd D:\projekte
git clone https://github.com/lenoben/jobhunt.git jobhunter
cd jobhunter

Run all later commands inside this jobhunter folder.

Step 3: Install the dependencies

uv sync

This creates a private Python environment in .venv\ with everything JobHunter needs, including Typst for the PDFs. Nothing is installed system-wide. It takes a minute the first time.

Step 4: Get your passwords and keys ready

The setup wizard in the next step asks for these, so have them at hand. Only Telegram is required; skip whatever else you don't want.

• A mailbox for email drafts. For jobs that apply by email, JobHunter saves a ready email with your PDFs as a draft; it never sends anything. You need an app password, never your normal password:
  • Yahoo: https://login.yahoo.com/account/security → Generate app password;
  • Gmail: turn on 2-Step Verification, then https://myaccount.google.com/apppasswords;
  • GMX / web.de: enable IMAP in the mail settings (and use an app password if you have two-factor login).
• A mailbox with your job alerts. If you get LinkedIn or Instaffo job-alert emails, JobHunter can read them read-only: nothing is marked as read, deleted or moved. It can be the same mailbox as above or a different one, even with a different provider.
• Telegram (required): run summaries, jobs that need you and failed runs arrive there. Install Telegram on your phone and sign in. The wizard then walks you through creating a bot with @BotFather (/newbot, pick a name, copy the bot token).
• A Himalayas API key (optional, free at https://himalayas.app/api) for the remote-jobs board. Without one, JobHunter uses Himalayas' shared public allowance.
• An LLM API key, only if you chose another provider than Claude Code in Step 1.

Step 5: Run the setup wizard

uv run python cli.py setup

It asks one question at a time. The value in [brackets] is the default: press Enter to take it. Passwords and keys are typed hidden and never shown again. What it asks:

| Part | Question | What to answer | |---|---|---| | 1. Requirements | — | Shows ✓/✗ for Claude Code, Node, npm and Typst. Install anything marked ✗ that you need | | 2. Your files | — | Creates .env (your secrets) and profile/profile.yaml (your data) from the examples | | 3. AI | Provider | 1 for claude-code, or your provider's number | | | Models | Claude Code: Enter keeps haiku for scoring and sonnet for writing. Other providers: the wizard lists the provider's models; pick a fast, cheap one for searching/scoring and a strong one for writing | | 4. Countries | Countries | Numbers from the list or names, comma-separated, e.g. 2, 3, remote for USA, UK and remote jobs. Then the optional Himalayas key | | 5. Email | Save application emails as drafts? | y, then the address and the app password; or n | | | Read job alerts from | the drafts mailbox, another mailbox, or none | | 6. Telegram | Bot token | Paste the token from @BotFather. The wi

…