JobHunt

A Claude Code (and Hermes Agent) plugin that runs a disciplined, low-volume job search for one person. Every weekday it finds roles that fit your hard filters, verifies each one on the employer's own posting, dedupes against everything you have touched, and prepares tailored applications. It submits only through the employer's official apply flow, and only after you approve. It tracks replies and interviews and writes one short daily report.

The design follows one principle: fewer, better applications.

Website: adamwardecki.github.io/job-hunt-mcp

Status: early (v0.1). It grew out of one person's real job search and is used daily by that one person. Expect rough edges, and expect the source adapters to break when job sites change. Issues and pull requests are welcome.

What it will never do

• Send email or LinkedIn messages. It writes drafts only, and a hook blocks every send tool.

• Submit an application without your /j-hunt:approve <role_id> in the same session.

• Create accounts, enter passwords, solve visible CAPTCHAs, tick consent boxes, or fill personal-data fields (passport, nationality, age, gender, marital status, ID numbers).

• Auto-apply at volume.

Related MCP server: job-search-copilot

Requirements

• Claude Code 2.1.295 or newer (the Desktop app or the CLI), or Hermes Agent.

• Node.js 22.18 or newer. If it is missing, /j-hunt:setup offers to install it on macOS and Windows: it downloads the official installer from nodejs.org and checks its checksum and signature (on Windows it uses winget when available). The tracker uses the built-in node:sqlite, and Node runs the plugin's TypeScript directly. There are no runtime npm dependencies.

• Recommended connectors: Gmail and Google Calendar, for recruiter replies, interview invites and reply drafts.

• Recommended browser: Claude in Chrome or the host's built-in browser. You need one for logged-in job boards, some employer pages and every application form. Without a browser the daily run still works and queues browser work for later.

• Optional: a LinkedIn MCP server (read-only use: job search and inbox).

Usage. A sweep runs several subagents (one per source, one per role it scores), so a daily run uses a noticeable share of your Claude plan or API budget. Start with /j-hunt:sweep --limit 5 to see what a run costs you.

Install

Claude Code:

/plugin marketplace add adamwardecki/job-hunt-mcp
/plugin install j-hunt@job-hunt-mcp
/j-hunt:setup

Setup walks through CV import, hard filters, preferences, writing rules, accounts (including which calendar your invites actually land on), connectors, browser check, sources, autonomy and the daily schedule, then runs a 5-result calibration sweep. Every "no, because..." becomes a rule. You can stop at any point and run /j-hunt:setup again to resume.

Already tracking applications in a markdown table? /j-hunt:import <folder> brings in an applied-log.md (| date | company | role | source | action | status |), a preferences file, queue notes and your profile and stories. See commands/import.md for the expected files.

Hermes Agent

The same checkout is also a native Hermes plugin:

git clone https://github.com/adamwardecki/job-hunt-mcp.git
cd job-hunt-mcp
scripts/hermes-install.sh

Restart Hermes and type /j-hunt:setup. Details and the differences from Claude Code are in docs/hermes.md.

What a day looks like

