Skip to main content
Glama

job-hunting-organizer

A local-first CLI and MCP server for running a job-hunting campaign.

What it does

  1. 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.

  2. 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.

  3. Generates tailored cover letters from job-description URLs (Seek, LinkedIn, Indeed, others).

  4. Tailors answers to application questions — given as text or as a screenshot.

  5. Tracks every application in a structured folder per role, with the full interview pipeline.

  6. After a failed interview, captures your weak topics and generates a personal learning plan for each, then aggregates recurring weak areas across applications.

  7. Schedules interviews via an ICS file you can import into any calendar.

Related MCP server: vagas-mcp

Privacy

Your data stays local. job-hunting-organizer reads 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

npm install -g job-hunting-organizer

Then 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 build

The 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 --version or npx jho --version.

  • Windows: use npx jho --version (or jho --version after npm install -g). Direct invocation of ./bin/jho requires 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, and macos-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 filtering

Tip: you can omit the slug and just cd into the application folder — jho show, jho cover-letter, jho answer, jho interview ..., jho prepare, jho retro, jho retro show, jho retro append all 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 too

Multiple campaigns: each one lives at <data-root>/campaigns/<name>/. Create them with jho init <name> (omit the name to use the default campaign). 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 stats

Renaming 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 just jho 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 just mv the 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": 60000 to the MCP server config. Local models can be slow on first load, and the default 5-second timeout may fire before the server responds to initialize or tools/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 the env block (Claude Desktop, Cursor, Copilot) or environment block (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/messages instead of /v1/chat/completions). To use Claude with jho, run LiteLLM as a local proxy:

pip install litellm
litellm --model anthropic/claude-3-5-sonnet-20241022 --api_base http://localhost:4000

Then configure jho with baseUrl http://localhost:4000/v1 and 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

JHO_CONFIG_HOME

Override the config home directory (default ~/.job-hunting-organizer/)

JHO_DATA

Override the data root directory (default ~/job-hunting-organizer-data/)

JHO_DEFAULT_CAMPAIGN

Default campaign name when --campaign is omitted (default default)

JHO_URL_PATTERNS

JSON array of { name, pattern, group } URL-pattern objects used to extract job IDs from job ad URLs; tried before the built-in Seek/LinkedIn/Indeed patterns

JHO_CV_PATH

Pre-fill the CV path during jho init

JHO_LINKEDIN_URL

Pre-fill the LinkedIn profile URL during jho init

JHO_LOG_FILE

Override the log file path (default <config-home>/jho.log); set to any falsy value via logging.disableFileLogging in config.json to suppress file logging

JHO_LOG_LEVEL

Override the minimum log level written to file

LLM_BASE_URL

Override the LLM endpoint base URL from config.json

LLM_API_KEY

Override the API key from config.json

LLM_MODEL

Override the model from config.json

LLM_TAGS

Comma-separated key=value tags sent on every LLM call (e.g. user=jho). Some providers (notably Nous Research's inference gateway) require a user=<value> tag or return 400 missing tags. jho ships with a default user=jho tag so this is handled automatically for Nous; override it here if you need a different value.

NO_COLOR

Set to disable ANSI colour output in terminal output

Documentation

License

MIT

Available Tools

37 tools
add_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

    B3/5.0

    Scored across 37 tools

    Disambiguation3/5

    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 Consistency3/5

    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).

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessUsually handled

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      Enables tracking job applications through a pipeline, scheduling follow-ups, and summarizing job search progress via natural language.
      7
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      5
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      1
      MIT