job-hunting-organizer
Builds a structured candidate profile from your GitHub repositories, including target roles, stack, and experience, using a configured GitHub token.
Fetches job descriptions from Indeed URLs to generate tailored cover letters, application answers, and track applications.
Supports local Ollama models as the LLM backend for private, on-device generation of cover letters, answers, and command parsing.
Uses OpenAI's API as the LLM backend for generating cover letters, tailoring answers, and parsing natural-language commands.
job-hunting-organizer
A local-first CLI and MCP server for running a job-hunting campaign.
What it does
Builds your profile from a CV (PDF / DOCX / Markdown) and your GitHub repos — including a structured list of target roles (level, domain, stack, comp floor, priority) you can refine.
Suggests the best-matching target role for every new job description, so the cover letter and Q&A know which version of "you" to emphasize.
Generates tailored cover letters from job-description URLs (Seek, LinkedIn, Indeed, others).
Tailors answers to application questions — given as text or as a screenshot.
Tracks every application in a structured folder per role, with the full interview pipeline.
After a failed interview, captures your weak topics and generates a personal learning plan for each, then aggregates recurring weak areas across applications.
Schedules interviews via an ICS file you can import into any calendar.
Related MCP server: vagas-mcp
Privacy
Your data stays local.
job-hunting-organizerreads your CV from a path you configure, fetches job descriptions from URLs you provide, and calls the LLM endpoint you configure. Nothing is sent to the tool author or to any third party. With a local model (Ollama, OpenCode, LM Studio) the LLM call stays on your machine. The tool has zero telemetry, zero analytics, and zero outbound calls except those you explicitly configure.
All user data lives outside the repo under two external directories. The config home (default ~/.job-hunting-organizer/, override with $JHO_CONFIG_HOME) holds the global config.json (LLM endpoint, GitHub token) and .locks/. The data root (default ~/job-hunting-organizer-data/, override with $JHO_DATA) holds campaigns/<name>/ and all per-campaign working data — each campaign has its own profile.md, applied/, and knowledge-base/. Nothing user-specific is committed to this repo. You can run multiple independent campaigns by creating more under campaigns/.
The data layout (folder-per-application, markdown + JSON, no DB) leaves room for an optional local web client in the future. The CLI and MCP server are the v1 surfaces; see docs/PLAN.md §20 for the forward-looking design notes.
Install
From npm (recommended)
npm install -g job-hunting-organizerThen run jho init to set up your first campaign.
From source
git clone https://github.com/koalyptus/job-hunting-organizer.git
cd job-hunting-organizer
npm install
npm run buildThe binaries are then available at ./bin/jho and ./bin/jho-mcp.
Build & test commands
npm run build # tsup → dist/
npm run typecheck # tsc --noEmit
npm run lint # eslint
npm run format:check # prettier
npm test # vitest (unit tests)
npm run test:integration # vitest (integration tests)
npm run eval # lightweight LLM eval suite (manual)Cross-platform notes
Runs unchanged on Linux, macOS, and Windows.
Linux / macOS:
./bin/jho --versionornpx jho --version.Windows: use
npx jho --version(orjho --versionafternpm install -g). Direct invocation of./bin/jhorequires Git Bash or WSL because Windows shells don't honor shebangs; the npm shim handles this transparently.All shell commands above work in PowerShell, cmd, bash, and zsh. No platform-specific flags.
CI runs the full check matrix on
ubuntu-latest,windows-latest, andmacos-latest(Node 20 + 22).
Quickstart
# 1. Initialize your campaign (wizard builds your profile from CV + GitHub,
# then reviews the suggested target roles with you)
jho init
# 2. Record an application from a job URL
# (suggests a target role from your profile; you confirm or override)
jho track https://au.seek.com.au/job/12345
> **Job ID extraction**: URLs are parsed for a job-board ID used in the folder slug. Built-in patterns support Seek, LinkedIn, Indeed, and a generic trailing-number fallback. Custom patterns can be added via the `JHO_URL_PATTERNS` environment variable — a JSON array of `{ name, pattern, group }` objects that are tried before the built-in patterns.
# 3. Generate a tailored cover letter
jho cover-letter 2026-Jun-03-SE-Nuage-Technology-Group-12345
# 4. Tailor an answer to an application question
jho answer 2026-Jun-03-SE-Nuage-Technology-Group-12345 "Why this company?"
# 5. Track interview stages
jho interview 2026-Jun-03-SE-Nuage-Technology-Group-12345 add \
--when "2026-06-10 10:00" --type hr --duration 30
# 5b. Before the interview: get a prep plan (tech stack, depth-tagged topics, timeline)
jho prepare 2026-Jun-03-SE-Nuage-Technology-Group-12345 --days 7
# ... write prepare.md to the app folder; append with --add
# 6. After a rejection: jot down weak topics, get a learning plan
jho retro 2026-Jun-03-SE-Nuage-Technology-Group-12345
# ... answer "what topics did you struggle with?" ...
# 7. See recurring weak topics across all interviews
jho retro aggregate
# 8. Get a snapshot of the campaign (counts, funnel, this-month delta)
jho stats
# 9. Read the log file (pretty-printed; log file is always JSON for tools)
jho logs --tail 50
jho logs --json | jq 'select(.level == 50)' # pipe to jq for filteringTip: you can omit the slug and just
cdinto the application folder —jho show,jho cover-letter,jho answer,jho interview ...,jho prepare,jho retro,jho retro show,jho retro appendall infer the slug from the current directory.cd ~/job-hunting-organizer-data/campaigns/default/applied/2026-Jun-03-SE-Nuage-Technology-Group-12345 jho show # same as passing the slug explicitly jho retro # works from any subfolder tooMultiple campaigns: each one lives at
<data-root>/campaigns/<name>/. Create them withjho init <name>(omit the name to use thedefaultcampaign). All commands accept--campaign <name>to target a specific one; otherwise the campaign is inferred from your cwd.jho init freelance jho --campaign freelance track https://au.seek.com.au/job/12345 jho --campaign ft-jobs statsRenaming a campaign: the folder name is the only thing that identifies a campaign — nothing on disk references it elsewhere, so
jho rename-campaign <old> <new>(or justjho rename-campaign <new>from inside the campaign folder) is enough. It validates the new name, takes a lock, and logs the move. You can also justmvthe folder directly; the tool will pick up the new name on the next call.
Natural language
Any command can also be invoked in plain English. If the first argument contains a space and isn't a known command, jho asks an LLM to map it to the equivalent command and re-runs the real implementation — no behaviour is reimplemented, so output is identical to the explicit form.
jho "list all applications for javascript-developer campaign"
jho "create cover letter for application-xyz"
jho "show retro for application-xyz"
jho "add interview for application-xyz tomorrow at 2pm"Global flags work too: jho --yes "list apps". Lower-confidence parses are echoed back for confirmation (unless --yes); very low confidence errors out with a rephrase hint. Natural-language parsing requires a configured LLM (same as the other LLM-backed commands).
As an MCP server
This package ships an MCP server via the jho-mcp binary.
Check your harness documentation for correct configuration, as an example:
GitHub Copilot (.vscode/mcp.json):
{
"servers": {
"jho-mcp": {
"type": "stdio",
"command": "node",
"args": ["bin/jho-mcp"],
"cwd": "C:\\path\\to\\job-hunting-organizer"
}
}
}Opencode (opencode.json):
{
"mcp": {
"jho-mcp": {
"type": "local",
"command": ["node", "bin/jho-mcp"],
"cwd": "path/to/job-hunting-organizer/bin/jho-mcp",
"enabled": true,
"timeout": 60000
}
}
}Local model tip: If you use a local LLM (Ollama, LM Studio, OpenCode), add
"timeout": 60000to the MCP server config. Local models can be slow on first load, and the default 5-second timeout may fire before the server responds toinitializeortools/list.
Note: MCP client configs are not standardized — each client uses its own schema and key names. To set a custom data location, add
"JHO_DATA": "/path/to/data"to theenvblock (Claude Desktop, Cursor, Copilot) orenvironmentblock (Opencode).
LLM configuration
jho uses the OpenAI API format for all LLM calls. Any OpenAI-compatible endpoint works:
Ollama —
http://localhost:11434/v1(free, private, on-device)LM Studio —
http://localhost:1234/v1(free, private, on-device)OpenAI —
https://api.openai.com/v1(cloud)Any OpenAI-compatible proxy (LiteLLM, OpenRouter, etc.)
Anthropic / Claude users: Anthropic native API uses a different format (
/v1/messagesinstead of/v1/chat/completions). To use Claude withjho, run LiteLLM as a local proxy:pip install litellm litellm --model anthropic/claude-3-5-sonnet-20241022 --api_base http://localhost:4000Then configure
jhowith baseUrlhttp://localhost:4000/v1and an empty API key.
During jho init, the tool automatically detects locally-installed Ollama and LM Studio instances (via the detect-local-agents package) and pre-fills the recommended LLM config. Run jho doctor --detect-agents at any time to see what's detected.
Environment variables
All env var names are uppercase. Prefix JHO_ denotes jho-internal config; prefix LLM_ overrides the corresponding field in config.json's llm block (only relevant when the LLM is called).
Variable | Description |
| Override the config home directory (default |
| Override the data root directory (default |
| Default campaign name when |
| JSON array of |
| Pre-fill the CV path during |
| Pre-fill the LinkedIn profile URL during |
| Override the log file path (default |
| Override the minimum log level written to file |
| Override the LLM endpoint base URL from |
| Override the API key from |
| Override the model from |
| Comma-separated |
| Set to disable ANSI colour output in terminal output |
Documentation
docs/PLAN.md— full design plandocs/ROADMAP.md— phased build plan with statusAGENTS.md— for AI agents using the MCP server
License
Available Tools
37 toolsadd_interviewC
Add a new interview entry for an application
Inputs: slug (required), when (required), campaign (required), type, +4 more.
aggregate_retrosC
Aggregate weak topics across all application retro files for a campaign
Inputs: campaign (required), targetRole, includeAbandoned.
answer_questionB
Answer a question for an application and append it to qa.md
Inputs: slug (required), campaign (required), question (required), steer, +2 more.
append_retroC
Append additional weak topics and notes to an existing retro
Inputs: slug (required), campaign (required), notes, steer, +3 more.
cover_letterC
Generate a tailored cover letter for an application
Inputs: slug (required), campaign (required), steer, noSave.
doctorA
Diagnose campaign or application issues (missing files, invalid frontmatter, toolhash mismatches)
Inputs: campaign (required), slug.
extract_jdC
Extract structured job description from a URL or raw text
Inputs: campaign (required), url, text.
get_campaignC
Get campaign configuration (secrets redacted)
Inputs: campaign (required).
get_rootB
Resolve the campaign root directory path
Inputs: campaign (required).
get_statsA
Compute campaign statistics: counts by status, role, site, employment type, funnel, interview entries, and this-month delta
Inputs: campaign (required), since, targetRole, employmentType.
initB
Initialize a new campaign with optional CV, GitHub, and LinkedIn. Pass llm to set the global LLM endpoint (baseUrl/apiKey/model), shared across all campaigns.
Inputs: llm, cvPath, campaign, githubUser, +1 more.
kb_addB
Copy knowledge-base docs (PDF, DOCX, MD, TXT) into the campaign
Inputs: paths (required), campaign (required).
kb_updateC
Re-sync the knowledge base from sources recorded at init
Inputs: campaign (required).
list_applicationsC
List applications with optional status, tags, role, employment type, and text filters
Inputs: campaign (required), tags, filter, status, +2 more.
list_campaignsB
List all campaigns under the data root
Inputs: no named parameters.
list_interviewsB
List all interviews for an application
Inputs: slug (required), campaign (required).
mark_interviewC
Change the status of an existing interview
Inputs: slug (required), index (required), status (required), campaign (required), +1 more.
ownershipA
Show file ownership rules (which files the tool writes, which you can edit). Returns a human-readable markdown table, not JSON.
Inputs: no named parameters.
post_mortemC
Generate a post-mortem learning plan for an application
Inputs: slug (required), campaign (required), notes, steer, +2 more.
prepareA
Generate or add topics to a pre-interview prep plan. Provide topics to append to an existing plan (steer/days ignored in this mode).
Inputs: slug (required), campaign (required), days, steer, +1 more.
read_campaign_configB
Read campaign configuration (redacted)
Inputs: campaign (required).
read_configA
Read global configuration (secrets redacted)
Inputs: no named parameters.
read_cover_letterB
Read an existing saved cover letter for an application
Inputs: slug (required), campaign (required).
read_logsB
Read the log file with optional filtering (tail, level, JSON format)
Inputs: json, tail, level.
read_prepC
Read an existing pre-interview prep plan for an application
Inputs: slug (required), campaign (required).
read_profileB
Read the candidate profile for a campaign
Inputs: campaign (required).
read_qaC
Read existing Q&A entries for an application
Inputs: slug (required), campaign (required).
read_retroC
Read an existing retro/learning plan for an application
Inputs: slug (required), campaign (required).
remove_applicationB
Permanently remove an application folder — cleans metadata, index, and sidecars
Inputs: slug (required), campaign (required), confirm.
remove_campaignB
Permanently remove a campaign folder — destructive, cannot be undone
Inputs: campaign (required), confirm.
rename_applicationC
Rename an application folder
Inputs: to (required), from (required), campaign (required).
rename_campaignC
Rename a campaign folder
Inputs: to (required), from (required).
repairC
Repair application toolhash sidecars, rebuild index and counters
Inputs: campaign (required), slug.
show_applicationB
Show a single application: metadata (meta.md) and job description (jd.md)
Inputs: slug (required), campaign (required).
track_applicationB
Track a job application — create from URL or update by slug
Inputs: campaign (required), url, note, slug, +7 more.
update_configC
Update global configuration settings
Inputs: patch (required).
update_profileB
Overwrite the campaign profile.md with new markdown content
Inputs: content (required), campaign (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 37 tools
Most tools target distinct resources and actions, but a few pairs overlap significantly: get_campaign and read_campaign_config both appear to read campaign configuration, and track_application's update mode can be confused with update_profile. Descriptions help clarify most boundaries, but the large surface still creates some ambiguity.
Naming is mostly snake_case and readable, but conventions are mixed: retrieval uses get_, read_, and show_ inconsistently (get_campaign vs read_campaign_config, show_application vs read_profile), and several tools use bare nouns or verbs (ownership, doctor, repair, prepare, init).
37 tools is excessive for a job-hunting organizer, far beyond the well-scoped 3–15 range. Many tools are granular read/generate pairs, and the count suggests feature sprawl rather than a tightly scoped interface.
The surface covers a wide lifecycle: campaigns, applications, profiles, interviews, prep, retros, cover letters, Q&A, stats, knowledge base, config, logs, and diagnostics. Minor gaps exist (e.g., no interview deletion or explicit campaign config update), but core workflows are well supported.
Maintenance
Related MCP Connectors
Job search management: applications, interviews, offers, recruiter email, and company openings.
Search jobs, prepare resumes and cover letters, retrieve PDFs, and track your applications.
Track job applications: find the ones to follow up on, add jobs, update status, notes and steps.
Your own job search in any AI: next steps, matches, résumés, applications, reminders. Free.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables tracking job applications through a pipeline, scheduling follow-ups, and summarizing job search progress via natural language.7-
- AlicenseAqualityCmaintenanceEnables Claude to organize a job search by registering openings, advancing applications through a status funnel, measuring conversion rates between stages, and flagging applications that have gone quiet and need follow-up. Data is kept locally in SQLite, so no external account or server is required.5MIT
- AlicenseNot gradedqualityBmaintenanceEnables an AI agent to research industries and companies, track job postings and deadlines from recruiting sites and spreadsheets, match roles against a personal profile, manage application stages, and fill in application forms up to but not including submission. All data stays in a local folder on the user's machine, with reversible actions and confirmation cards for consequential steps.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables job seekers to structure job descriptions, search a personal Markdown profile with hybrid BM25/dense retrieval, and compare a posting against that profile to see which requirements are supported, weak, or missing evidence. It also tracks applications and follow-up deadlines through JSON-backed tools whose writes stay as previews until a human turn confirms them.1MIT