Quick start

From clone to your first scored CSV — about 5 minutes the first time, then 60 seconds every day after.

Prerequisites

1. Install

# Clone
git clone <your-repo> ~/jobpilot
cd ~/jobpilot

# Install Python deps
pip3 install -r requirements.txt
python3 -m playwright install chromium

2. Configure

# Copy example configs
cp config/profile.example.yml config/profile.yml
cp config/portals.example.yml config/portals.yml

Open config/profile.yml and fill your name, email, target roles, location preferences, and tech stack. This drives every downstream pipeline — scoring, resume tailoring, email signatures.

Open config/portals.yml and add/remove company slugs and Naukri search queries.

Add your resume PDF

cp /path/to/your_resume.pdf templates/resume/resume.pdf

This file gets auto-attached to outgoing cold emails.

Add project descriptions (for project-aware cold emails)

# Each markdown file = one project pitch the cold-email agent can use
cat > projects/jobpilot.md <<'EOF'
---
name: JobPilot
demo_url: https://yourdomain.com
repo_url: https://github.com/you/jobpilot
tech: Python, Playwright, sentence-transformers, Gmail API
---
End-to-end AI job-search agent. Scans 30+ portals, scores
roles with ML embeddings, tracks every application — local-first.
EOF

3. Gmail OAuth (optional, for cold email + inbox tracker)

  1. Go to console.cloud.google.com
  2. Create a project (or pick existing)
  3. APIs & Services → Enable APIs → search "Gmail API" → Enable
  4. OAuth consent screen → External → fill basic fields → save
  5. Test users → add your gmail address
  6. Credentials → Create OAuth Client ID → Desktop app
  7. Download the JSON → save to credentials/gmail-oauth-desktop.json

Apollo.io (optional, for auto-fetching contact emails)

  1. Sign up at apollo.io (free, 50 lookups/month)
  2. Settings → API Keys → Create
  3. Save key to credentials/apollo-api-key.txt

4. First run

# Quit Chrome completely first (India scanner needs the profile)
osascript -e 'quit app "Google Chrome"'

# Run everything end-to-end
./jobpilot run-all

Output:

━━━ Greenhouse (11 companies) ━━━
  vercel: 75 jobs
  hightouch: 64 jobs
  ...
━━━ Naukri ━━━
  Query: software-engineer in bangalore → 40 jobs
  ...
Total fetched: 1578 jobs
After filter: 282 jobs
✓ Semantic scoring done
Review CSV: outputs/2026-06-28/review-batch.csv
  Score >= 4.0: 13
  Score 3.5-3.9: 50

5. Daily workflow

Once it's set up, your daily loop looks like this:

# Morning — 5 min
./jobpilot run-all
open outputs/$(date +%Y-%m-%d)/review-batch.csv

# Review in Excel (10 min, manual)
# - Change Approval to APPROVED / SKIP
# - Fill Contact_Email for cold-email candidates
# - Save

# Apply (5 min)
./jobpilot find-contacts    # Apollo auto-fills
./jobpilot apply            # Opens portal URLs in tabs

# Cold emails (optional)
./jobpilot draft-emails     # Project-aware drafts
./jobpilot send-emails      # Asks y/n per email

# Evening
./jobpilot inbox            # Scan Gmail for replies
Nothing happens without you saying yes. CSV approval is the first gate. Per-email y/n confirmation is the second.

Next