Jobtrack

jobtrack

[](https://github.com/james5101/jobtrack/actions/workflows/test.yml)

Local-first CLI + MCP server for tracking job applications. A flight recorder, not a filing cabinet.

Install (dev)

uv sync
uv pip install -e ".[dev]"

Quickstart

# Paste-driven (most reliable for modern job boards)
jobtrack add --company Valon --role "Platform Engineer" \
    --resume ~/resumes/platform.pdf --jd-paste

# Or attach a saved JD file, with a cover letter and tags
jobtrack add --company Stripe --role SRE \
    --resume ~/resumes/sre.pdf --jd-file ~/jds/stripe-sre.md \
    --cover ~/covers/stripe.md --tag payments --tag fintech

jobtrack list
jobtrack list --status interviewing
jobtrack show valon                 # by company
jobtrack show 2026-05-10_valon_...  # by full ID
jobtrack open valon                 # opens snapshot dir in OS file browser

jobtrack status  screening
jobtrack note  "recruiter asked about k8s depth"
jobtrack tag  +fintech -ghosted

Status pipeline

Seven values, one enum, no enforced transitions:

applied → screening → interviewing → offer
                                   ↘ rejected
                                   ↘ ghosted
                                   ↘ withdrawn

applied is set automatically. The rest are moved with jobtrack status (CLI) or update_status (MCP). Every change appends to status_history — nothing is overwritten.

Snapshot layout

Each application is a directory under /applications/:

2026-05-10_valon_platform-engineer_a3f1/
├── meta.json
├── resume.pdf            # exact bytes sent, with sha256 in meta.json
├── resume.txt            # extracted on add — the search sidecar
├── job-description.md
└── cover-letter.md       # if provided

ID format: YYYY-MM-DD___. The 4-hex suffix is sha256(applied_at)[:4] so IDs stay unique even if you apply to the same role twice in a day.

Where data lives

• Windows: %LOCALAPPDATA%\jobtrack
• macOS: ~/Library/Application Support/jobtrack
• Linux: ~/.local/share/jobtrack

Override with JOBTRACK_HOME=/path/to/dir.

Demo

Build a throwaway store with five sample applications run through every status:

bash scripts/demo-pipeline.sh /tmp/jobtrack-demo
JOBTRACK_HOME=/tmp/jobtrack-demo jobtrack list

Useful for verifying an install or showing someone what the tool does without polluting your real data store.

Tests

uv run pytest

MCP server

jobtrack-mcp is a FastMCP server exposing five read tools and three write tools:

Read:

• list_applications(status?, tag?, since?, limit?) — summaries
• get_application(query) — full meta + resume text + JD + cover letter
• find_application_by_company(company) — all summaries matching a company name (substring)
• search_applications(query) — substring search across all snapshot files and notes
• get_recent(n=5) — the N most recent with full content

Write:

• update_status(query, status) — append-only status change
• add_note(query, note) — append a note
• edit_tags(query, add?, remove?) — tag arithmetic

Writes require an exact ID or a uniquely-resolving company name; ambiguous queries return candidate IDs instead of silently writing to the wrong record. Creating new applications stays CLI-only (you have files on disk when you apply).

Claude Desktop

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "jobtrack": {
      "command": "D:\\code\\application-tracker\\.venv\\Scripts\\jobtrack-mcp.exe"
    }
  }
}

If you keep your data outside the default location, add an env block — otherwise the MCP server reads the wrong store and will report no results:

{
  "mcpServers": {
    "jobtrack": {
      "command": "D:\\code\\application-tracker\\.venv\\Scripts\\jobtrack-mcp.exe",
      "env": {
        "JOBTRACK_HOME": "D:\\jobtrack-data"
      }
    }
  }
}

Restart Claude Desktop. Try: "What did I send to Valon?"

Claude Code

claude mcp add jobtrack -- uv --directory D:\code\application-tracker run jobtrack-mcp

To pass JOBTRACK_HOME, use --env:

claude mcp add jobtrack --env JOBTRACK_HOME=D:\jobtrack-data -- `
    uv --directory D:\code\application-tracker run jobtrack-mcp

Or edit .mcp.json in the project directly:

{
  "mcpServers": {
    "jobtrack": {
      "command": "uv",
      "args": ["--directory", "D:\\code\\application-tracker", "run", "jobtrack-mcp"],
      "env": {
        "JOBTRACK_HOME": "D:\\jobtrack-data"
      }
    }
  }
}

The MCP server resolves JOBTRACK_HOME exactly like the CLI: env var if set, otherwise the platform default from "Where data lives" above. The two must agree, or the CLI and MCP will see different stores.

Skills (Claude Code)

The repo ships Claude Code skills under .claude/skills/. They load automatically when you run Claude Code in this directory.

Development skills — keep extensions consistent with the project's patterns:

• add-mcp-tool — add a read/write tool to the FastMCP server
• add-cli-command — add a jobtrack subcommand
• add-application-field — add a field to the ApplicationMeta schema (covers backwards-compat with existing snapshots)

Workflow skills:

• smart-job-search — find new openings across employers' career boards, dedupe against what's already tracked (via the MCP read tools), rank by résumé fit, and write per-company files plus a ranked shortlist to a (gitignored) jobs/ folder. The intelligence runs in your Claude session; jobtrack supplies the data. Reading JS career boards uses a browser tool — Claude in Chrome for logged-in/interactive sources (e.g. LinkedIn), or headless Playwright for public boards and unattended runs. A PreToolUse hook in .claude/settings.json keeps a run bounded (no exhaustive crawling, API reverse-engineering, or scratch dumps in the repo); review or disable it via /hooks.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: james5101
• Source: james5101/jobtrack
• License: MIT

Install and usage instructions live in the source repository linked above.