Skip to content
Back to search

autopilot-jobhunt

AI job agent: scans 130+ careers pages nightly, scores every role against your resume with an LLM (0–100), alerts you on Telegram, and drafts tailored cover letters + resumes. Free & open source.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tarunlnmiit--autopilot-jobhunt/badge.svg)](/listings/tarunlnmiit--autopilot-jobhunt)

HTML

<a href="/listings/tarunlnmiit--autopilot-jobhunt"><img src="/api/listings/tarunlnmiit--autopilot-jobhunt/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Option A — pip install

pip install autopilot-jobhunt        # or: pip install 'autopilot-jobhunt[mcp]' for Claude Code
mkdir my-job-hunt && cd my-job-hunt
autopilot init                       # creates config.json, companies.json, resume/, .env
# Fill in config.json (API keys + your profile) and resume/YOUR_RESUME.md, then:
autopilot scan

Option B — clone (recommended if you want to customize companies or contribute)

git clone https://github.com/tarunlnmiit/autopilot-jobhunt.git
cd autopilot-jobhunt
pip install -e '.'               # standalone CLI
# pip install -e '.[mcp]'       # + Claude Code MCP integration
cp config.example.json config.json && cp .env.example .env
# Fill in your API keys and candidate profile, then:
autopilot scan

**For the full walkthrough** — API key setup, Claude Code MCP registration, rate limit details, and troubleshooting — see **[SETUP.md](SETUP.md)**.

📚 Documentation

Step-by-step guides live in [`docs/`](docs/README.md):

| Guide | Covers | |---|---| | [Install](docs/01-install.md) | pip / from source / `autopilot init` scaffolding | | [LLM providers](docs/02-providers.md) | OpenRouter fallback chain, Claude CLI (keyless), Anthropic API | | [API keys](docs/03-api-keys.md) | TinyFish + OpenRouter keys, where each goes | | [Companies & scanning](docs/04-companies-and-scanning.md) | `companies.json`, discovery + scoring, scan pacing | | [Integrations](docs/05-integrations.md) | Telegram notifications | | [MCP server & Skill](docs/06-mcp-and-skill.md) | Drive the hunt from Claude Code | | [Config & scoring](docs/07-config-and-scoring.md) | Candidate profile, `min_score`, `top_n` | | [Troubleshooting](docs/08-troubleshooting.md) | Every error we've hit, and the fix | | [Testing checklist](docs/09-testing-checklist.md) | Reproducible independent verification |

API keys needed

