Metadata-Version: 2.4
Name: jobpilot-ai
Version: 1.6.1
Summary: Automated job-hunt pipeline for Claude Code: scrape → score → tailor → notify, with an optional local web UI + scheduler.
Project-URL: Homepage, https://github.com/ashlesh-t/jobpilot
Project-URL: Repository, https://github.com/ashlesh-t/jobpilot
Author-email: ashlesh-t <ashleshat5@gmail.com>
License: MIT
License-File: LICENSE
Keywords: automation,claude,job-search,jobs,resume,scraping,telegram
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Requires-Dist: apify-client>=1.8
Requires-Dist: confusable-homoglyphs>=3.0
Requires-Dist: httpx>=0.27
Requires-Dist: keyring>=25.0
Requires-Dist: openpyxl>=3.1
Requires-Dist: pypdf2>=3.0
Requires-Dist: python-docx>=1.1
Requires-Dist: python-dotenv>=1.0
Requires-Dist: python-whois>=0.9
Requires-Dist: requests>=2.31
Requires-Dist: telethon>=1.36
Requires-Dist: tldextract>=5.1
Requires-Dist: urlextract>=1.9
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: server
Requires-Dist: apscheduler>=3.10; extra == 'server'
Requires-Dist: claude-agent-sdk>=0.1; extra == 'server'
Requires-Dist: fastapi>=0.110; extra == 'server'
Requires-Dist: sse-starlette>=2.0; extra == 'server'
Requires-Dist: uvicorn[standard]>=0.27; extra == 'server'
Provides-Extra: tray
Requires-Dist: pillow>=10.0; extra == 'tray'
Requires-Dist: pystray>=0.19; extra == 'tray'
Description-Content-Type: text/markdown

# JobPilot

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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](https://t.me/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](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**
```bash
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)**
```bash
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).

```bash
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.
