An MCP server that turns your AI agent into a job search assistant, with a local dashboard.
jhh pulls open roles from the public job boards of the companies you care about, and searches Himalayas's public jobs API and Hacker News's monthly "Who is hiring?" threads for roles at companies you didn't know to list. It filters out the obvious misses with simple rules, and tracks your applications and outreach. Your own agent (Claude Code, Cursor or any MCP client) does the judgment: it interviews you, writes your profile and filters, and screens each role for fit. Everything stays on your machine, in one SQLite file.
Status: early, and in daily use. The author has used jhh every day since October 2026, and the features added since the MVP came out of that use: tracking messages from recruiters, interviews and contacts, and an "apply next" shortlist. See the latest release. The design is in docs/design.md, and what's next is in docs/roadmap.md.
Download the archive for your system from the latest release, unpack it, and put jhh (jhh.exe on Windows) somewhere on your PATH. jhh version says which release you have.
The binaries aren't signed yet, so Windows SmartScreen and macOS Gatekeeper warn the first time you run one. To check that a download was built from this repo, use the GitHub CLI: gh attestation verify <archive> -R drewsokol/job-hunt-harness. Or build it yourself with Go: go install github.com/drewsokol/job-hunt-harness/cmd/jhh@latest.
To update, download the new release and replace the binary, then restart your agent's connection to jhh. jhh backs up its database before it upgrades it.
Add jhh to your agent as an MCP server that runs the jhh binary with no arguments. In Claude Code:
claude mcp add jhh -- /path/to/jhhOther MCP clients take the same command in their config:
{ "mcpServers": { "jhh": { "command": "/path/to/jhh" } } }Then ask your agent to "initialize job hunt harness". It interviews you about what you want next, reads your resume if you point it at one, writes your profile and filters with your OK, suggests companies, fetches jobs and screens a first batch with you. After that, "what's new?" is the daily check-in, "screen new jobs" rates whatever the last refresh found, and "interview me again" updates your profile when your search changes. Before an interview, start a new session and say "help me prepare for my interview with …": the agent helps you prepare and debrief, and keeps a bank of your career stories so every session tells them the same way.
To see everything you can ask, open the dashboard and press ? in its header: the "Ask your agent" page lists each workflow with the phrase to say, a button that copies it, the slash command where there is one, and which ones are best started in a new session.
Ask your agent to "open my dashboard", or run jhh dashboard. It opens in your browser at http://127.0.0.1:7878 (set JHH_UI_PORT to use another port) and shows what your agent finds and does, live:
- To review: the jobs your agent rated, best first, with its reason, the gaps and the pay. Mark them applied, skip them, keep notes, or add a role you found yourself. Keys:
j/kto move,aapplied,sskip,oopen the posting,nnotes,xselect for bulk skip,uundo. - Applied and Outreach: your applications and the people you wrote to, with follow-up dates.
- Archive: skipped jobs, the ones your agent screened out, and the ones your filters dropped, each with the reason. "Send to screening" overrides a filter.
- Profile: the profile, memories and filters your agent set up. To change them, ask your agent.
When a listing contains text addressed to an AI, the job gets an "AI instructions" badge, and you decide whether to keep or hide it. The dashboard only answers on 127.0.0.1, and the link from your agent signs your browser in once.
Your data lives in one SQLite file in your user data directory (jhh doctor shows where). Set JHH_DATA_DIR to put it somewhere else.
Requires Go (the version in go.mod). Everything else comes through Go itself.
go build ./cmd/jhh # build the jhh binary
go test ./... # run the tests
go vet ./... # vet
go tool staticcheck ./... # lint
gofmt -l . # list files that need formattingTo keep your real data separate while developing, point jhh at a scratch directory with JHH_DATA_DIR:
JHH_DATA_DIR=./tmp-data go run ./cmd/jhh doctor
JHH_DATA_DIR=./tmp-data go run ./cmd/jhh probe exampleco # which board does a company use?
JHH_DATA_DIR=./tmp-data go run ./cmd/jhh companies add "Example Co" # find its board and start reading it
JHH_DATA_DIR=./tmp-data go run ./cmd/jhh refresh # fetch the boards you added
JHH_DATA_DIR=./tmp-data go run ./cmd/jhh filters preview examples/filters.json # what would these filters keep?
JHH_DATA_DIR=./tmp-data go run ./cmd/jhh filters set examples/filters.json --rationale "trying the example"
JHH_DATA_DIR=./tmp-data go run ./cmd/jhh sources # where jhh searches: Hacker News is on from the start
JHH_DATA_DIR=./tmp-data go run ./cmd/jhh sources set himalayas examples/himalayas.json # give Himalayas a query
JHH_DATA_DIR=./tmp-data go run ./cmd/jhh refresh # runs the search sources that are on; fetches descriptions for jobs that passed stage 1
JHH_DATA_DIR=./tmp-data go run ./cmd/jhh candidates # the jobs that passed, best first
JHH_DATA_DIR=./tmp-data JHH_UI_PORT=7979 go run ./cmd/jhh dashboard # the dashboard, on a port of its ownjhh ships no list of companies: yours starts empty and grows from what search finds and what you add. Normally your agent writes the filters and sets up the sources through MCP; the filters and sources commands are for checking them by hand. examples/ holds made-up examples.
Tests never touch the network: each source is tested against made-up fixtures by the shared conformance suite in internal/sources/conformance.
Never commit real profiles, resumes, salary numbers, contacts or databases. Test fixtures are always made up.
Pull requests to main need the owner's review. When the owner opens one that isn't a draft, a GitHub Action has Claude review it and post one summary comment (.github/workflows/claude-review.yml); the owner can also run that review by hand on any PR, such as a draft that is now ready. It never runs on its own for outside PRs.
New features start as specs in docs/specs/ (how). When the owner opens a spec PR, another Action has Claude comment with the questions that would change what gets built (.github/workflows/spec-review.yml), and the owner's /review comment runs it again after answering. Merging a spec starts the build workflow (.github/workflows/build.yml), which has Claude build it on a spec/... PR in rounds of implement, check and review, and tags the owner when it has a question or is ready; the owner steers it with /continue, /restart and /stop.