| Service | Cost | Required | Where to get it | |---|---|---|---| | **TinyFish** | **Free** — no credit card | Always | [agent.tinyfish.ai](https://agent.tinyfish.ai) | | **OpenRouter** | **Free** — 4-model fallback chain | Unless using Claude CLI / Anthropic | [openrouter.ai](https://openrouter.ai) | | **Telegram** | Free | Optional | [@BotFather](https://t.me/BotFather) on Telegram |

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 368 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # autopilot-jobhunt
  2. <!-- mcp-name: io.github.tarunlnmiit/autopilot-jobhunt -->
  3. **Your AI job agent. Finds, scores, and drafts applications — while you sleep.**
  4. > Scans 130+ company careers pages nightly → scores every role against your resume with an LLM → sends you the top matches on Telegram → drafts a tailored resume + cover letter on demand.
  5. >
  6. > 🔒 **Drafts only — never applies.** You review every draft and submit applications yourself. See [PRIVACY.md](PRIVACY.md) for exactly what data leaves your machine.
  7. <p align="center">
  8. <img src="demo/autopilot-reel.gif?v=3" alt="autopilot-jobhunt demo — nightly scan, LLM scoring, Telegram alert, drafted application" width="300">
  9. </p>
  10. [![CI](https://github.com/tarunlnmiit/autopilot-jobhunt/actions/workflows/ci.yml/badge.svg)](https://github.com/tarunlnmiit/autopilot-jobhunt/actions/workflows/ci.yml)
  11. [![codecov](https://codecov.io/gh/tarunlnmiit/autopilot-jobhunt/branch/main/graph/badge.svg)](https://codecov.io/gh/tarunlnmiit/autopilot-jobhunt)
  12. [![PyPI version](https://img.shields.io/pypi/v/autopilot-jobhunt)](https://pypi.org/project/autopilot-jobhunt/)
  13. [![PyPI downloads](https://img.shields.io/pypi/dm/autopilot-jobhunt)](https://pypi.org/project/autopilot-jobhunt/)
  14. [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue)](https://www.python.org/)
  15. [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
  16. [![GitHub Stars](https://img.shields.io/github/stars/tarunlnmiit/autopilot-jobhunt?style=social)](https://github.com/tarunlnmiit/autopilot-jobhunt/stargazers)
  17. [![autopilot-jobhunt MCP server](https://glama.ai/mcp/servers/tarunlnmiit/autopilot-jobhunt/badges/score.svg)](https://glama.ai/mcp/servers/tarunlnmiit/autopilot-jobhunt)
  18. [![Listed on CodeGuilds](https://codeguilds.dev/badge/autopilot-jobhunt)](https://codeguilds.dev/packages/autopilot-jobhunt)
  19. [![MCPVault: claimed](https://mcpvault.io/badge/autopilot-jobhunt.svg)](https://mcpvault.io/servers/autopilot-jobhunt/health?utm_source=external_badge&utm_medium=referral&utm_campaign=mcp_health_report)
  20. **Seen by 90K+ people** — [the Instagram reel that launched it](https://www.instagram.com/p/DZhkDvoxtt2/).
  21. Published on [PyPI](https://pypi.org/project/autopilot-jobhunt/) and listed on the [Official MCP Registry](https://registry.modelcontextprotocol.io) (`io.github.tarunlnmiit/autopilot-jobhunt`), [Glama](https://glama.ai/mcp/servers/tarunlnmiit/autopilot-jobhunt) (Quality A), and [Smithery](https://smithery.ai/servers/tarungupta-y12/autopilot-jobhunt) (MCPB bundle).
  22. **[📖 Full setup guide with Claude Code MCP integration → SETUP.md](SETUP.md)**
  23. > ### ⭐ Star this repo if it helps you land a job
  24. > This tool is free, open source, and runs entirely on your machine — no subscription, no credit card. The only "payment" I ask: **if it surfaces a role you apply to (or land), drop a star.** It takes one click, costs you nothing, and it's the single thing that pushes the project in front of the next person grinding through 130 careers pages by hand. **[⭐ Star it here →](https://github.com/tarunlnmiit/autopilot-jobhunt/stargazers)**
  25. ---
  26. ## How it works
  27. ```mermaid
  28. flowchart LR
  29. A["🌐 130+ Careers Pages"] -->|TinyFish API| B["Job Discovery"]
  30. B --> C["LLM Batch Scorer\n(0–100 fit score)"]
  31. C -->|score ≥ min| D["📱 Telegram Alert\nTop N matches"]
  32. C -->|on demand| E["✉️ Cover Letter\n+ Resume Bullets"]
  33. C --> F["📊 CSV Export"]
  34. ```
  35. **The scoring prompt uses your actual resume** — not keywords. The LLM reads your full work history and the job description, then explains in one sentence why you fit or don't. No more guessing.
  36. ### What a scan result looks like
  37. ```
  38. Scanning Mistral AI...
  39. 3 new job URLs. Fetching details...
  40. Scoring jobs...
  41. Saved 2 jobs from Mistral AI
  42. Scanning HuggingFace...
  43. 5 new job URLs. Fetching details...
  44. Scoring jobs...
  45. Saved 3 jobs from HuggingFace
  46. Scanning Stripe...
  47. No new jobs found
  48. ...
  49. Scan complete.
  50. Top 5 sent to Telegram.
  51. ```
  52. ### What the Telegram notification looks like
  53. ```
  54. Job Hunt — 06 Jun 2026
  55. 5 matches found
  56. #1 | Mistral AI | Applied AI Engineer, ML Infrastructure
  57. 📍 Paris/London/Marseille, On-site
  58. 🔧 Python, LLMs, RAG, AWS, MLOps, DevOps
  59. ✅ Role combines applied AI + ML infrastructure in EU, aligns with MLOps/RAG expertise and relocation goal
  60. Score: 85/100 → https://jobs.lever.co/mistral/...
  61. #2 | HuggingFace | Staff ML Engineer
  62. 📍 Remote (EU)
  63. 🔧 Python, PyTorch, Transformers, CUDA, MLOps
  64. ✅ Open-source ML role matches deep learning and distributed training background
  65. Score: 80/100 → https://apply.workable.com/huggingface/...
  66. ...
  67. Reply "apply to #N" to draft a tailored application.
  68. ```
  69. ---
  70. ## What it does
  71. ```
  72. Every night at 2:30 AM:
  73. ┌─────────────────────────────────────────────────────────┐
  74. │ Scans careers pages → Scores with LLM → Notifies │
  75. │ (130+ cos) (0–100 fit) (Telegram) │
  76. └─────────────────────────────────────────────────────────┘
  77. On demand:
  78. autopilot draft 1 → tailored resume + cover letter in 60s
  79. ```
  80. ---
  81. ## Usage modes
  82. ```
  83. Mode 1: Standalone CLI (no Claude Code required)
  84. pip install autopilot-jobhunt
  85. autopilot scan / autopilot draft 1 / autopilot export
  86. Mode 2: Claude Code MCP (control via natural language)
  87. pip install 'autopilot-jobhunt[mcp]'
  88. claude mcp add autopilot-jobhunt ...
  89. → "Scan for ML jobs" / "Draft application for job #2"
  90. ```
  91. Both modes use the same config and produce the same output.
  92. ## Quick start
  93. ### Option A — pip install
  94. ```bash
  95. pip install autopilot-jobhunt # or: pip install 'autopilot-jobhunt[mcp]' for Claude Code
  96. mkdir my-job-hunt && cd my-job-hunt
  97. autopilot init # creates config.json, companies.json, resume/, .env
  98. # Fill in config.json (API keys + your profile) and resume/YOUR_RESUME.md, then:
  99. autopilot scan
  100. ```
  101. ### Option B — clone (recommended if you want to customize companies or contribute)
  102. ```bash
  103. git clone https://github.com/tarunlnmiit/autopilot-jobhunt.git
  104. cd autopilot-jobhunt
  105. pip install -e '.' # standalone CLI
  106. # pip install -e '.[mcp]' # + Claude Code MCP integration
  107. cp config.example.json config.json && cp .env.example .env
  108. # Fill in your API keys and candidate profile, then:
  109. autopilot scan
  110. ```
  111. **For the full walkthrough** — API key setup, Claude Code MCP registration, rate limit details, and troubleshooting — see **[SETUP.md](SETUP.md)**.
  112. ### 📚 Documentation
  113. Step-by-step guides live in [`docs/`](docs/README.md):
  114. | Guide | Covers |
  115. |---|---|
  116. | [Install](docs/01-install.md) | pip / from source / `autopilot init` scaffolding |
  117. | [LLM providers](docs/02-providers.md) | OpenRouter fallback chain, Claude CLI (keyless), Anthropic API |
  118. | [API keys](docs/03-api-keys.md) | TinyFish + OpenRouter keys, where each goes |
  119. | [Companies & scanning](docs/04-companies-and-scanning.md) | `companies.json`, discovery + scoring, scan pacing |
  120. | [Integrations](docs/05-integrations.md) | Telegram notifications |
  121. | [MCP server & Skill](docs/06-mcp-and-skill.md) | Drive the hunt from Claude Code |
  122. | [Config & scoring](docs/07-config-and-scoring.md) | Candidate profile, `min_score`, `top_n` |
  123. | [Troubleshooting](docs/08-troubleshooting.md) | Every error we've hit, and the fix |
  124. | [Testing checklist](docs/09-testing-checklist.md) | Reproducible independent verification |
  125. ### API keys needed
  126. | Service | Cost | Required | Where to get it |
  127. |---|---|---|---|
  128. | **TinyFish** | **Free** — no credit card | Always | [agent.tinyfish.ai](https://agent.tinyfish.ai) |
  129. | **OpenRouter** | **Free** — 4-model fallback chain | Unless using Claude CLI / Anthropic | [openrouter.ai](https://openrouter.ai) |
  130. | **Telegram** | Free | Optional | [@BotFather](https://t.me/BotFather) on Telegram |
  131. ---
  132. ## Claude Code / MCP integration
  133. Use autopilot-jobhunt as an MCP server inside **Claude Code** (CLI) or **Claude Desktop**.
  134. ### Step 1: Install with MCP support
  135. ```bash
  136. git clone https://github.com/tarunlnmiit/autopilot-jobhunt.git
  137. cd autopilot-jobhunt
  138. pip install -e '.[mcp]'
  139. ```
  140. ### Step 2: Register with Claude Code
  141. **Option A — one command:**
  142. ```bash
  143. claude mcp add autopilot-jobhunt \
  144. --env TINYFISH_API_KEY=your_key \
  145. --env OPENROUTER_API_KEY=your_key \
  146. --env TELEGRAM_TOKEN=your_token \
  147. --env TELEGRAM_CHAT_ID=your_chat_id \
  148. -- python -m job_hunt.mcp_server
  149. ```
  150. **Option B — edit `~/.claude.json` manually:**
  151. ```json
  152. {
  153. "mcpServers": {
  154. "autopilot-jobhunt": {
  155. "command": "python",
  156. "args": ["-m", "job_hunt.mcp_server"],
  157. "cwd": "/absolute/path/to/autopilot-jobhunt",
  158. "env": {
  159. "TINYFISH_API_KEY": "your_key",
  160. "OPENROUTER_API_KEY": "your_key",
  161. "TELEGRAM_TOKEN": "your_token",
  162. "TELEGRAM_CHAT_ID": "your_chat_id"
  163. }
  164. }
  165. }
  166. }
  167. ```
  168. > **Note:** `cwd` must point to the cloned repo — the server reads `config.json` and `companies.json` from there.
  169. ### Step 3: Use it
  170. In any Claude Code session:
  171. ```
  172. "Scan for ML jobs"
  173. "Draft an application for job #2"
  174. "Export jobs from the last 7 days with score above 70"
  175. ```
  176. ### Claude Desktop
  177. Same JSON block — add it under `mcpServers` in Claude Desktop → Settings → Developer.
  178. ---
  179. ## Customize your target companies
  180. Edit `companies.json`. Each entry needs:
  181. ```json
  182. {
  183. "name": "Stripe",
  184. "careers_url": "https://stripe.com/jobs",
  185. "search_domain": "stripe.com",
  186. "location": "Remote / San Francisco, CA",
  187. "region": "Remote"
  188. }
  189. ```
  190. The repo ships with 130+ pre-configured EU, NZ, and remote-friendly tech companies. Add or remove as you like.
  191. ---
  192. ## How scoring works
  193. The LLM reads your full resume + the full job description and assigns a score 0–100:
  194. | Score | Meaning |
  195. |---|---|
  196. | 80–100 | Near-perfect fit — apply immediately |
  197. | 60–79 | Good fit — worth applying |
  198. | 40–59 | Partial fit — apply if pipeline is thin |
  199. | < 40 | Poor fit — skipped |
  200. Set `min_score` in config to filter. Default: 60.
  201. ---
  202. ## Project structure
  203. ```
  204. autopilot-jobhunt/
  205. ├── job_hunt/
  206. │ ├── main.py # CLI entry point
  207. │ ├── scanner.py # Job discovery + LLM scoring
  208. │ ├── drafter.py # Resume tailoring + cover letter
  209. │ ├── notifier.py # Telegram notifications
  210. │ ├── llm_utils.py # OpenRouter wrapper with fallback
  211. │ ├── tools.py # Protocol-agnostic tool layer
  212. │ └── mcp_server.py # MCP server (Claude/AI assistant integration)
  213. ├── demo/ # Demo scripts for recording GIF
  214. ├── resume/ # Put your resume here (gitignored)
  215. ├── state/ # Scan state (gitignored)
  216. ├── output/ # Generated applications (gitignored)
  217. ├── companies.json # 130+ target companies
  218. ├── config.example.json # Config template (copy to config.json — gitignored)
  219. └── config.json # Your config (gitignored — never committed)
  220. ```
  221. ---
  222. ## LLM options
  223. ### Default: OpenRouter (free)
  224. Uses a 4-model fallback chain — all free, no credit card needed:
  225. | Model | Role |
  226. |---|---|
  227. | `meta-llama/llama-3.3-70b-instruct:free` | Primary — best quality |
  228. | `nvidia/nemotron-3-super-120b-a12b:free` | Fallback 1 — 120B |
  229. | `google/gemma-4-31b-it:free` | Fallback 2 |
  230. | `qwen/qwen3-coder:free` | Fallback 3 |
  231. If one model hits its daily free-tier quota, the tool automatically tries the next. **Zero LLM cost by default.**
  232. ### Alternative A: Claude Code CLI (no API key needed)
  233. If you have [Claude Code](https://claude.ai/code) installed and authenticated, you can use it as the LLM backend — no separate API key required:
  234. In `config.json`:
  235. ```json
  236. "llm_provider": "claude_cli"
  237. ```
  238. Or via environment variable: `LLM_PROVIDER=claude_cli autopilot scan`
  239. Optionally set a model: `"claude_cli_model": "sonnet"` (or `"opus"`, `"haiku"`, empty = Claude's default).
  240. > **Note:** Requires the `claude` binary in your PATH. Verify with `claude --print "hi"` first.
  241. > The MCP server and cron jobs must run in an environment where your `claude` auth session is active.
  242. >
  243. > **Rate-limit note:** Each call loads your global Claude Code context (~25–30k tokens). A nightly scan
  244. > (5–15 LLM calls) burns significantly against your subscription's 7-day rate limit. Prefer OpenRouter
  245. > for nightly automation; use Claude CLI for occasional on-demand drafts.
  246. ### Alternative B: Anthropic API
  247. If you have an Anthropic API key:
  248. ```bash
  249. pip install 'autopilot-jobhunt[claude]'
  250. ```
  251. In `config.json`:
  252. ```json
  253. "llm_provider": "anthropic",
  254. "anthropic_api_key": "sk-ant-...",
  255. "anthropic_model": "claude-haiku-4-5-20251001"
  256. ```
  257. `claude-haiku-4-5-20251001` is fast and cheap; `claude-sonnet-4-6` gives higher quality scores. A nightly scan uses ~5–15 LLM calls total (jobs scored in batches of 10).
  258. ---
  259. ## Contributing
  260. See [CONTRIBUTING.md](CONTRIBUTING.md). PRs welcome for:
  261. - Adding companies to `companies.json`
  262. - New ATS platform support (Rippling, Lever variants, Workday)
  263. - OpenAI / Gemini MCP adapters
  264. - Better scoring prompts
  265. ---
  266. ## License
  267. MIT — see [LICENSE](LICENSE).
  268. ---
  269. *Built by [@tarunlnmiit](https://github.com/tarunlnmiit). If this saved you hours of job searching, a ⭐ means a lot.*

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.