headhunter

HeadHunter — AI Job Search Co-pilot

A full-lifecycle job-search assistant: pipeline CRM, interview prep, CV tailoring, job discovery, salary negotiation, network mapping, and analytics — all from your terminal.

Works with Claude Code, Cursor, and OpenAI Codex CLI.
Requires Node.js ≥ 18. No npm dependencies.

Storage: there is no separate database server — all CRM data lives in local JSON under data/ (see docs/ARCHITECTURE.md for the full architecture, pipeline, and integration model).

---

Install

Claude Code

/plugin marketplace add /path/to/headhunter
/plugin install headhunter@headhunter-marketplace

Cursor

Rules auto-load from .cursor/rules/. MCP servers load from .cursor/mcp.json. Both are included in this repo — open the repo root in Cursor and they're active immediately.

OpenAI Codex CLI

AGENTS.md at the repo root is read automatically by Codex. No install step needed — clone the repo and run codex from it.

---

First run

node scripts/crud.js seed        # load 5 demo applications
node scripts/candidate-profile.js show   # view your profile (set up with /headhunter:setup)

---

Lifecycle

/headhunter:setup     → build your candidate profile (CV, salary, target roles)
/headhunter:discover  → find matching jobs on LinkedIn, AllJobs, Drushim, Indeed
/headhunter:scan      → Match Score + Success Score for any job posting
/headhunter:brief     → full company intel + salary script (ILS) for recruiter screen
/headhunter:apply     → tailored CV (HTML) + cover letter for a specific role
/headhunter:network   → find contacts at target company, draft outreach
/headhunter:research  → study guide (scrape → analyze → OpenAI Deep Research → merge)
/headhunter:mock      → live mock interview with per-answer feedback
/headhunter:insights  → post-interview performance analysis + next-round predictor
/headhunter:negotiate → counter-offer script with market data (ILS)
/headhunter:followup  → draft follow-up emails for stale applications
/headhunter:analytics → pipeline funnel, conversion rates, source performance

---

Commands

Command	What it does
add-application	Add a job to the pipeline
pipeline	Kanban board — move applications between stages
dashboard	Metrics: response rate, conversion, ghosted %, avg time
calendar	Upcoming interview agenda
tasks	View and manage prep tasks
contacts	Contacts per application
log-interview	Log an interview round + debrief
search	Filter applications by any field
settings	View/edit settings (currency, stale threshold, salary)
status	Mid-session notification check
cv-review	ATS score, keyword gaps, bullet improvements, LinkedIn audit
sync	Trigger Notion / Calendar / Tasks / Todoist syncs
export-data	Export pipeline to CSV or JSON

---

Skills (always loaded)

• headhunter-core — CRM operations, offer comparison, search/filter
• pipeline — Kanban view and stage moves (read-only)
• interview-research — multi-agent study guide pipeline
• interview-prep — prep briefs with pre-assessment and study guide integration
• interview-brief — Interview Intel: 6-section company briefing with ILS salary script
• job-scanner — Match + Success scoring with company selectivity research
• application-assistant — tailored CV + cover letter generation (HTML output)
• cv-optimizer — ATS scoring, keyword gap analysis, LinkedIn audit
• mock-interview — interactive mock session with per-answer evaluation
• job-discovery — multi-board job search (LinkedIn, AllJobs, Drushim, Indeed)
• salary-negotiation — counter-offer script with market anchoring
• network-finder — contact mapping + personalized outreach drafts
• follow-up — detect and draft follow-up emails for all three scenarios
• gmail-status-scan — classify inbox → detect status changes (with approval gate)
• integrations — Notion / Calendar / Google Tasks / Todoist / CSV / reminders
• scaffold-base44-app — regenerate Base44 React web app (developer mode)

---

Documentation