🚀 AI career intelligence: understands your career, finds roles that genuinely fit, explains every match, and prepares honest application material

Upload your resume once. Press search. Go grab a coffee. ☕ JobHunterX reads your resume, finds real jobs that truly fit you, tells you why each one fits (or doesn't), writes an honest one-page resume, a cover letter and a CV for you — and then a browser agent fills the application live, right inside the app, while you watch. Stuck on a CAPTCHA or a login? Just take over, fix it, and hand it back. 🙌 💜 The job-hunting buddy you always wished you had. 💜

🇮🇳 Built for Indian job seekers

JobHunterX is made for people like this: 1–3 years of experience, living in South India (Hyderabad / Bengaluru first), who can't move North or abroad for a job.

The real problem it solves: a public LinkedIn / Naukri / Indeed post now gets hundreds to thousands of applicants within days. Recruiters read the first few dozen and filter on years, current company and notice period. With 1–2 years of experience you are filtered out unread — your skills never reach a human. So "apply to more jobs" does not work. Being seen early, on the right channel, does.

[!NOTE] The watchlist covers Hyderabad, Bengaluru and remote-India today. More South Indian cities (Chennai, Kochi, Coimbatore, Vizag…) come next. The research lives in jobhunterx/jobhunterx/watchlist/companies.json.

🗺️ The whole journey

Everything happens in this order — the sidebar is ordered the same way. 👇

flowchart LR
    K(["🔑 Free AI key<br/><sub>first screen</sub>"]) --> A(["📄 Upload resume<br/><sub>once</sub>"])
    A --> B["🙋 Check what<br/>we understood"]
    B --> C["🎯 Your goals<br/><sub>titles · cities · remote · CTC</sub>"]
    C --> D["🔎 Search + watchlist<br/><sub>real live progress</sub>"]
    D --> E["⭐ Pick a job<br/><sub>see why it fits</sub>"]
    E --> F["📝 Documents<br/><sub>resume · letter · CV</sub>"]
    F --> G["🤖 Auto-apply<br/><sub>live in the app</sub>"]
    G -->|"CAPTCHA / login"| H["🙌 You take over"]
    H -->|"give back"| G
    G --> I(["🎉 Applied!<br/><sub>tracked for you</sub>"])

    classDef start fill:#EE6B33,stroke:#c4501d,color:#fff,stroke-width:2px;
    classDef step fill:#fff7f2,stroke:#EE6B33,color:#1f1f24,stroke-width:1.5px;
    classDef agent fill:#1f1f24,stroke:#1f1f24,color:#fff,stroke-width:2px;
    classDef you fill:#fde9b8,stroke:#c4860f,color:#1f1f24,stroke-width:1.5px;
    classDef done fill:#2f9a68,stroke:#21754f,color:#fff,stroke-width:2px;
    class K,A start; class B,C,D,E,F step; class G agent; class H you; class I done;

📸 A tour, step by step

0 · First run: one free AI key 🔑

_{No key yet? Press Start free to use Kilo's free models right away, or get a free key: the screen shows where, tests it with one call and saves it to .env. Placeholder values never count as a key.}

1 · Who's searching? 👥

_{Several people (or personas) can use one install — each profile keeps its own resume, matches, tracker and documents.}

2 · Upload your resume — only once 📄

_{A short 5-step setup: resume → about you → goals → pay & availability → first search. Reload any time; it remembers where you were.}

3 · "Here's how we see you" 🙋

_{Experience is calculated from your dates — total, professional only, and internships — so the numbers are never guessed.}

4 · Search, live 🔎

_{Real progress only: the bar and the text move with real counts the server reports — "Web searches: 7 of 15", "Company job boards: 21 of 33", "Jobs analysed: 3 of 20 · reading 'AI Engineer' at …". Nothing is estimated from time.}

5 · Why this score? ⭐

_{Click a job and it opens beside the list: hard requirements, the weighted score, requirements, verification and the application kit.}

5b · Chance to be seen + what the company is like 📡

_{Every signal is listed with its points: how fresh the post is, which channel it is on, applicant counts (only when the page shows one), email routes, notice period, competition — plus the researched company card.}

5c · Companies to watch 🏢

_{The researched watchlist for your cities: verdict, competition, early-career hiring, ratings, red flags. "Check for new roles now" shows the check live, step by step.}

6 · Honest documents 📝

_{Every AI edit is fact-checked against your profile. "What changed" shows each edit — accepted or rejected, and why.}

7 · Auto-apply: documents first ✅

_{Before the browser opens, the kit is checked: resume (one page), cover letter and CV. Anything missing is written right then.}

8 · Auto-apply: watch it work, live 🤖

_{No extra Chrome window — the browser is streamed into the app. Every step is listed in plain words, with what was clicked and typed.}

9 · When it needs you 🙌

_{CAPTCHA or login? Take over, click and type right in the view, then press Continue. Progress is saved, so nothing starts over.}

10 · Track everything 📊

_{The whole journey in one stage bar, one-click "next stage", and the job beside the list — no sideways scrolling.}

11 · Your profile, your settings ⚙️

_{Turn providers on/off, add keys (loaded from .env), pick a model per task, choose which documents Auto-apply attaches.}

12 · Dark mode & phones 🌙📱

_{One click for dark mode. On phones the sidebar becomes a floating bottom bar.}

🤖 Auto-apply — the browser agent

Press Auto-apply on any job and three things happen, in this order:

flowchart TD
    S(["▶️ Auto-apply"]) --> K{"📂 Check the kit"}
    K -->|"resume missing?"| R["✍️ Write a one-page resume"]
    K -->|"cover letter missing?"| L["✍️ Write a cover letter"]
    K -->|"CV missing?"| V["✍️ Write the CV"]
    K -->|"all ready"| O
    R --> O
    L --> O
    V --> O
    O["🌐 Open a private browser<br/><sub>streamed into the app</sub>"] --> F["⌨️ Fill the form<br/><sub>step by step</sub>"]
    F -->|"submitted"| A(["🎉 Applied"])
    F -->|"CAPTCHA · login · code"| N["🙌 Needs you"]
    F -->|"⏹ you press Stop"| X["⏸ Stopped — progress saved"]
    N -->|"take over, then Continue"| F
    X -->|"Continue"| F

    classDef go fill:#EE6B33,stroke:#c4501d,color:#fff;
    classDef kit fill:#fff7f2,stroke:#EE6B33,color:#1f1f24;
    classDef run fill:#1f1f24,stroke:#1f1f24,color:#fff;
    classDef wait fill:#fde9b8,stroke:#c4860f,color:#1f1f24;
    classDef ok fill:#2f9a68,stroke:#21754f,color:#fff;
    class S go; class K,R,L,V kit; class O,F run; class N,X wait; class A ok;

Why it feels calm and clean ✨

• 🪟 No separate Chrome window. The page is streamed with Chrome's own screencast into the Auto-apply tab. (Want a real window for debugging? Settings → Auto-apply → Also show a separate Chrome window.)
• 🧾 Readable steps. Each step shows the goal in plain words ("Fill in email and phone") with small chips for what was done ("Type … into Email", "Upload Asha_Rao_Resume.pdf"). Repeats are counted (×2) instead of listed again.
• 🧵 One owner for the browser. The agent, the live view and your clicks all run on one dedicated browser thread, so they never fight over the connection (this fixed the old "navigation timed out" and "duplicate response" errors).
• 💾 Saved state. Status, the kit, every step and the last page are stored in the database — reload the app, restart it, or switch tabs and pick up right where you were.
• 🐢 Polite pacing. A small pause between steps looks human and keeps you inside free AI limits (BROWSER_STEP_DELAY_S).

🧠 How matching works

JobHunterX does not just count shared keywords. It understands you, finds and checks real postings, reads each job, and explains whether it genuinely fits.

Example: one candidate, five jobs

Candidate: ~1.5 years professional AI/ML experience, Hyderabad, not relocating.

This exact scenario runs in the test suite (tests/test_scenarios.py).

📡 Chance to be seen (reach)

Fit answers "am I right for this job?". Reach answers "will a person actually read my application?". It is shown next to fit and never mixed into the fit score. Every signal is shown with its reason:

The default sort, Best chance, ranks by fit and reach together. You can also sort by Best fit or Least crowded.

📄 Resume vs CV vs cover letter

They are three different documents — JobHunterX makes all three, and Auto-apply checks for them before it starts.

🔗 Links stay where they belong: when your resume PDF is read, every link is kept together with the text on it ("Code", "Live demo", "Verify") and the lines around it. So a project keeps its GitHub and demo links, a certificate keeps its credential link, and blog / Kaggle-style profiles go to the header. In the resume and CV they show up as small clickable labels next to the right project or entry — nothing extra, no long raw URLs. You can edit them in Profile.

✅ Nothing invented: every AI-written line is fact-checked (generation/evidence.py). A new number, tool, employer or claim that isn't in your profile is rejected and your own words are kept.

🤖 LLM Models & Provider Architecture

One router (config/llm_router.py) sends every AI call through a task chain: the first usable model answers, and the next one takes over if it is busy, rate limited, turned off or not on your account. The model catalog, chains and free-tier limits live in config/models.py.

graph LR
    subgraph Google["☁️ Google AI Studio"]
        G1["gemma-4-31b-it"]
        G2["gemini-3.5-flash-lite"]
    end
    subgraph Groq["⚡ Groq"]
        GR1["openai/gpt-oss-120b"]
        GR2["moonshotai/kimi-k2-instruct-0905"]
        GR3["qwen/qwen3.6-27b"]
        GR4["openai/gpt-oss-20b"]
    end
    subgraph Mistral["🌀 Mistral"]
        M1["mistral-medium-latest"]
        M2["mistral-small-latest"]
    end
    subgraph Kilo["🆓 Kilo Gateway (no key)"]
        K1["kilo-auto/free"]
        K2["nemotron-3-super-120b:free"]
        K3["laguna-s-2.1:free"]
    end
    subgraph NIM["🟩 NVIDIA NIM"]
        N1["nemotron-nano-3-30b-a3b"]
        N2["glm-5.3-flash"]
        N3["deepseek-v4.1-flash"]
    end
    G2 -->|fallback| K1 -->|fallback| N1 -->|fallback| G1 -->|fallback| GR1 -->|fallback| M1

    classDef google fill:#4285F4,stroke:#1a73e8,color:#fff,stroke-width:2px;
    classDef groq fill:#F55036,stroke:#c9302c,color:#fff,stroke-width:2px;
    classDef mistral fill:#FF7000,stroke:#cc5a00,color:#fff,stroke-width:2px;
    classDef kilo fill:#8B5CF6,stroke:#6d28d9,color:#fff,stroke-width:2px;
    classDef nim fill:#76B900,stroke:#5a8f00,color:#fff,stroke-width:2px;
    class K1,K2,K3 kilo;
    class N1,N2,N3 nim;
    class G1,G2 google;
    class GR1,GR2,GR3,GR4 groq;
    class M1,M2 mistral;

Task chains

Kilo comes before NVIDIA NIM on purpose: it needs no key and each Kilo model has its own 200 requests/hour, while NIM's 40 requests/minute is shared by every NIM model on your account. Kilo's free models are "thinking" models; the app turns their thinking off (reasoning: {enabled: false}) — in tests that made them answer in about 1–3 s instead of running out of room before the answer. If a model still returns an empty answer, it gets one retry with more room and is never "rested" for it.

[!WARNING] Privacy: Kilo's free models are marked may train on your prompts. Your resume text and job posts are sent in those prompts. If that matters to you, add any free key (Google, NVIDIA, Groq or Mistral) and turn Kilo off in Settings → AI providers.

Llama models are deliberately not used. In Settings → AI providers you can turn any provider off, add or replace its key, pick the first model for each task, and press Check available models — the app asks each provider's /models endpoint with your key and skips models your account cannot call.

💳 Free-tier limits the router respects

Each model gets its own limiter: requests are spaced to its RPM, a rolling one-minute window keeps it under TPM, and daily RPD / TPD counters stop using it for the day once spent (the chain moves on). A 429 also puts the provider in a short cooldown. Override any number with MODEL_LIMITS_JSON in .env, e.g. MODEL_LIMITS_JSON={"gemini/gemma-4-31b-it": {"rpm": 30, "rpd": 14400}} — limits differ per account and change often.

[!NOTE] Why you may see 500 INTERNAL or 503 high demand from Gemma: those come from Google's servers. In live tests (Oct 2026) the free Gemma 4 31B endpoint took 12–120 s per answer and often refused larger prompts, while Gemini 3.5 Flash Lite answered in about 1–5 s. So Flash Lite is now the first choice for every task and Gemma 4 31B is the first backup. When Gemma fails it gets one quick retry, then the app moves on and Gemma rests for 2 minutes (4, 8… up to 30 if it keeps failing). Settings → AI providers shows "resting N min". A Gemma call never waits more than GEMMA_TIMEOUT_S (90 s). Resume upload runs in the background with live progress, so a slow free-tier call never times out the page.

🌐 Job Sources & Verification

🔎 Deep Search — good results without any search key

Paid search APIs like Tavily and Exa do three things one free scraper does not: they ask several indexes, they read the pages, and they rank by meaning. Deep Search (tools/deep_search.py) does the same with free parts:

1. Ask many engines at once — Bing, Yandex, Google and Brave (through Mullvad's proxies), Yahoo and DuckDuckGo. An engine that keeps failing is rested for 10 minutes instead of slowing every query.
2. Merge — results are combined with reciprocal-rank fusion (a page several engines agree on rises). Employer job pages get a boost (a single ATS posting 1.6×, a company job board 1.4×, a careers page 1.25×); aggregators are lowered and people-lookup sites (RocketReach, ZoomInfo…) are pushed out.
3. Open the pages — the best careers / listing pages are opened and mined for links to the employer's own job board and individual postings (Greenhouse, Lever, Ashby, Workday, Keka…). One careers page can become many real postings.
4. Rank by meaning — the AI scores the top 20 for "is this a real, open posting that matches the search?" (it uses Kilo's free models when you have no key).

Search queries now run 3 at a time, so a full search finishes much faster than one by one.

Search providers are tried in priority order (primary first, DuckDuckGo last) with zero-spend protection (tools/zero_spend.py) and a usage ledger. All fetching of untrusted URLs goes through an SSRF-safe client (discovery/net.py: public addresses only, checked on every redirect, size and time limits).

🎨 Design: fonts & themes

⚡ Quickstart

🚀 One command (recommended)

Get the code, then run one command. It does everything for you: installs uv, makes the virtual environment, installs all packages (~30 seconds), creates the settings file, starts the app and opens it in your browser.

git clone https://github.com/kvcops/jobhunterx.git
cd jobhunterx

The first screen asks for a free AI key and shows where to get it. That's it. 🎉

Next time: run the same command (or double-click start.bat again). It skips the setup and just starts the app. Stop the app: press Ctrl + C in that window.

What you need

• 🌐 Internet for the first setup
• 🌐 Google Chrome, used by Auto-apply
• 🔑 One free AI key — Google AI Studio is the easiest (get it here)

You don't need to install Python yourself — uv downloads Python 3.11 if it's missing.

git clone https://github.com/kvcops/jobhunterx.git
cd jobhunterx

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

curl -LsSf https://astral.sh/uv/install.sh | sh

uv venv --python 3.11

uv pip install -r requirements.txt

# Windows
copy jobhunterx\.env.example jobhunterx\.env
# macOS / Linux
cp jobhunterx/.env.example jobhunterx/.env

GOOGLE_API_KEY=paste-your-key-here     # free — start with this one
NVIDIA_API_KEY=                        # optional — 40 requests/min, fast small models
GROQ_API_KEY=                          # optional — makes it faster
MISTRAL_API_KEY=                       # optional — backup

cd jobhunterx
python -m jobhunterx.api.main

🆘 If something goes wrong

⚙️ Handy settings (.env or Settings page)

📐 Architecture

jobhunterx/jobhunterx/
├── domain/          # 📦 Data contracts: profile, snapshot, job posting, match, document
├── intelligence/    # 🧠 Understanding + judgement (candidate, job, matching, reach, policy)
├── discovery/       # 🔎 Search, ATS adapters (incl. Workday, Keka), watchlist, page parsing, dedupe, validation, SSRF-safe fetch
├── watchlist/       # 🏢 companies.json — the researched company watchlist (Hyderabad, Bengaluru, remote India)
├── generation/      # 📝 Resume / CV / cover letter + fact-checking + one-page PDF rendering
├── services/        # 🧩 Orchestration: search runs, watchlist watcher, jobs, documents, profiles, auto-apply kit
├── agents/
│   ├── browser_agent.py   # 🤖 Auto-apply session: steps, stop / take over / continue / close
│   ├── browser_worker.py  # 🧵 One long-lived thread that owns the browser
│   └── live_view.py       # 📺 Chrome screencast → the app, your clicks → the page
├── storage.py       # 💾 SQLite: jobs, documents, people, search runs, apply sessions (+ migrations)
├── db_health.py     # 🩺 Check, repair and back up the database on every start
├── api/             # 🔌 FastAPI routes, WebSockets (/ws events, /ws/browser live view)
├── config/          # ⚙️ Settings, model catalog & limits, LLM router, app state
└── web/             # 🎨 Preact + htm UI with bundled fonts — no build step

• 🚀 One command to run it: start.ps1 / start.bat (Windows) and start.sh (macOS / Linux) set up uv, the venv and packages, check that everything loads, start the app, and open the browser only once it answers.
• 🔁 One search at a time; every event carries its run id, so old results never leak into a new search. Background watchlist checks never interrupt a search you started.
• 📶 Real progress only: progress is streamed as real counts (search.progress events), never estimated from time.
• 💸 Low AI cost: profile understanding and job reading are cached, role-fit is batched, out-of-country jobs are dropped before any AI call, watchlist checks read only new postings (20 per check), and a provider whose key is rejected is skipped instead of retried.
• 🔒 Secure by default: same-origin CORS, CSRF guard, WebSocket origin checks, SSRF-safe fetching, upload limits, autoescaped templates.

🔌 API Reference

The full contract (REST + WebSocket) is in jobhunterx/docs/API.md.

🧪 Testing

# with the venv on (see Quickstart)
cd jobhunterx
python -m pytest -q --ignore=tests/frontend      # fast: API, pipeline scenarios, parsers

uv pip install playwright                        # only needed for the browser UI tests
python -m pytest -q tests/frontend

• tests/test_scenarios.py — the full pipeline on a realistic candidate (fake network + fake AI, including made-up claims that must be rejected)
• tests/test_api_v2.py — API contract, errors, cancellation, CSRF / WebSocket / SSRF guards
• tests/frontend/test_ui.py — Playwright against the real app

📜 License

MIT License — Build on it, fork it, make it yours.

Built with ❤️ and an unhealthy amount of caffeine for job seekers who refuse to waste time on repetitive applications.

⭐ Star this repo if JobHunterX saved you from the soul-crushing grind of manual job applications