convez.ai
Agente
Tamircohen28

headhunter

Tamircohen28/headhunter

Ver no GitHub
BomPluginScore · de 0 a 100

AI job-search co-pilot: CRM pipeline, interview prep, CV tailoring, job discovery, salary negotiation, and analytics — all from your terminal.

Instalação

$npx convez-ai Tamircohen28/headhunter

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
85%
Último commit
há 3 meses
Versão
v1.5.0
Issues abertas
0
Contribuidores
5

README

A tradução para o português deste README ainda está na fila.

HeadHunter — AI Job Search Co-pilot

CI License: MIT Node.js ≥ 18

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

CommandWhat it does
add-applicationAdd a job to the pipeline
pipelineKanban board — move applications between stages
dashboardMetrics: response rate, conversion, ghosted %, avg time
calendarUpcoming interview agenda
tasksView and manage prep tasks
contactsContacts per application
log-interviewLog an interview round + debrief
searchFilter applications by any field
settingsView/edit settings (currency, stale threshold, salary)
statusMid-session notification check
cv-reviewATS score, keyword gaps, bullet improvements, LinkedIn audit
syncTrigger Notion / Calendar / Tasks / Todoist syncs
export-dataExport 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

DocContents
docs/user/quick-start.mdInstall → seed → first scan in 5 minutes
docs/user/concepts.mdPipeline, skills, agents, data model explained
docs/user/troubleshooting.mdCommon errors + fixes
docs/ARCHITECTURE.mdStorage model, system layers, pipelines, MCP vs scripts
docs/engineering/architecture/overview.mdLayer breakdown, data flow, design invariants
docs/engineering/decisions/001-local-json-store.mdADR: why flat JSON over SQLite/MongoDB
docs/CONTRIBUTING.mdHow to contribute
references/data-model.mdEntity fields and enums
AGENTS.mdAgent/CLI quick reference

Scripts

ScriptPurpose
scripts/crud.jsAdd/update/move/delete/seed all entities; event log
scripts/dashboard.jsAnalytics metrics (--json for raw)
scripts/analytics.jsFunnel with conversion rates, source performance
scripts/calendar.jsInterview agenda
scripts/timeline.js <appId>Per-application chronological timeline
scripts/session-briefing.jsSessionStart briefing (pipeline + overdue + stale)
scripts/candidate-profile.jsManage candidate profile (show/set/extract-cv/reset)
scripts/score-job.js <meta.json>Deterministic pre-score for the scanner
scripts/generate-cv-html.jsMarkdown CV → A4 HTML (print to PDF)
scripts/draft-followups.jsIdentify and draft follow-up emails
scripts/save-discovered-jobs.jsBatch-save discovered job leads (dedup by URL)
scripts/csv-import.jsCSV → applications (--url for remote CSVs)
scripts/export-applications.jsExport CSV or JSON
scripts/detect-gmail-status.jsClassify emails → pipeline status
scripts/sync-notion.jsApplications + tasks → Notion (--dry-run)
scripts/sync-todoist.jsTasks → Todoist (--dry-run)
scripts/sync-google-calendar.jsInterviews → Google Calendar (--dry-run)
scripts/sync-google-tasks.jsTasks → Google Tasks (--dry-run)
scripts/sync-twilio.jsWhatsApp reminder digest (--dry-run)
scripts/send-stale-reminders.jsStale-app digest via Twilio or stdout (--dry-run)
scripts/backup.jsTimestamped JSON snapshot (deduped, max 10)
scripts/pipeline-run.jsResearch dir init / write prompts / batch / finish
scripts/deep-research.jsOpenAI Deep Research for topic batches (OPENAI_API_KEY)
scripts/restore.js <backup>Restore from snapshot (--confirm)
scripts/validate-data.jsPostToolUse schema validation
scripts/test.sh21-check self-test suite

Environment variables

VariablePurpose
HEADHUNTER_DATA_DIROverride data directory (default: ./data relative to repo root)
NOTION_TOKENNotion MCP / sync
NOTION_DATABASE_IDApplication → Notion database
NOTION_TASKS_DATABASE_IDTask → Notion database
GOOGLE_OAUTH_TOKENGoogle Calendar + Tasks REST sync
GOOGLE_CALENDAR_IDCalendar ID (default: primary)
GOOGLE_TASKS_LIST_IDTasks list ID (default: @default)
TODOIST_API_TOKENTodoist sync
TWILIO_ACCOUNT_SID / TWILIO_AUTH_TOKEN / TWILIO_WHATSAPP_FROM / WHATSAPP_TOWhatsApp reminders
GITHUB_PERSONAL_ACCESS_TOKENGitHub MCP (profile import, company research)
LINKEDIN_EMAIL / LINKEDIN_PASSWORDLinkedIn MCP (unofficial, opt-in — see below)
OPENAI_API_KEYOpenAI Deep Research for topic batches (deep-research.js)
OPENAI_DEEP_RESEARCH_MODELOptional: o3-deep-research or o4-mini-deep-research (default)

Secrets live in your environment only — never commit them. data/ and .env are gitignored.


MCP servers

Configured in .mcp.json. Active by default:

ServerPackagePurpose
Gmailofficial claude.ai integrationEmail scanning + follow-up (authenticate via /mcp)
Google Calendarofficial claude.ai integrationInterview scheduling (authenticate via /mcp)
Notion@notionhq/notion-mcp-serverApplication + task sync (requires NOTION_TOKEN)
GitHubtamirs-superpowers pluginProfile import, company research (zero-config via gh CLI)

LinkedIn MCP (opt-in)

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=yourpassword

Then 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}"
  }
}

Testing

bash scripts/test.sh           # 21 checks — exercises every core feature
node scripts/crud.js seed      # reset to demo data
Ver o original no GitHub

Bom para

Relacionados