The scheduled sweep ends with a report like this one (the format is real, rendered by the tracker's render_report; the companies are made up):

# Daily report · 2026-10-18

**46 roles checked. 2 worth a look.**

## Needs you

1. **Halyard**, Senior Platform Engineer (role 1): Cover note saved. Apply with /j-hunt:apply?
2. **Pinecrest Health**, Staff Engineer (role 2): The posting asks for 2 days a month in Berlin. OK?

## Interviews

- 2026-10-20 14:00 (Europe/Berlin): **Juniper**, technical screen with Head of Engineering

## Applied

- **Ostra**, Backend Engineer, Payments. Confirmation: "Thanks for applying to Ostra! We will be in touch within two weeks."

## Dropped

- location: Northwind (ATS says hybrid in Austin)
- pay: Ledgerly (Band €55–72k is below the floor)
- industry: Blockwise (Crypto exchange)

## Sources

- wellfound: now degraded (Login expired)

You answer the "Needs you" items, run /j-hunt:apply for the roles you want, and approve each submit.

Commands

How it fits together

commands, scheduled task
  └─ skills (setup, source-roles, verify-employer, score-role, write-note, fill-form,
     triage-tracker, inbox-and-calendar, interview-prep) and agents (sourcer, scorer, auditor)
       └─ hooks: hard gates on every MCP call, user prompt and stop
            └─ MCP: tracker (this repo), Gmail, Calendar, LinkedIn, browser
                 └─ storage: tracker DB in ~/.job-hunt (never inside the plugin directory)

• Tracker (servers/tracker/): the only writer to the database. Narrow tools, no raw SQL. An append-only event log with a state machine (found → verified → scored → queued → applied → interviewing → offer, plus dropped and closed). Drops need an employer quote, verified needs the ATS URL and location line, applied needs the confirmation text. Tool reference: docs/tracker-api.md.

• Hooks (hooks/): see below.

• Skills, commands, agents, templates: the operating rules, including the incidents that shaped them. The original design document, with the reasoning behind each rule, is docs/SPEC.md.

Your data

The tracker runs locally, always. .mcp.json starts a stdio server on ~/.job-hunt/tracker.db. There is no network listener and no token. The directory is created owner-only (0700) and the database and session files are 0600, because they hold your CV summary, pay floor and application history. Tightening is best effort: on a filesystem that cannot chmod, the tracker logs a warning and still starts.

Local storage does not mean nothing leaves your machine. Like any Claude Code or Hermes session, what the model reads (your profile, postings, emails it classifies) goes to your model provider, and each connector you add has its own data policy.

The daily sweep is a local scheduled task (Claude Desktop or Claude Code on your machine, or a Hermes cron job). It needs the browser for logged-in boards, employer pages and forms, and the browser is only reachable from a local session, so cloud scheduled tasks are not supported. The task runs only while the machine is awake and the app is open.

Hooks (hard gates)

Browser gates apply only in sessions that used a job-hunt command or the tracker; send blocking applies everywhere.

Known limits. Gates see tool calls, not the screen. A click by raw coordinates has no element label, so the submit gate cannot classify it; the skills require ref-based clicks for submits and the auditor checks every applied role for captured confirmation text. Pressing Enter in a field is not gated. Hooks require a host that runs plugin hooks (Claude Code, Claude Desktop, Hermes); if approval notes never appear, the approve command tells the model not to submit. If Node.js is missing, or the gate cannot start or times out, mail, LinkedIn and browser tools are blocked (onFailure: "block"); other MCP tools still run, and the prompt hook stays fail open so you can still ask for help.

Use it responsibly

• You are the applicant. Everything submitted goes out in your name. Read what it prepared before you type /j-hunt:approve.

• Site terms. Some job boards (LinkedIn in particular) restrict automated access in their terms of service. The plugin keeps LinkedIn read-only and low-volume, but whether to connect a source is your call and your account.

• Employer AI policies. If a form says not to use AI, the writing skill leaves those fields for you.

• Models make mistakes. Verification quotes the employer's own page so you can check every drop and every match, and /j-hunt:correct turns each mistake into a rule.

Development

npm run setup   # dev only: TypeScript, the Node types and Biome, installed into dev/
npm test        # tsc, then the Node and Python tests

The code is TypeScript that Node runs directly (type stripping), so there is no build step and nothing to install at runtime. npm run typecheck runs tsc on its own; npm run test:node skips it.

Node tests cover tracker logic, migrations and locking, the MCP protocol, every hook gate, the triage guard run against a synthetic board in headless Chrome (skipped when Chrome is not installed), the hook config and matcher partition, the Node.js installer scripts, the runtime instructions in setup and the commands, the Hermes host adapter, the tools/list schemas, and the shared helpers. Python tests cover the native Hermes plugin wiring, including fail-closed rules and the Windows Node path.

See CONTRIBUTING.md before opening a pull request.

Design choices

1. Local only. The tracker is SQLite behind a stdio server in ~/.job-hunt. A remote mode was built and removed: the daily run needs a local browser anyway.

2. The daily run is a local scheduled task. Every run still detects capabilities and queues browser work with blocked_by: browser when no browser is connected.

3. LinkedIn is read-only and optional. Send and connect tools are blocked by a hook.

4. Voice. write-note uses an installed humanizer or writing-style skill when present, else its own rules.

5. Templates ship neutral. Your own values go in through setup.

License

MIT