JobHuntBot: An Agent-Read SKILL.md Workflow for Job Applications, With a Local CSV Dashboard

The problem is not finding jobs, it is remembering what you already did

Job hunting at volume produces a specific kind of mess. You have a resume that exists in four versions, a spreadsheet that stopped being updated two weeks ago, a folder of confirmation emails, and no reliable answer to the question of which company you applied to on which date with which resume. JobHuntBot targets that mess. The README frames it as turning "scattered job hunting into a repeatable system" with named stages: candidate profile, screening rules, resume strategy, application execution, blocker triage, follow-up, and a dashboard.

The audience is narrow and identifiable. You need a coding agent that can read local files and follow written instructions, and the README names Claude Code, Codex CLI and Cursor as examples. You also need to be comfortable in a terminal, because the onboarding step is literally a prompt you type into the agent. Someone who wants a web app with a signup form is not the user here. The repository is HTML plus a Node server, and the workflow itself is markdown. There is no installer.

SKILL.md is the product, and the templates are the state

The architecture is unusually flat, and that is the point. SKILL.md sits at the repository root and holds what the README calls the "core agent workflow and safety contract." Three reference documents sit beside it: setup-workflow.md for onboarding, application-playbook.md for browser and ATS handling (forms, uploads, CAPTCHA), and safety-and-boundaries.md for privacy and consent. Nothing in that set is executable. The agent reads prose and behaves accordingly.

State lives in templates. candidate_profile.template.json holds identity, contact, work authorization and targets. application_rules.template.md encodes what to prioritize, consider, skip, or hand back to you. resume_routing.template.md maps role families to resume versions. answer_bank.template.md and experience_bank.template.md hold reusable answers and the internships or projects to feature per role family and job description. During onboarding the agent fills these in from your materials folder plus a short set of questions.

The dashboard reads four CSVs: job_pool.csv, application_log.csv, blocker_queue.csv and follow_up.csv. The agent updates them as it works. The dashboard groups job_pool.csv rows into Applied (status = Submitted), Pending (status = Pending or Needs user), and Ended (Offer or Rejected). Pending is further split by the cohort_match_status column into confirmed-open versus not-open-or-unclear. That column name is the one piece of schema you should read about before trusting the Pending view, and the README points to templates/dashboard-template/README.md for the full field reference.

The safety contract is the actual feature, and it is enforced by prompting

The README is explicit that this is "not a one-click auto-apply bot." The mechanism behind that claim is a behavioural rule: the agent stops and asks before guessing anything identity-, legal-, or compensation-related, and before it clicks final submit on any application. The repository does not contain a code-level interlock that prevents submission. It contains instructions telling the agent not to. That distinction matters if you are evaluating this for someone else, or if you are running a model that is loose about following long instruction files.

The practical consequence is that the workflow is slower than a scripted form filler and considerably more predictable. For work authorization, visa sponsorship and salary fields, an agent that guesses is worse than useless, because a wrong answer on a real application is not recoverable. JobHuntBot's answer to that is to ask. Whether the ask actually happens depends on the agent, the model version, and how much context is competing for attention when the form is open.

Getting it running: one MCP command, one launcher script, and a folder name that is already gitignored

Clone the repository, then decide whether you need browser control. Lead-finding only needs web search. Filling real forms, uploading a resume and clicking submit needs the agent to drive a browser. For Claude Code the README gives one command:

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

Restart or reopen the session afterward so the new tools are picked up. For Codex CLI or another agent, the README tells you to check whether the agent has an equivalent browser-automation or computer-use capability and enable it as that agent documents. It does not provide a command for those. If you skip browser setup entirely, the agent can still do lead-finding and drafting, and you submit manually.

Put your source materials in a folder the agent can read. The README suggests my-materials/ and notes that the name is already listed in .gitignore, so personal files will not be committed by accident if the repository is on GitHub. It also recommends an editable DOCX or Markdown resume rather than a PDF only, and points to references/setup-workflow.md for the reasoning.

Then open the agent in the repository folder and type:

Use SKILL.md to initialize my job search workflow.

The README's recommended first run is a scoped trial: ask for lead-finding only, three to five jobs, classify them, update the dashboard, and submit nothing. That step needs web search alone, which makes it a reasonable way to see the workflow behave before any real form is involved.

For the dashboard, Windows users double-click dashboard/start-dashboard.bat. macOS and Linux users run dashboard/start-dashboard.sh, which needs Node.js installed and may need chmod +x once. The server is described as zero-dependency with no npm install. It opens http://localhost:8420/dashboard.html and reads the CSVs in the same folder live. No build step, no external server, nothing leaves the machine.

The dashboard writes back, which is where the design gets interesting

