Job Hunter

Complete job-search pipeline for Pi Agent — search, score, salary enrichment, and assisted applications.

Prerequisites

Layer	Requirement	Stage
Runtime	Node.js ≥ 22, uv ≥ 0.4	Install
Code	npm ci in repo root	Install
Workspace	$JOBHUNTER_HOME (default ~/.job-hunter) with jobhunter.sqlite, CV.docx, personal-info-cache.json	Init
Browser	Chromium CDP on 127.0.0.1:9225 (Selenium container)	Search, Apply
Search	SearXNG on 127.0.0.1:8888	Discover
Vision (optional)	LM Studio on 127.0.0.1:1234 with Qwen VLM	CAPTCHA, Debug
MCP (optional)	Obscura, Apple Mail MCP servers	Browse, Outreach

Host tools (docker, sqlite3, python3) must be installed and on PATH — the doctor (jh-doctor) diagnoses which are missing but does not install them.

Installation

git clone https://github.com/Deviad/job-hunter.git && cd job-hunter
npm ci
node scripts/install.mjs          # copies skills into ${PI_AGENT_HOME:-~/.pi/agent}/skills/
node scripts/install.mjs --dry-run  # preview without writing

Re-run is idempotent and never overwrites CV.docx, personal-info-cache.json, or jobhunter.sqlite.

Initialization

node ~/.pi/agent/skills/job-hunter/scripts/jh-init.mjs

Before applying, populate ~/.job-hunter/CV.docx and the profile.firstName, profile.lastName, profile.email, and profile.phone fields in ~/.job-hunter/personal-info-cache.json. Application helpers fail closed when required identity fields are absent; the repository contains no maintainer identity defaults.

Doctor

Run the doctor before each search or application session. It distinguishes required failures from optional degraded capabilities.

node ~/.pi/agent/skills/job-hunter/scripts/jh-doctor.mjs

External Services

Start Selenium and SearXNG:

export SEARXNG_SECRET="$(node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))")"
docker compose up -d
bash scripts/rehearse-compose.sh    # isolated health-check rehearsal with teardown

See docs/prerequisites.md for full host-tool list and docs/security-and-privacy.md for security boundaries.

Workflow

Search

node ~/.pi/agent/skills/job-hunter/scripts/jh-search.mjs --source linkedin --country GB --role "Software Engineer"
node ~/.pi/agent/skills/job-hunter/scripts/jh-search.mjs --source indeed --country GB --query "Software Engineer"
node ~/.pi/agent/skills/job-hunter/scripts/jh-discover.mjs --locations "United Kingdom" --queries "Software Engineer"

Score

Ask Pi to score the saved jobs. The job-match-scorer skill reads the user's CV and workspace profile rather than repository defaults.

Salary

node ~/.pi/agent/skills/salary-calculator/scripts/enrich-job-salary.mjs --db ~/.job-hunter/jobhunter.sqlite --all-unsalaried

Apply

Ask Pi to apply to a scored job. The auto-job-application skill uses the user's local CV, cache, and authenticated Chromium session; there is no repository-level submit command.

Pipeline status and backup

node ~/.pi/agent/skills/job-hunter/scripts/jh-status.mjs
node ~/.pi/agent/skills/job-hunter/scripts/jh-backup.mjs

Update

git pull && npm ci && node scripts/install.mjs

Uninstall

node scripts/install.mjs --uninstall

Removes only files recorded in the installation manifest. User data (CV.docx, DB, cache) is untouched.

Troubleshooting

node ~/.pi/agent/skills/job-hunter/scripts/jh-doctor.mjs    # full diagnostic

Common issues:

• CDP not reachable: ensure docker compose up -d ran and curl -s http://127.0.0.1:9225/json/version returns JSON.
• SearXNG 502: SearXNG needs a few seconds after container start; retry after 5s.
• better-sqlite3 build failure: ensure python3 and a C compiler (Xcode CLT on macOS) are installed.
• MCP "Not connected": run the repair skill or bash scripts/rehearse-compose.sh to verify transport.

Security and Privacy

• All job-search data, credentials, and browser sessions stay on your machine.
• The installer never reads or transmits personal files.
• Authenticated browser sessions (LinkedIn, Indeed) belong to you — this project does not bypass MFA, or site access controls.
• See docs/security-and-privacy.md for the full policy.

License

MIT — see LICENSE.