jobpilot-ai 1.6.1

Automated job-hunt pipeline for Claude Code: scrape → score → tailor → notify, with an optional local web UI + scheduler.

JobPilot

Automated, personal job-hunting pipeline for Claude Code.

1. What it does

JobPilot scrapes roughly a dozen job sources (LinkedIn, Indeed, Glassdoor, Google Jobs, Naukri, Internshala, Wellfound, plus Hacker News "Who is hiring", YC, and Telegram job channels) through Apify and free native scrapers, then scores every posting against your resume. The strongest matches get a tailored resume and land in a dated, styled XLSX report. A digest of the top picks — with the report and resumes attached — is pushed to Telegram (or Discord) automatically on whatever schedule you set. You can drive it from a chat, or run it headless on a schedule via the local control service (§5a).

2. Prerequisites

• Claude Desktop Pro (the scheduled task runs under your Pro subscription).
• Apify account — free tier is fine (~$5 credit/month).
• Telegram bot — create one with @BotFather and grab your chat ID.
• Python 3.11+.
• tectonic (optional) — only needed to compile LaTeX resumes to PDF.

New here? Follow GETTING_STARTED.md for a full step-by-step walkthrough — how to get your Apify token, create a Telegram bot, find your chat ID, fill in .env, and verify each piece before scheduling.

3. Install

JobPilot is two pieces: the Claude Code skills (/job-search, /job-setup, …) and a Python backend (pipeline scripts + optional web UI). Pick the path that fits — all are cross-platform (Linux / macOS / Windows).

a. Claude Code plugin (recommended for the skills)

/plugin marketplace add ashlesh-t/jobpilot
/plugin install jobpilot@jobpilot

This registers the skills in Claude Code on any OS. Then install the Python backend once with either (b) or (c) below so the scripts have their dependencies.

b. pipx — the backend + web UI, one command on every OS

pipx install "jobpilot-ai[server]"   # or: pip install "jobpilot-ai[server]"
jobpilot setup                            # configure data dir + secrets (cross-platform)
jobpilot serve                            # optional local web UI → http://127.0.0.1:8787

On Arch: yay -S jobpilot-ai · macOS: brew install ashlesh-t/tap/jobpilot · Windows: scoop install jobpilot — all thin wrappers over the same package (see packaging/).

c. From source (contributors)

git clone https://github.com/ashlesh-t/jobpilot ~/projects/jobpilot
cd ~/projects/jobpilot
./setup.sh                       # Linux/macOS
python scripts/jobpilot_setup.py # Windows (or any OS — identical, no bash needed)

4. One-time setup

a. Configure JobPilot — jobpilot setup (or ./setup.sh / python scripts/jobpilot_setup.py) creates ~/.claude/job-hunt-ai/, initialises the SQLite cache (via Python's stdlib, so no sqlite3 CLI is needed on Windows), and runs an interactive wizard that collects your Apify token, Telegram bot token, and chat ID (validates each live before saving).

b. Connect Google Drive in Claude Desktop → Settings → Connections.

c. Create a folder named jobpilot-resume in your Google Drive and upload your resume as a PDF file into it.

d. Run /job-setup in Claude Desktop. It checks that secrets and Google Drive are ready, lets you pick your resume PDF from the Drive folder (shows a numbered list if there are several), downloads and parses it, then asks for your job preferences (locations, CTC floor, role types, experience, degree, optional tech stack).

Everything personal — secrets, preferences, cached resume, reports — lives in ~/.claude/job-hunt-ai/, never in the repo. The resume source of truth stays in Google Drive.

5. Daily use

Once the scheduled task is set up, you do nothing. It fires on your cadence, runs the full pipeline, and pushes results to your notify channel. Just check Telegram (or Discord) for the digest, the attached XLSX report, and any tailored resumes.

5a. Local control service + UI (optional)

Instead of a chat, you can run JobPilot as a small local web app that schedules runs, lets you pick an execution engine, wires up Discord/Telegram in the browser, and shows a live, harness-style view of each run (stages lighting up, per-source counts, the final digest).

pip install -r requirements-server.txt   # fastapi/uvicorn/apscheduler/… (separate from core)
python -m server                         # → http://127.0.0.1:8787

• Engine choice (Setup tab). Claude Code runs the pipeline under your Pro/Max subscription (no per-token cost, needs the claude CLI logged in). Anthropic API runs it metered via the Claude Agent SDK (ANTHROPIC_API_KEY). Gemini/Antigravity is interface-ready for a future release. The UI greys out any engine that isn't usable yet and tells you why.
• Schedule tab. Add/remove IST time slots; the service fires /job-search at each and the skill alternates full ⇄ native to stretch Apify credit. python -m server install-service writes a systemd/launchd unit so it survives reboot.
• Connections tab. Telegram sign-in is a phone → OTP form (no terminal); Discord is a webhook paste + test. A ✅/⚠️/❌ health check tells you which sources are live.
• Delivery is pluggable: set notify_channels (e.g. ["telegram","discord"]) in preferences or the UI.

The service only drives the existing pipeline — all scoring/tailoring logic still lives in skills/job-search/SKILL.md, the single source of truth for every engine.

6. Slash command reference

Command	What it does	When to use
/job-setup	Collect preferences + parse resume into a profile	Once, at first install, or to change criteria
/job-search	Full pipeline: scrape -> dedupe -> filter -> score -> research -> report -> tailor -> notify	Manually, or via scheduled task
/job-tailor <job_id|URL|JD>	Tailor resume to one job; ATS score before vs after	When you want to apply to a specific role
/jobpilot-clear	Wipe seen-job cache, score cache, and reports (keeps prefs + resume)	To reset history and re-surface old jobs

7. Resume versioning

Keep your master resume as ~/.claude/job-hunt-ai/resumes/base.tex (LaTeX) or base.docx. JobPilot reads from it and writes tailored copies into resumes/tailored/. Use git as your version control for the base resume — commit changes there and JobPilot will re-parse when the file hash changes.

8. Editing preferences

Either hand-edit ~/.claude/job-hunt-ai/options/preferences.json, or just ask Claude in natural language (e.g. "raise my CTC floor to 18 LPA and add Remote") and it will update the file for you.

9. Cost

Layer A (scraping + filtering) costs nothing in LLM tokens — it is pure Python. The only spend is Apify usage; the free tier (~$5 credit/month) covers roughly one run per day. Tune schedule_slots_ist to a single daily slot to stay free. LLM usage in Layer B is covered by your Claude Pro subscription.

10. Contributing / marketplace listing

PRs welcome. To list in a Claude plugin marketplace, publish this repo publicly and share the claude plugin install github:ashlesh-t/jobpilot one-liner. A .mcpb bundle and pip-installable helper package are on the roadmap.