🧭 Job-Pilot

Your personal, AI-powered job hunter & application co-pilot.

Five tools in one clean, self-hosted dashboard: search remote jobs across multiple boards, track your pipeline, get instant AI salary & company intel, auto-draft your application kit, score your résumé against a job, rehearse the interview, and coach your salary negotiation.

---

👀 Preview

Home — tools + live pipeline stats	Job Search — master-detail, ranked by match
Application Tracker — Saved → Offer pipeline	Resume Analyzer — ATS score & keyword gaps
Interview Prep — questions + STAR answers	Salary Coach — market range & counter-script

---

🧰 The tools

Tool	What it does	Needs AI?
🔍 Job Search	Search 5+ free boards at once, ranked by a keyword match score. AI company/salary intel + auto-drafted email, cover letter & CV prompt.	for intel/drafts
📋 Application Tracker	Save jobs and move them through Saved → Applied → Interview → Offer → Rejected, with notes. Persists to local JSON.	no
📄 Resume Analyzer	Paste your CV against a job → ATS match score, matched vs missing keywords, concrete rewrite suggestions, and a stronger tailored summary.	yes
🎤 Interview Prep	Generate the questions you'll likely face — what each really assesses, plus STAR-format model answers tailored to you.	yes
💰 Salary Coach	A realistic market range, an assessment of your offer, a ready-to-send counter-offer script, and negotiation tips.	yes

---

✨ Features

• 🔎 Multi-board search — pulls from 5 free job APIs at once, remote-first with a Remote | Any toggle.
• ⭐ Instant match score — every card shows how well it fits your skills (keyword overlap, zero AI cost).
• 🧠 AI company & salary intel — one click gives you a company brief, reputation summary, fit score, recommended salary (real or AI-estimated), and the best way to apply.
• 🔗 Deep research links — jump straight to the company's Glassdoor, Levels.fyi, Blind, and LinkedIn pages.
• ✉️ One-click application kit — tailored outreach email, cover letter, and a CV-tailoring prompt, each editable with copy + mailto:.
• 📋 Local pipeline tracker — save any job and track it to offer; notes and status live in applications.json.
• 🔌 Provider-agnostic AI — works with any OpenAI-compatible endpoint: OmniRoute, Groq, OpenRouter, OpenAI, or local Ollama. Built-in model picker + connection tester.
• 🎛️ Clean multi-page UI — one shared theme across five tools. No database, no build step, no accounts, no telemetry.

---

🛠 How it works

flowchart LR
    U([You]) -->|title · skills · Remote/Any| S[Search form]
    S --> J["jobs.search_jobs()"]
    J --> R[Remotive]
    J --> RO[RemoteOK]
    J --> AB[Arbeitnow]
    J --> JC[Jobicy]
    J --> TM[The Muse]
    J -. optional key .-> AD[Adzuna]
    J -. optional key .-> JS[JSearch]
    R & RO & AB & JC & TM --> N[Normalize · de-dupe · match score]
    N --> C[[Job cards]]
    C -->|Select| D[Detail panel]
    D -->|Analyze| E["ai.enrich()"]
    D -->|Generate| G["ai.generate()"]
    E & G --> AI{{Any OpenAI-compatible endpoint}}
    AI --> OMNI[OmniRoute / Groq / OpenAI / Ollama]

Loading

The job boards find the jobs; the AI enriches them (salary, company, fit, drafts). The LLM never scrapes — it only reasons over what the APIs return.

Tech stack: Python · Streamlit · requests · openai SDK · python-dotenv. No database — results live in session state, your profile saves to a local profile.json.

---

🚀 Quick start

# 1. Clone
git clone https://github.com/hassanannajjar/Job-Pilot.git
cd Job-Pilot

# 2. Create a virtual env + install
python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# 3. (Optional) configure AI + keys
cp .env.example .env               # edit AI_BASE_URL / AI_API_KEY / AI_MODEL

