Local-first job search automation • Smart scoring • Zero tracking • $0 forever
Quickstart • Features • Documentation • Wiki
The problem: Job boards are noisy, privacy-invasive, and require manual filtering. Paid services charge monthly fees ($30-100/mo), sell your data, and still miss the best opportunities.
The solution: JobSentinel runs 100% locally on your machine. It scrapes top job boards, scores matches against your preferences, and sends high-value alerts (80+ score) to Slack or email—all while keeping your data private. No tracking. No subscriptions. $0 forever.
- Job seekers who value privacy and want automated alerts for high-match roles
- Passive candidates monitoring the market without broadcasting availability
- Recruiters tracking positions for clients (GDPR/HIPAA compliant)
- Developers who want local-first automation without cloud dependencies
- React 19 + Vite 7 modern web UI with real-time updates
- Platform installers one-click setup for Windows and macOS
- WCAG 2.1 AA accessibility compliance
- Resume analyzer AI-powered job-resume matching
- Application tracker manage your job search pipeline
- Dark mode eye-friendly interface
- Download: https://github.com/cboyd0319/JobSentinel/archive/refs/heads/main.zip
- Extract to Desktop
- Double-click:
deploy/local/windows/launch-gui.bat
Done! A GUI opens. Click "Start JobSentinel" and view logs in the interface.
- Download: https://github.com/cboyd0319/JobSentinel/archive/refs/heads/main.zip
- Extract to Desktop
- Double-click:
deploy/local/macos/setup-macos.sh- If blocked: Right-click → Open → Open
Follow the interactive wizard to configure your preferences.
# Clone repository
git clone https://github.com/cboyd0319/JobSentinel
cd JobSentinel
# Create virtual environment
python3 -m venv .venv && source .venv/bin/activate
# Install dependencies
pip install -e .
playwright install chromium
# Configure preferences
cp deploy/common/config/user_prefs.example.json deploy/common/config/user_prefs.json
# Edit config with your keywords, locations, salary, etc.
# Run single scan
python -m jsa.cli run-once
# Or start daemon (every 2 hours)
python -m jsa.cli run-daemon --interval 7200
# Or launch web UI
python -m jsa.cli web --port 8000
# Open: http://localhost:8000First time using a terminal? → Quickstart Guide
graph LR
A[Job Boards] -->|Scrape| B[JobSentinel]
B -->|Score| C[Matcher Engine]
C -->|80+ score| D[Alerts]
C -->|All jobs| E[SQLite DB]
D -->|Slack/Email| F[You]
style A fill:#43A047
style C fill:#1976D2
style D fill:#F57C00
style F fill:#E91E63
- Scrape - Pull jobs from Greenhouse, Lever, Reed, JobsWithGPT, JobSpy
- Normalize - Convert to standard format (source, title, company, location, salary, URL)
- Score - Match against preferences (skills 40%, salary 25%, location 20%, company 10%, recency 5%)
- Alert - Send high matches (80+ score) via Slack/email
- Store - Save to local SQLite database (
data/jobs.sqlite)
Privacy-first: All data stays on your machine. No telemetry. No external API calls (except job board scraping).
|
Job Scraping
Smart Scoring
Web UI (NEW)
|
Alerts & Notifications
Data Storage
Security & Privacy
Platform Support
|
| Tool | Version | Purpose | Required |
|---|---|---|---|
| Python | ≥ 3.12 | Runtime (includes SQLite) | Yes |
| Git | any | Clone repository (or download ZIP) | No |
| Disk Space | 1GB | App + ML models + job data | Yes |
| Slack Webhook | N/A | Alerts (optional) | No |
| Reed API Key | N/A | UK jobs (optional) | No |
See Quickstart Guide for detailed instructions.
Edit deploy/common/config/user_prefs.json:
{
"keywords": ["python", "backend", "api"],
"locations": ["Remote", "San Francisco"],
"min_salary": 120000,
"denied_companies": ["Meta", "Amazon"],
"job_sources": {
"jobswithgpt": {"enabled": true},
"reed": {"enabled": false, "api_key": ""}
},
"alerts": {
"slack": {
"enabled": false,
"webhook_url": ""
},
"email": {
"enabled": false,
"smtp_host": "smtp.gmail.com",
"smtp_port": 587,
"from_email": "",
"password": ""
}
}
}| Key | Type | Default | Example |
|---|---|---|---|
keywords |
list[str] | [] | ["python", "backend"] |
locations |
list[str] | [] | ["Remote", "SF"] |
min_salary |
int | 0 | 120000 |
denied_companies |
list[str] | [] | ["Meta", "Amazon"] |
Validate config:
python -m jsa.cli config-validate# Single scan
python -m jsa.cli run-once
# Daemon (every 2 hours)
python -m jsa.cli run-daemon --interval 7200
# Web UI
python -m jsa.cli web --port 8000
# Health check
python -m jsa.cli health- Start web server:
python -m jsa.cli web --port 8000 - Open browser:
http://localhost:8000
Features:
- Dashboard with job statistics
- Search and filter jobs
- Application tracker
- Resume analyzer (AI-powered)
- Real-time updates (WebSocket)
- Dark mode support
- WCAG 2.1 AA accessibility
Error: Python not found
Cause: Python 3.12+ not installed
Fix:
# Check version
python --version # Need 3.12+
# Install:
# Windows: python.org
# macOS: brew install python@3.12
# Linux: apt install python3.12Error: Config not found
Cause: Missing user_prefs.json
Fix:
cp deploy/common/config/user_prefs.example.json deploy/common/config/user_prefs.jsonNo jobs found
Cause: Keywords too specific, salary too high, or sources disabled
Fix:
- Broaden keywords (e.g., "engineer" instead of "senior staff principal engineer")
- Lower minimum salary threshold
- Check enabled sources:
python -m jsa.cli config-validate
Slack alerts not working
Cause: Invalid webhook URL or Slack app misconfigured
Fix:
# Test webhook
curl -X POST "YOUR_WEBHOOK" \
-H "Content-Type: application/json" \
-d '{"text":"Test"}'
# Verify webhook in config
cat deploy/common/config/user_prefs.json | grep webhook_urlDatabase locked error
Cause: Multiple JobSentinel processes running
Fix:
# Find and kill processes
ps aux | grep jobsentinel
kill <PID>
# Or restart systemMore help: Troubleshooting Guide • GitHub Discussions
Expected performance:
- Scrape time: 30–60s per source
- Scoring: <5s per 100 jobs
- Alert latency: <10s (Slack/email)
- Memory usage: <500MB (includes ML models)
- Disk usage: ~50MB per 1000 jobs
- Database: SQLite (<100MB typical)
Tested with: 10,000+ jobs in SQLite without performance degradation.
- React 19 + Vite 7 UI
- Consolidated documentation
- Platform installers (Windows/macOS)
- WCAG 2.1 AA accessibility
- GPT-4 integration (optional, cost-controlled)
- Multi-language support
- Browser extension
- Mobile companion app
See AI/ML Roadmap for AI/ML features.
- Quickstart Guide - Detailed setup instructions
- Documentation Index - Complete documentation map
- Wiki - Capabilities and features
- Architecture - System design and data flow
- Security - Security model and threat analysis
- Troubleshooting - Common issues and fixes
- Contributing - Development setup
Contributions welcome! See CONTRIBUTING.md.
Before submitting:
- Tests pass:
make test - Lint passes:
make lint - Type check passes:
make type - Coverage ≥85%:
make cov - No secrets committed
Quick start for developers:
git clone https://github.com/cboyd0319/JobSentinel
cd JobSentinel
make dev # Install dev dependencies
make test # Run testsMIT License - See LICENSE for full text.
✅ Commercial use allowed
✅ Modification allowed
✅ Distribution allowed
✅ Private use allowed
📋 License and copyright notice required
TL;DR: Use it however you want. Just include the license.
Learn more: https://choosealicense.com/licenses/mit/
Need help?
- 🐛 File a bug report
- 💡 Request a feature
- 💬 Ask a question
- 🔒 Report a security issue (private)
Resources:
- Wiki - Comprehensive capabilities and features
- Documentation - Complete docs
- Security Policy - Responsible disclosure
This is a single-developer, personal project. Support is best-effort with no SLAs. Security issues are prioritized; feature requests and questions are handled as time allows.
If JobSentinel helps you find your next opportunity, give us a star ⭐
Active Development • Privacy-First • Community-Driven
Made with ❤️ for job seekers who value privacy