Most local dashboards are read-only renderers. This one is not. Expanding a card in the Applied view reveals a "进度已结束" (Mark as ended) control, followed by "已通过" (Passed) or "已被挂" (Rejected). Choosing one writes the new status directly into job_pool.csv, and the job moves to the Ended view on the next refresh.

That write path creates a race condition the author has thought about. The README states that the local server confirms the row still matches company plus job title before writing, in case the agent updated the same file in the meantime. That is a narrow check. It catches a shifted row index or a rewritten file, but it does not resolve two simultaneous edits to the same row, and it does not lock the file. If you have an agent mid-run updating job_pool.csv while you click through the dashboard, the guard reduces the chance of writing a status onto the wrong company. It does not eliminate it. The honest reading is that this is a single-user tool with a single-writer assumption most of the time, and the check is a courtesy.

Below the three views there is a 7-day calendar for upcoming events (tests, interviews, anything you schedule) attached to jobs in the Applied bucket, with a "+ 添加日程" control for adding one. The README excerpt ends mid-sentence at the point of describing the date and time picker and the search step, so the exact interaction after that point is not something I can describe from the supplied material.

Where the workflow breaks: a PDF-only resume, no browser, and a CSV as a database

Three failure modes are visible from the repository layout alone.

The first is the resume format. The README recommends an editable DOCX or Markdown source rather than a PDF, and defers the reasoning to references/setup-workflow.md. If your only resume is a PDF, the agent has less to work with when routing role families and drafting answers. That is a real constraint on the resume_routing and experience_bank templates, not a cosmetic preference.

The second is the browser dependency. Without a Playwright MCP server or an equivalent capability in your agent, the workflow stops at lead-finding and drafting. The README says this plainly. It is worth repeating because the marketing-adjacent framing of "agent-led job application workflow" can read as though submission is included by default. It is not.

The third is the storage model. Four CSV files are the database. There is no schema migration path, no locking, no validation layer beyond the company-plus-title check on the dashboard write, and no release history to consult: the repository shows no releases retrieved, and the last push date is 2026-08-08. If you hand-edit a CSV and break a column, nothing in the tool will tell you. The dashboard will simply render fewer rows or misclassify them. Back up the CSV folder before a long application session, and treat the field reference in templates/dashboard-template/README.md as the schema of record.

What it is not: compared with a scripted auto-apply tool

The obvious alternative is a scripted form filler that takes a list of job URLs and submits applications without a human in the loop. The difference is not speed, it is where the judgement lives. A scripted filler encodes your answers once and applies them everywhere, which is fine until a form asks a question you did not anticipate, at which point it either fails or fills something wrong. JobHuntBot puts a language model between the form and your answer bank, with an instruction to stop when the fact is missing or sensitive.

A second alternative is a hosted application tracker with a browser extension. That gives you sync across devices and a support team. It also means your work authorization status, compensation expectations and application history live on someone else's server. JobHuntBot's counter-argument is structural: a static HTML page, a local Node server, and CSVs in a folder. Nothing leaves the machine. If your reason for using a local tool is data locality rather than automation, that is the comparison that matters, and it is the one the README chooses to make.

Maintenance cost, licensing, and what to check before your first real application

The maintenance surface is small and mostly yours. The repository ships no build step and no npm install for the dashboard, so there is no dependency tree to patch. The agent-side setup is one MCP server command for Claude Code, and whatever your agent requires otherwise. The files you will actually maintain are the templates you filled in during onboarding and the four CSVs. Those grow with your search, and nothing prunes them.

The licence is MIT, which permits commercial and private use, modification and redistribution provided the copyright notice and permission notice are retained. That is a summary of the licence identifier given in the repository metadata, not legal advice. If you plan to redistribute a modified version, read the LICENSE file in the repository and, for anything consequential, get your own counsel.

Two things to verify before you let an agent near a real application form. First, read references/safety-and-boundaries.md and confirm that the pause behaviour described there matches what your agent actually does when you test it on a form you do not care about. Second, decide your resume strategy (the README names Volume versus Precision as the choice the agent will ask about) before onboarding, because it feeds application_rules.md and changing it later means re-editing the rules file by hand. The dashboard's company-plus-title check on writes is a guard rail, not a transaction. Keep a copy of the CSV folder before a long session.

Editorial conclusion

Adopt JobHuntBot if you already run Claude Code or Codex CLI in a terminal, are willing to maintain your own candidate_profile.json and application_rules.md by hand, and want application state to live in four CSV files on your own disk. Do not adopt it if you expect the tool to submit applications without browser automation configured, or if you want a hosted tracker with multi-user sync. Before anything else, open SKILL.md and read the safety-and-boundaries.md reference end to end, because the pause-before-submit behaviour is the whole product. Then run the lead-finding-only trial the README describes and inspect the four CSVs it writes before you let an agent touch a real application form.

Official sources

1. DanielPan12/JobHuntBot on GitHub
2. Issues
3. License: MIT
4. README