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 the four targets this repo supports — Claude Code, Cursor,
OpenAI Codex CLI, and OpenCode — each installable standalone straight from this
repo. Per-target guides: docs/user/install/.
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/engineering/ARCHITECTURE.md for the full architecture, pipeline, and integration model).
- Node.js ≥ 18 — the only hard requirement; check with
node --version. - No
npm install— the core CRM runs on Node's standard library alone. - One of Claude Code ≥ 2.0.0, Cursor ≥ 3.14.7, Codex ≥ 0.40.0, or OpenCode ≥ 1.16.2 to drive the agent workflows (optional — the scripts also run standalone). Version floors and how each was derived: platform-targets.json.
- Optional integrations (Notion, LinkedIn, Todoist, Twilio, Google) read credentials from a local
.env; copy.env.exampleand fill in only what you use.
make install # verify Node >= 18 and print per-platform stepsEvery target installs standalone from this repo — no catalog required. Full per-target guides live in docs/user/install/.
/plugin marketplace add TamirCohen28/headhunter
/plugin install headhunter@headhunter
Dashboard → Plugins → Team Marketplaces → Add Marketplace → Import from Repo → TamirCohen28/headhunter.
Or just open the repo root: rules auto-load from .cursor/rules/ and MCP servers from .cursor/mcp.json, both included.
Full guide →
codex plugin marketplace add TamirCohen28/headhunter
codex plugin add headhunter@headhunterAGENTS.md at the repo root is also read automatically — clone and run codex from it for the no-install path.
Full guide →
OpenCode has no plugin format. Clone and run opencode from inside — opencode.json
declares the skill paths and .opencode/agent/ carries the translated subagents.
git clone https://github.com/TamirCohen28/headhunter.git && cd headhunter && opencodeRefresh: make update · Remove: make uninstall
node scripts/crud.js seed # load 5 demo applications
node scripts/candidate-profile.js show # view your profile (set up with /headhunter:setup)/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
| 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 |
- 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)
| Doc | Contents |
|---|---|
| docs/user/quick-start.md | Install → seed → first scan in 5 minutes |
| docs/user/concepts.md | Pipeline, skills, agents, data model explained |
| docs/user/troubleshooting.md | Common errors + fixes |
| docs/engineering/ARCHITECTURE.md | Storage model, system layers, pipelines, MCP vs scripts |
| docs/engineering/architecture/overview.md | Layer breakdown, data flow, design invariants |
| docs/engineering/decisions/001-local-json-store.md | ADR: why flat JSON over SQLite/MongoDB |
| docs/CONTRIBUTING.md | How to contribute |
| references/data-model.md | Entity fields and enums |
| AGENTS.md | Agent/CLI quick reference |
| Script | Purpose |
|---|---|
scripts/crud.js |
Add/update/move/delete/seed all entities; event log |
scripts/dashboard.js |
Analytics metrics (--json for raw) |
scripts/analytics.js |
Funnel with conversion rates, source performance |
scripts/calendar.js |
Interview agenda |
scripts/timeline.js <appId> |
Per-application chronological timeline |
scripts/session-briefing.js |
SessionStart briefing (pipeline + overdue + stale) |
scripts/candidate-profile.js |
Manage candidate profile (show/set/extract-cv/reset) |
scripts/score-job.js <meta.json> |
Deterministic pre-score for the scanner |
scripts/generate-cv-html.js |
Markdown CV → A4 HTML (print to PDF) |
scripts/draft-followups.js |
Identify and draft follow-up emails |
scripts/save-discovered-jobs.js |
Batch-save discovered job leads (dedup by URL) |
scripts/csv-import.js |
CSV → applications (--url for remote CSVs) |
scripts/export-applications.js |
Export CSV or JSON |
scripts/detect-gmail-status.js |
Classify emails → pipeline status |
scripts/sync-notion.js |
Applications + tasks → Notion (--dry-run) |
scripts/sync-todoist.js |
Tasks → Todoist (--dry-run) |
scripts/sync-google-calendar.js |
Interviews → Google Calendar (--dry-run) |
scripts/sync-google-tasks.js |
Tasks → Google Tasks (--dry-run) |
scripts/sync-twilio.js |
WhatsApp reminder digest (--dry-run) |
scripts/send-stale-reminders.js |
Stale-app digest via Twilio or stdout (--dry-run) |
scripts/backup.js |
Timestamped JSON snapshot (deduped, max 10) |
scripts/pipeline-run.js |
Research dir init / write prompts / batch / finish |
scripts/deep-research.js |
OpenAI Deep Research for topic batches (OPENAI_API_KEY) |
scripts/restore.js <backup> |
Restore from snapshot (--confirm) |
scripts/validate-data.js |
PostToolUse schema validation |
scripts/test.sh |
21-check self-test suite |
| Variable | Purpose |
|---|---|
HEADHUNTER_DATA_DIR |
Override data directory (default: ./data relative to repo root) |
NOTION_TOKEN |
Notion MCP / sync |
NOTION_DATABASE_ID |
Application → Notion database |
NOTION_TASKS_DATABASE_ID |
Task → Notion database |
GOOGLE_OAUTH_TOKEN |
Google Calendar + Tasks REST sync |
GOOGLE_CALENDAR_ID |
Calendar ID (default: primary) |
GOOGLE_TASKS_LIST_ID |
Tasks list ID (default: @default) |
TODOIST_API_TOKEN |
Todoist sync |
TWILIO_ACCOUNT_SID / TWILIO_AUTH_TOKEN / TWILIO_WHATSAPP_FROM / WHATSAPP_TO |
WhatsApp reminders |
GITHUB_PERSONAL_ACCESS_TOKEN |
GitHub MCP (profile import, company research) |
LINKEDIN_EMAIL / LINKEDIN_PASSWORD |
LinkedIn MCP (unofficial, opt-in — see below) |
OPENAI_API_KEY |
OpenAI Deep Research for topic batches (deep-research.js) |
OPENAI_DEEP_RESEARCH_MODEL |
Optional: o3-deep-research or o4-mini-deep-research (default) |
Secrets live in your environment only — never commit them. data/ and .env are gitignored.
Configured in .mcp.json. Active by default:
| Server | Package | Purpose |
|---|---|---|
| Gmail | official claude.ai integration | Email scanning + follow-up (authenticate via /mcp) |
| Google Calendar | official claude.ai integration | Interview scheduling (authenticate via /mcp) |
| Notion | @notionhq/notion-mcp-server |
Application + task sync (requires NOTION_TOKEN) |
| GitHub | tamirs-superpowers plugin |
Profile import, company research (zero-config via gh CLI) |
The LinkedIn MCP is an unofficial community package that may violate LinkedIn ToS. It is not included by default. To enable it, set your credentials in ~/.zshrc:
export LINKEDIN_EMAIL=you@email.com
export LINKEDIN_PASSWORD=yourpasswordThen add this block to your plugin's .mcp.json (find it at ~/.claude/plugins/cache/tamirs-plugins/headhunter/<version>/.mcp.json):
"linkedin": {
"command": "bash",
"args": ["${CLAUDE_PLUGIN_ROOT}/hooks/linkedin-mcp.sh"],
"env": {
"LINKEDIN_EMAIL": "${LINKEDIN_EMAIL}",
"LINKEDIN_PASSWORD": "${LINKEDIN_PASSWORD}"
}
}bash scripts/test.sh # 21 checks — exercises every core feature
node scripts/crud.js seed # reset to demo data