# 4. Run
streamlit run Home.py

Open the URL Streamlit prints (default http://localhost:8501). Search & the tracker work with zero config — you only need an AI provider for the intel, résumé, interview, salary & drafting features (set it live in the sidebar).

Run the offline self-checks and the line-cap gate anytime (same as CI):

python scripts/check_lines.py     # → "✓ every source file is ≤ 150 lines"
python -m scripts.selftest_all    # → "✓ all self-checks passed"

---

🔗 Connect an AI provider

Pick a preset in the sidebar, paste a key, and go. Any OpenAI-compatible endpoint works.

Preset	Base URL	Example model	Key needed?
OmniRoute	http://localhost:20128/v1	auto/best-free	Local key (see below)
Groq (free)	https://api.groq.com/openai/v1	llama-3.3-70b-versatile	Free — console.groq.com
OpenRouter	https://openrouter.ai/api/v1	openai/gpt-4o-mini	openrouter.ai/keys
OpenAI	https://api.openai.com/v1	gpt-4o-mini	Paid — platform.openai.com
Ollama (local)	http://localhost:11434/v1	llama3.1	None (runs on your machine)

💡 New to this? Groq is the fastest free path (sign up, paste key, done). Ollama runs fully offline.

---

🔌 Using OmniRoute

OmniRoute is a local, open-source AI gateway — one OpenAI-compatible endpoint (http://localhost:20128/v1) that routes across 290+ providers with free-tier fallback. Job-Pilot connects to it like any other provider.

📖 Full step-by-step guide: docs/omniroute.md.

The OmniRoute (local) preset is selected by default, so the sidebar already points at http://localhost:20128/v1 with model auto/best-free — you just paste your key and load models.

Setup:

1. Install & run OmniRoute — its dashboard opens at http://localhost:20128.
2. Providers → connect at least one (e.g. Kimi, DeepSeek, Gemini). The Provider Topology must show ≥ 1 active — a router with 0 active providers can't answer.
3. API Keys → Create a key.
4. In Job-Pilot's sidebar: choose the OmniRoute (local) preset → paste your key → click 🔄 Load models → pick a model → click 🧪 Test connection (should show ✅ + the model name).

sequenceDiagram
    participant JP as Job-Pilot
    participant OR as OmniRoute (:20128)
    participant P as Provider (DeepSeek / Kimi / …)
    JP->>OR: POST /v1/chat/completions (model = auto/best-free)
    OR->>P: routes to a healthy provider
    P-->>OR: completion
    OR-->>JP: OpenAI-shaped response

Loading

⚠️ Pick the right model (important!)

OmniRoute exposes namespaced model routes — there is no bare auto. Sending auto (or auto/best-chat) can fall through to a weak provider (e.g. felo-chat) that returns garbage like .com.

Use these ✅	Avoid these ❌
auto/best-free, auto/smart (route to DeepSeek)	bare auto, auto/best-chat (→ felo-chat junk)

Use 🔄 Load models to see everything your OmniRoute exposes, and 🧪 Test connection to confirm a model actually replies before you rely on it. If output ever comes back as a fragment, Job-Pilot detects it and tells you to switch models. Note: some providers may return errors independent of Job-Pilot (e.g. Kimi 402 if its quota/billing is unset, occasional 502s) — just pick another working route.

---

💼 Job sources

Source	Coverage	Salary data	Key required
Remotive	Remote (tech + non-tech)	sometimes	❌ none
RemoteOK	Remote (tech)	sometimes	❌ none
Arbeitnow	EU + remote	rarely	❌ none
Jobicy	Remote	often	❌ none
The Muse	Global (many on-site)	rarely	❌ none
Adzuna	Broad incl. non-remote	✅ real	ADZUNA_APP_ID + ADZUNA_APP_KEY
JSearch	Aggregates LinkedIn/Indeed/Glassdoor/ZipRecruiter	✅ real	RAPIDAPI_KEY

The five no-key sources are always on. Adzuna and JSearch activate automatically only when their keys are present in .env.

---

⚙️ Configuration (.env)

Variable	Purpose	Default
AI_BASE_URL	AI endpoint	http://localhost:20128/v1
AI_API_KEY	Key for the endpoint	—
AI_MODEL	Model id	auto (override to a valid one, e.g. auto/best-free)
ADZUNA_APP_ID / ADZUNA_APP_KEY	Enable Adzuna	—
ADZUNA_COUNTRY	Adzuna country code	us
RAPIDAPI_KEY	Enable JSearch	—

All AI settings are also editable live in the sidebar — .env just sets the defaults.

---

🧭 Usage walkthrough

1. Sidebar → My profile — add your name, email, target role, key skills, and a short résumé summary. (Skills power the match score & AI drafts.) Hit 💾 Save profile.
2. Search — type a title, choose Remote or Any, hit 🔍 Search.
3. Scan — cards are sorted by ★ match %; salary/source/remote chips at a glance.
4. Select a job → the right panel fills in.
5. 🏢 Company & Salary → 🔎 Analyze — get the AI brief, fit score, recommended salary, apply strategy, and research deep-links.
6. ✉️ Apply — pick Email / Cover Letter / CV Prompt → ✨ Generate → edit → copy or open in your mail client.

---

📁 Project structure

Job-Pilot/
├── Home.py                  # dashboard entry — `streamlit run Home.py`
├── pages/                   # one file per tool (Streamlit-native multipage nav)
│   ├── 1_🔍_Job_Search.py
│   ├── 2_📋_Application_Tracker.py
│   ├── 3_📄_Resume_Analyzer.py
│   ├── 4_🎤_Interview_Prep.py
│   └── 5_💰_Salary_Coach.py
├── lib/
│   ├── ai/                  # client · prompts · generate · analyze  (+ barrel)
│   ├── jobs/                # normalize · sources · search           (+ barrel)
│   ├── ui.py · ui_css.py    # shared components + the single CSS kit
│   └── storage.py           # profile.json + applications.json
├── scripts/                 # check_lines.py (≤150 cap) · selftest_all.py
├── docs/                    # per-tool documentation
├── .github/                 # CI workflow + screenshots
├── CLAUDE.md · CONTRIBUTING.md  # engineering rules (CI-enforced)
├── requirements.txt · .env.example · .streamlit/config.toml

Every file stays ≤ 150 lines, one responsibility each, with strict page → lib barrel → service/engine layering. See CONTRIBUTING.md.

---

🗺 Roadmap

• Saved-applications tracker (applications.json + a pipeline page)
• Résumé analyzer, interview prep, salary coach
• More keyed boards (USAJobs, etc.)
• Optional one-click send via Gmail SMTP (currently draft + mailto:)
• Export the tracker to CSV

---

🤔 Honest limitations

• No live Glassdoor ratings — Glassdoor has no free/legal API, so reputation is an AI summary + deep links, not scraped scores. Salary is real when a board provides it, otherwise a clearly-labeled AI estimate.
• Output quality tracks the model you route to — a weak/free model gives weaker text. Use the model picker + connection tester to land on a good one.
• Not a scraper — it uses official/public job APIs; it does not bypass any site's login or anti-bot.

---

🤝 Contributing

Issues and PRs welcome. This is a small codebase with a deliberately strict, tiny rule set (≤150 lines/file, one responsibility, zero heavy deps, a self-check per module) — read CONTRIBUTING.md first. CI enforces the line cap and self-checks on every PR. Adding a tool? Drop a file in pages/, reuse lib.ai.chat() + the lib.ui kit, and add a page under docs/.

📄 License

MIT © 2026 Hassan Al-Najjar

⚠️ Disclaimer

A personal productivity tool. Respect each job board's Terms of Service and rate limits, and review every AI-generated draft before sending it.