# JobHuntBot: an agent-led job application workflow with a local dashboard

> JobHuntBot is a set of instruction files and a local CSV-backed dashboard that let a coding agent run your job search. It is a workflow, not an auto-apply bot, and it stops before the final submit.

**DanielPan12/JobHuntBot** — Agent-led job application workflow with a local progress-tracking dashboard — works with any AI coding agent that can read files and follow instructions.AI Agent 驱动的求职投递工作流,配本地进度追踪看板——适配任何能读文件、听懂指令的编程 Agent。

- Repository: https://github.com/DanielPan12/JobHuntBot
- Stars: 847 · Forks: 67
- Language: HTML
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/danielpan12-jobhuntbot

## What JobHuntBot actually solves

Job hunting produces a mess of files. A resume version here, a spreadsheet of leads there, a note about which recruiter asked for a transcript somewhere else. JobHuntBot's answer is to put the whole thing under a single agent-readable contract: SKILL.md is described as the core workflow and safety contract, and the references folder holds the onboarding steps, a browser and ATS playbook, and a document on privacy and consent.

The target user is someone who already runs a coding agent such as Claude Code, Codex CLI or Cursor. The README is explicit that no special integration is required: you point the agent at SKILL.md and tell it to follow the workflow. That is the whole interface. If you do not already have an agent that reads local files, the project has nothing to offer you.

The README also draws a line early: this is not a one-click auto-apply bot. It is a structured workflow plus explicit safety boundaries, and the agent is meant to stop and ask before guessing anything identity-, legal- or compensation-related, and before clicking final submit on any application.

## The four CSVs the whole workflow writes into

The mechanism is file-based rather than service-based. As the agent works, the README says it updates job_pool.csv, application_log.csv, blocker_queue.csv and follow_up.csv. Those four files are the state of your search. The dashboard reads the same CSVs live, so there is no database, no sync step and no account.

The dashboard groups job_pool.csv rows into three views. Applied holds rows with status = Submitted, and shows a follow-up timeline plus how each was submitted. Pending holds rows with status = Pending or Needs user, split into confirmed open but not yet applied versus not open or unclear, using the cohort_match_status column. Ended holds rows marked Offer or Rejected.

The status transitions are written from the browser rather than by hand. Expanding an Applied card and clicking the mark-as-ended control, then Passed or Rejected, writes the new status back into job_pool.csv and the job moves to the Ended view on the next refresh. The README notes the local server confirms the row still matches company plus job title before writing, which covers the case where the agent edited the same file in the meantime. That check is a small detail, but it is the kind of thing that matters when two writers share one file.

The templates folder mirrors this schema: candidate_profile.template.json, application_rules.template.md, resume_routing.template.md, answer_bank.template.md and experience_bank.template.md, plus dashboard-template with an empty CSV dashboard and a field reference in its own README.

## Installing JobHuntBot and running a first trial

There is no package to install. The README's first step is to download or clone the repository, or to point your coding agent at the GitHub URL.

The one real setup task is browser access, and the README marks it as required for actually filling out applications. Research and lead-finding only need web search, but filling out real forms, uploading a resume and clicking submit need the agent to control a real browser. For Claude Code the documented command adds the Playwright MCP server:

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

After that command, the README says to restart or reopen the Claude Code session so the new tools are picked up. For Codex CLI or another agent, check whether it has an equivalent browser-automation or computer-use capability and enable it the way that agent documents. Without it the agent can still do everything up through lead-finding and drafting.

Next, put your source materials where the agent can read them. The README suggests a folder such as my-materials/ and notes that name is already listed in .gitignore, so personal files will not be committed by accident. Then start a session in the repository folder and say:

```text
Use SKILL.md to initialize my job search workflow.
```

The README states the agent will ask a small set of minimum-viable questions about identity basics, target roles, work authorization and resume strategy (Volume versus Precision), and fill in the templates using what it read from your materials folder plus your answers. It will not guess anything sensitive.

The recommended first run avoids application forms entirely:

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

That trial only needs web search. Then open the dashboard. On Windows, double-click dashboard/start-dashboard.bat. On macOS or Linux, run dashboard/start-dashboard.sh, which requires Node.js installed and may need chmod +x once. The README says this opens http://localhost:8420/dashboard.html, reading the CSVs in the same folder live, with no build step and nothing leaving your machine.

## Where the workflow will not carry you

The safety contract is also the main limitation. The agent stops and asks before guessing anything identity-, legal- or compensation-related, and before it clicks final submit. That is deliberate, but it means JobHuntBot is the wrong tool if what you want is unattended bulk applications. Every submit is a checkpoint you have to be present for.

