jobhuntbot

JobHuntBot

English below · 中文 在下方

An agent-led job application workflow and local progress-tracking dashboard. It works with any AI coding agent that can read a file and follow written instructions (Claude Code, Codex CLI, Cursor, etc.) — there's no special integration required, you just point the agent at SKILL.md and tell it to follow the workflow. It turns scattered job hunting into a repeatable system: candidate profile, screening rules, resume strategy, application execution, blocker triage, follow-up, and a browser-based dashboard to see it all at a glance.

This is not a one-click auto-apply bot. It is a structured workflow plus explicit safety boundaries — the agent stops and asks before guessing anything identity-, legal-, or compensation-related, and before it clicks final submit on any application.

What's in this repo

SKILL.md                        Core agent workflow and safety contract — start here
references/
  setup-workflow.md             Step-by-step onboarding the agent should follow
  application-playbook.md       Browser/ATS handling playbook (forms, uploads, CAPTCHA, etc.)
  safety-and-boundaries.md      Privacy, consent, and what should never be automated
templates/
  candidate_profile.template.json    Your facts: identity, contact, work authorization, targets
  application_rules.template.md      What to prioritize, consider, skip, or hand off to you
  resume_routing.template.md        Which resume/version to use for which role family
  answer_bank.template.md           Reusable truthful answers for common application questions
  experience_bank.template.md       Which internships/projects to feature per role family and JD
  dashboard-template/               Empty CSV dashboard + field reference (see its README.md)
dashboard/                       A ready-to-run local dashboard (same CSV schema as the template)
  server.js                     Zero-dependency static file server (Node.js, no npm install)
  dashboard.html                 The dashboard UI itself
  start-dashboard.bat / .sh     One-click launcher (Windows / macOS-Linux)
  *.csv                          Empty starter data files

Quick Start

1. Download or clone this repo to your machine (or point your coding agent at the GitHub URL).

2. Give the agent browser access — required for actually filling out applications. Research/lead-finding (step 4 below) only needs web search, but step 6 in SKILL.md (filling out real forms, uploading a resume, clicking submit) needs the agent to control a real browser. Set this up once, before you ask it to apply to anything:

   • Claude Code: add the Playwright MCP server so the agent gets browser tools (navigate, click, type, fill forms, upload files, take snapshots):

     claude mcp add playwright npx '@playwright/mcp@latest'
     

     Restart/reopen your Claude Code session afterward so it picks up the new tools.
   • Codex CLI or another agent: check whether it has an equivalent browser-automation or computer-use capability (a Playwright-based MCP server, a built-in browser tool, etc.) and enable it the way that agent documents. Without it, the agent can still do everything up through lead-finding and drafting — it just can't open a real application page and submit it for you.
   • You can skip this entirely if you only want the lead-finding/dashboard-tracking half of the workflow and plan to submit applications yourself.

3. Put your source materials where the agent can read them. Before onboarding, drop your resume (ideally an editable DOCX/Markdown source, not just a PDF — see references/setup-workflow.md for why), transcript, and any project write-ups you want it to draw on into a folder in this repo, e.g. my-materials/. That folder name is already listed in .gitignore, so if you're keeping this repo on GitHub your personal files won't get committed by accident. Then just tell the agent where to look:

   My resume, transcript, and project notes are in my-materials/. Read them before we start.
   

4. Start a session with your AI coding agent (Claude Code, Codex CLI, or any agent that can read local files) in this folder and say:

   Use SKILL.md to initialize my job search workflow.
   

   The agent will ask you a small set of minimum-viable questions (identity basics, target roles, work authorization, resume strategy — Volume vs. Precision) and fill in the files under templates/ for you, using whatever it already read from your materials folder plus your answers. It will not guess anything sensitive; it asks when a fact matters and it's missing.

5. Run a safe first trial. Tell the agent explicitly:

   Do a lead-finding-only trial: find 3-5 jobs, classify them, update the dashboard, and don't open application flows or submit anything.
   

   This step only needs web search, not the browser automation from step 2 — it's the recommended way to see the workflow work before it touches any real application form.

6. Open the dashboard to see progress:

   • Windows: double-click dashboard/start-dashboard.bat
   • macOS/Linux: run dashboard/start-dashboard.sh (requires Node.js installed; chmod +x it once if needed)
   • This opens http://localhost:8420/dashboard.html in your browser. It reads the CSVs in the same folder live — every refresh shows the latest state, no build step, no external server, nothing leaves your machine.

7. Keep applying with the agent's help, one company at a time — this is where the browser automation from step 2 actually gets used. It updates job_pool.csv, application_log.csv, blocker_queue.csv, and follow_up.csv as it goes, and always pauses for your explicit confirmation before a final submit.

Faster Form Filling

The workflow defaults to filling a complete form section, or several predictable adjacent sections, in one browser-tool call. The agent prepares confirmed answers once, checks saved values and validation errors together, and repairs only differences. If a batch is interrupted, it checks what was saved and resumes from unfinished fields. Dependent controls still wait for real options, and final submission still requires your confirmation. See the application playbook for the execution rules.

The Dashboard

The dashboard is a static HTML page + a tiny local Node server (no framework, no build, no external dependencies). It groups your job_pool.csv rows into three views:

• Applied — rows with status = Submitted, with follow-up timeline and how each was submitted. Expand a card and click "进度已结束" (Mark as ended) at the bottom, then "已通过" (Passed) or "已被挂" (Rejected) — this writes the new status straight back into job_pool.csv and the job moves to the Ended view on next refresh. (The local server also confirms the row still matches company + job title before writing, in case the agent updated the same file in the meantime.)
• Pending — rows with status = Pending / Needs user, split into "confirmed open, not yet applied" vs. "not open / unclear" using the cohort_match_status column (see templates/dashboard-template/README.md for the full field reference).
• Ended — rows marked Offer or Rejected.

Below the three views, a 7-day calendar shows upcoming events (tests, interviews, anything you schedule) for jobs in the Applied bucket. Click "+ 添加日程" to add one: pick the date/time, search for the company/job from your already-submitted list, and type the event content freely (e.g. "二轮面试", "笔试") — whatever you type is used verbatim, since every company's process reads differently. Saving an event also stamps that job's current_stage in job_pool.csv with the same text, so the Applied card immediately shows it. Events can be edited or deleted later from the calendar; deleting one does n