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   # or: pip install jobpilot-ai — installs the pipeline + web UI
jobpilot setup                            # configure data dir + secrets (cross-platform)
jobpilot serve                            # optional local web UI → http://127.0.0.1:8787

Or run jobpilot start instead of setup + serve separately — it runs setup only if not already configured, asks for schedule slots (24h HH:MM, one at a time), then launches serve and opens the web UI in your browser. Safe to re-run: it skips the wizard on an already-configured install unless you pass --reconfigure.

macOS: brew install ashlesh-t/tap/jobpilot · Windows: scoop bucket add ashlesh-t https://github.com/ashlesh-t/scoop-bucket && scoop install jobpilot · Arch (AUR): pending — new AUR account registrations are temporarily disabled (details); the PKGBUILD is ready in packaging/aur/ and will be pushed once registration reopens. All are thin wrappers over the same PyPI package (see packaging/).

Note: jobpilot start (and setup) only bootstrap the Python backend — they cannot run step (a) for you. /plugin install jobpilot@jobpilot happens inside Claude Code, not the shell, so it stays a separate, one-time, manual step regardless of which backend install path you use.

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.

The same health check is available from the CLI, without the web UI:

jobpilot doctor              # full engines/notifiers/sources table
jobpilot doctor --live       # also runs each native scraper with a tiny cap
jobpilot view Apify          # just the one row (name, or unique substring), e.g. Apify/Discord
jobpilot view Apify --live   # same, with the live probe where applicable

• 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

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.