Browser access is a hard dependency for the half of the workflow that touches real forms. If your agent has no browser-automation capability and no equivalent computer-use feature, you are limited to lead-finding and drafting. The README says so plainly rather than pretending the gap can be worked around.

The dashboard is a static page served by a zero-dependency Node server, with a 7-day calendar for upcoming events such as tests and interviews. It reads CSVs from the same folder on every refresh. That design keeps everything local, but it also means the dashboard is only as correct as the files. If you edit a CSV by hand while the agent is running, you are the second writer on a file that the server only partially guards against, and the guard covers company plus job title matching, not arbitrary edits.

There are no releases listed for this repository, so there is no versioned upgrade path to reason about. The last push was on 2026-08-08. The README also does not document rollback for a status change written from the dashboard.

## How this differs from an auto-apply service

The natural comparison is a hosted auto-apply service: you upload a resume, it submits to many postings, and you get a report. JobHuntBot inverts nearly every part of that. There is no account, no server-side profile and no vendor holding your documents. The state lives in CSV files in a folder you control, and the dashboard is a local page on port 8420.

The difference in approach shows up in what each one optimizes. An auto-apply service optimizes for volume of submissions and removes you from the loop. JobHuntBot optimizes for a repeatable process you can inspect: candidate profile, screening rules, resume strategy, application execution, blocker triage and follow-up, in the README's own list. It also keeps you in the loop at the two points that carry the most risk, which is the identity, legal and compensation questions and the final submit.

That trade is not free. A hosted service will keep submitting while you sleep. JobHuntBot will not, and it will not even open an application page until you have configured browser automation for your agent. If your bottleneck is the number of applications you can send, a service addresses that directly. If your bottleneck is that you cannot remember which resume went to which role family, or which application is waiting on a transcript, the file-and-dashboard model is the closer fit.

## Maintenance, upgrades and the MIT licence

The project is MIT licensed, which permits commercial and private use, modification and redistribution provided the copyright notice and permission notice are kept. That is the standard MIT grant and nothing in the repository adds a further restriction on top of it. This is not legal advice; read LICENSE in the repository if the terms matter to your situation.

Upgrade cost is low in the usual sense because there is no dependency graph. The dashboard server is described as zero-dependency Node.js with no npm install, and there is no build step. Pulling a newer version of the repository is the upgrade. What you do have to maintain is your own data: the four CSVs, the filled-in templates and anything in your materials folder.

There is a real tension worth naming. Your filled-in templates and CSVs are the valuable part of the setup, and they live inside the repository you cloned. The README handles the materials folder by noting my-materials/ is already in .gitignore, but it does not say the same about the templates you fill in or the CSV data files. If you keep this repository on GitHub, check what your agent wrote before you commit. The last push to the upstream repository was on 2026-08-08, and there are no releases, so there is no changelog to diff against when you pull.

## Conclusion

Adopt JobHuntBot if you already use a coding agent, want your job search to run on files you can read and edit, and are willing to set up browser automation before any form gets filled. Skip it if you want a one-click auto-apply bot, or if you will not maintain the CSVs and templates yourself. Verify first that your agent can control a real browser, and check that the dashboard's local server on port 8420 starts on your machine.

## FAQ

### Can ChatGPT find jobs with JobHuntBot?

JobHuntBot is written for AI coding agents that can read local files and follow written instructions, with Claude Code, Codex CLI and Cursor named as examples. It is not tied to ChatGPT, and the README requires the agent to be able to read SKILL.md and the files in the repository.

### Is JobHuntBot a free tool that automatically applies to jobs?

The README states directly that this is not a one-click auto-apply bot. It is a structured workflow plus explicit safety boundaries, and the agent stops and asks for confirmation before clicking final submit on any application. The repository is MIT licensed, so there is no licence fee.

### Can I use AI to find me a job with JobHuntBot?

Yes, for the lead-finding half. The README recommends a lead-finding-only trial where the agent finds 3 to 5 jobs, classifies them and updates the dashboard without opening application flows. That trial only needs web search, not browser automation. Filling out real forms and submitting requires giving the agent browser access first.

## Sources

- [DanielPan12/JobHuntBot on GitHub](https://github.com/DanielPan12/JobHuntBot)
- [Issues](https://github.com/DanielPan12/JobHuntBot/issues)
- [License: MIT](https://github.com/DanielPan12/JobHuntBot/blob/main/LICENSE)
- [README](https://github.com/DanielPan12/JobHuntBot/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/danielpan12-jobhuntbot