← Help

Frequently Asked Questions

Quick answers to the most common questions. For the full walkthrough, see the help guide.

Is JobHunt free?

Yes. JobHunt is free and open source. There are no subscriptions and no accounts. If you use a cloud AI provider for extraction, you pay that provider directly for usage — but you can avoid that entirely with a local model (see below).

Does my data leave my Mac?

All your data is stored locally on your Mac. When you use a local AI model (LM Studio, Ollama, or a custom endpoint on localhost), nothing leaves your machine. When you choose a cloud provider, job description text is sent for extraction, and your resume text is sent along with it for fit scoring — only after you grant consent. See the Privacy Policy for details.

Do I have to pay for AI?

No. JobHunt works with free local models via LM Studio or Ollama — everything runs on your own machine at no cost. Cloud providers (OpenAI, Anthropic, Google, OpenRouter) are optional and typically cost a fraction of a cent per job. Google's Gemini Flash is a good low-cost default.

Which AI provider and model should I use?

For privacy and zero cost, use a local model through LM Studio or Ollama. For the best quality with minimal setup, a cloud model like Gemini Flash offers strong results at very low cost. You can switch any time in Settings → AI Provider and use Test Connection to confirm it works.

Do I need to keep the app open?

Yes — the app runs the local connection (localhost) that the Chrome extension talks to. If the app isn't running, the extension queues your captures and retries them automatically once the app is open again.

Why isn't the extension connecting?

Make sure the JobHunt app is open, then reopen the extension popup. If it still can't connect, restart the app. Captures made while disconnected are held in the extension and sync once the connection is restored.

Do I need a resume?

Only for fit scoring. Extraction (title, company, location, salary, etc.) works without one. To get a 0–100 fit score, add your resume in Settings → Resumes, then re-run scoring on existing jobs.

Why is a fit score low or missing?

Fit is scored across skills, seniority, location, and work arrangement against your resume and preferences. A low score usually means a genuine mismatch on one of those dimensions — open the job's Fit tab to see the breakdown. A missing score means no resume is configured, or scoring hasn't run yet; use Score against resume on the Fit tab.

How do I re-run AI on a job?

New captures are extracted automatically. To reprocess one, use Re-run AI on the job's detail pane, or on a selection in Jobs or Data Quality. To recompute fit after editing your resume without re-extracting, use Score against resume on the Fit tab.

What do the job statuses mean?

A job moves through New → Interested → Applied → Interview → Offer as things progress. The rest are endings, and the difference matters mainly for your own records:

Nothing is lost in any of these states, and you can move a job back at any time. If you only ever use Archived, everything still works — the distinction only affects how you can slice your own history later (for example, telling "I passed on 30 roles" apart from "30 companies rejected me").

What happens to duplicate jobs?

JobHunt groups likely duplicates (by title, company, and URL similarity) in the Duplicates screen, where you can keep, merge, archive, or ignore them. A job marked Duplicate is hidden from default views but kept in history.

How do I track referrals?

Open a job in your active pipeline and use the Referral section on its detail pane. Add one request per contact and move it through Requested → Responded → Submitted (or Declined), each with its own date — you can step back a state if you mis-clicked. Mark a job N/A when no referral is possible. The Dashboard shows jobs you've applied to but haven't asked for a referral yet and reminds you to follow up when a request goes quiet, and the Needs outreach filter in Jobs lists everything still waiting on a request.

What is the Application History report?

Application History (under Tools) is a date-stamped record of every job you've marked Applied — handy for employment or unemployment-benefit reporting that asks where and when you applied. You can correct the recorded application date, add evidence details, and export the whole list to CSV.

What's on the Dashboard?

The Dashboard opens with a Today recap of what you got done — jobs captured, applications sent, interviews, referrals requested, notes added, and follow-ups completed — plus a 7- or 30-day activity strip. Below it are follow-ups due, referral reminders, roles recommended to apply to, your application funnel, and housekeeping counts. Tap any total to see the jobs behind it.

How do notifications and Undo work?

Actions like archiving or changing a status show a brief toast with an Undo button in the corner. The same notifications also collect under the bell in the toolbar, so you can undo or review them later even after the toast fades — and Clear All when you're done. Rapid changes are grouped into a single entry with one Undo.

Will JobHunt warn me if I've already applied to a company?

Yes. When you open a job you're Interested in, JobHunt flags other roles at the same company you've already applied to, so you don't apply twice by accident. It's a heads-up only — it never blocks you.

How do I back up my data?

Use Settings → Data → Back Up to save a snapshot of your job database. Note that AI provider API keys are stored separately in the macOS Keychain and are not included in a backup — after restoring on a new Mac, re-enter your API key in AI Provider settings.

Does JobHunt work on Windows or Linux?

No. JobHunt is a native macOS app (macOS 15 and later). The Chrome extension works in any Chromium browser, but it only sends captures to the macOS app.

How do I install JobHunt?

Get it from the Mac App Store, or download the DMG from GitHub Releases. Both are the same app; the DMG build additionally includes the MCP server for AI assistants, which the sandboxed App Store build can't ship.

How do I update the app?

If you installed from the Mac App Store, updates arrive through the App Store automatically. If you installed the DMG, the app checks for updates automatically — you can also check manually from the application menu (JobHunt → Check for Updates) or download the latest build from GitHub Releases.

How do I connect JobHunt to an AI assistant (MCP)?

The DMG build ships a small bridge, jobhunt-mcp, that exposes your job database to AI assistants over the Model Context Protocol. A few things first:

Claude Desktop

Open Settings → Developer → Edit Config (this opens ~/Library/Application Support/Claude/claude_desktop_config.json) and add:

{
  "mcpServers": {
    "jobhunt": { "command": "/Applications/Jobhunt.app/Contents/Helpers/jobhunt-mcp" }
  }
}

Then fully quit and reopen Claude Desktop.

Claude Code (terminal)

claude mcp add jobhunt -- /Applications/Jobhunt.app/Contents/Helpers/jobhunt-mcp

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.jobhunt]
command = "/Applications/Jobhunt.app/Contents/Helpers/jobhunt-mcp"

Gemini CLI

Add to ~/.gemini/settings.json (same shape as Claude Desktop):

{
  "mcpServers": {
    "jobhunt": { "command": "/Applications/Jobhunt.app/Contents/Helpers/jobhunt-mcp" }
  }
}

ChatGPT desktop and the Gemini web/desktop app currently support only remote MCP connectors (a server URL), not a local command, so JobHunt's on-device bridge can't be added to them yet. Any MCP client that accepts a local command works — point it at the path above. (MCP support in these tools changes quickly; check each tool's own MCP docs if a config key differs.)

Not seeing the tools? Make sure JobHunt is open, then restart the assistant so it re-reads its config.

Still stuck?

See Support & Bug Reports — report a bug on GitHub or email us at [email protected].