Stop Doom-Scrolling Job Boards: job-scout Automates Your Hunt

Stop Doom-Scrolling Job Boards: job-scout Automates Your Hunt

What if your next $200K offer is sitting on page three of Indeed right now—and you'll never see it?

Here's the brutal truth: job boards are designed to keep you scrolling, not to get you hired. Promoted listings bury relevant posts. Identical jobs get reposted with different IDs to game the algorithm. And if you're checking LinkedIn, Indeed, Google Jobs, Glassdoor, ZipRecruiter, and Bayt manually? You're burning 2+ hours daily on digital archaeology.

I tried something different. Something that runs while I sleep, scores every match against my actual skills, and pings my phone only when something's worth my time. No API keys. No monthly fees. Just a Python^{↗ Bright Coding Blog} CLI tool that turned my Mac into a 24/7 job-hunting engine.

That tool is job-scout—and it's about to change how you think about finding work.

What is job-scout?

job-scout is a free, open-source CLI tool created by weberwcwei that scrapes six major job boards, intelligently scores each posting against your personalized profile, and delivers high-match alerts through Telegram, Slack, Discord, or email. Built for macOS with Python 3.12+, it requires zero API keys and runs entirely on your machine—no third-party services harvesting your data, no subscription tiers, no catch.

The project exploded in relevance throughout early 2026, with rapid-fire updates adding multi-profile support, LLM-powered Telegram queries via Gemini, content-based deduplication, and sophisticated scheduling through macOS plist files. The changelog reads like a product team on a mission: location normalization, daily email reports, dealbreaker storage, and export functionality all landed within a single month.

Why the momentum? The job market in 2026 is brutally efficient—and brutally noisy. Developers need tools that cut through the noise without cutting into their wallets. job-scout's "no API keys required" badge isn't just a feature; it's a statement against the SaaS-ification of job searching. Your credentials, your data, your machine. Period.

The tool sits at the intersection of web scraping, intelligent filtering, and developer workflow automation—three domains where open-source tools traditionally dominate proprietary alternatives. By combining these into a single, polished CLI experience, job-scout fills a gap that LinkedIn Premium, Indeed alerts, and scattered browser extensions fail to address: truly personalized, automated, cross-platform job intelligence.

Key Features That Separate job-scout from Everything Else

Six-Platform Scraping Engine job-scout hits LinkedIn, Indeed, Google Jobs, Glassdoor, ZipRecruiter, and Bayt in a single sweep. Each platform has distinct HTML structures, anti-bot measures, and rate-limiting behaviors. The tool handles these variations internally, normalizing disparate data into a consistent schema for scoring and storage.

0–100 Intelligent Scoring System This isn't keyword matching. job-scout weights your profile across four keyword tiers (critical, strong, moderate, weak), company preference tiers, title signals with point values, seniority levels, and dealbreaker regex patterns. A job posting gets dissected, scored, and ranked—so an 85 from Indeed competes fairly with an 85 from LinkedIn.

Multi-Channel Alert Delivery Configure Telegram (with Gemini LLM natural-language queries!), Slack webhooks, Discord webhooks, or SMTP email. Mix and match. Get digest summaries or immediate alerts. The 2026-04-12 update even hardened Telegram prompts against injection attacks—because yes, someone thought about security.

Content-Based Deduplication Job boards rotate IDs. Indeed especially plays games with key rotation, making the "same" posting appear "new." job-scout's deduplication analyzes actual content—titles, descriptions, locations—to catch these clones. The dedup command cleans existing databases; new scrapes catch duplicates automatically.

Application Tracking Built-In Every job gets a persistent ID. Mark applied with timestamps. Add notes. Generate stats. Export to CSV/JSON. This isn't a separate ATS; it's integrated job search lifecycle management that respects the reality that finding jobs and tracking applications are inseparable activities.

Multi-Profile Architecture Run job-scout --config frontend.yaml and job-scout --config backend.yaml simultaneously—separate databases, separate schedules, separate notification prefixes. Perfect for dual-role searches, household sharing, or testing configuration variations without polluting your main database.

macOS Native Scheduling No cron complexity. job-scout schedule --install creates proper launchd plists that survive reboots, run every 6 hours by default, and include daily report generation. Uninstall cleanly with --uninstall.

Use Cases: Where job-scout Actually Shines

The Passive Candidate

You're employed but opportunistic. You don't have time to check boards, but you'd move for the right role. job-scout runs silently, surfaces only 80+ matches, and you spend zero mental energy until something exceptional arrives. This is the tool's sweet spot—ambient job awareness without ambient anxiety.

The Reluctant Job Hopper

Burned out, need to leave, but the thought of six open tabs makes you want to stay miserable. Set up job-scout once, get Telegram pings with pre-scored matches, and reduce the activation energy of applying from "mountain" to "molehill." The apply command's tracking adds just enough structure to maintain momentum.

The Dual-Skill Professional

Full-stack? DevOps^{↗ Bright Coding Blog}-curious? Data engineer who'd take ML roles? Run multiple configs with --config. Your frontend search targets React^{↗ Bright Coding Blog}/TypeScript roles at startups; your backend search targets Go/Rust positions at infrastructure companies. Both run independently, both alert separately. No compromise, no confusion.

The International Candidate

H-1B sponsorship requirements, location restrictions, visa dealbreakers—job-scout's regex-based dealbreakers section catches these before you waste time. The built-in patterns flag "no visa sponsorship," "US citizen only," and "security clearance required." Add your own: country-specific, language-specific, whatever filters your reality.

The Methodical Tracker

You apply to 50+ positions weekly and need organization. job-scout list, view, apply, stats, and export form a complete workflow. Generate weekly CSVs for your spreadsheet obsession. The database is SQLite—open it directly if you need custom queries.

Step-by-Step Installation & Setup Guide

Prerequisites

• macOS (the tool is optimized for Apple's ecosystem)
• Python 3.12+ (download from python.org)
• Git (for cloning)

Installation Commands

# Clone the repository
git clone https://github.com/weberwcwei/job-scout.git

# Enter the project directory
cd job-scout

# Make setup script executable and run it
chmod +x setup.sh
./setup.sh

The setup.sh script creates a Python virtual environment, installs dependencies, and configures the CLI entry point. After completion, you have two execution options:

Option A: Activate virtual environment (recommended for regular use)

source .venv/bin/activate
job-scout check

Option B: Run directly without activation

.venv/bin/job-scout check

All subsequent examples assume you've activated the virtual environment.

Configuration Generation

job-scout requires a config.yaml file that defines your profile, search parameters, scoring thresholds, and schedule. Rather than wrestling with YAML syntax, the project provides an AI-assisted setup prompt that transforms your resume into a valid configuration.

Copy the detailed prompt from the README's collapsible section, paste it into ChatGPT or any AI chatbot along with your resume text, and save the output as config.yaml in the project folder.

The generated config includes strictly validated sections:

• profile: Your skills, companies, dealbreakers, and target levels
• search: Terms, locations, sites, and result limits
• scoring: Minimum thresholds for alerts and display
• schedule: Automation interval (default 6 hours)

Critical validation rules the AI prompt enforces:

• Four-tier keyword system (critical/strong/moderate/weak)
• Regex dealbreakers with (?i) case-insensitive flags
• Title signals with 1-12 point values
• Exact site names: linkedin, indeed, google, glassdoor, ziprecruiter

Notification Setup (Optional but Recommended)

Slack (fastest setup):

1. Create an Incoming Webhook
2. Add to config.yaml:

notifications:
  slack:
    enabled: true
    webhook_url: "https://hooks.slack.com/services/T.../B.../..."

Telegram (most feature-rich with Gemini LLM):

1. Message @BotFather → /newbot → copy token
2. Message @userinfobot → copy chat ID
3. Uncomment and fill notifications.telegram in config

Email (Gmail with App Password):

1. Enable 2-Step Verification, then visit Google App Passwords
2. Create "job-scout" password, enter without dashes

First Run & Scheduling

job-scout check                # Validate configuration syntax
job-scout scrape --dry-run     # Test scraping without saving
job-scout schedule --install   # Enable automated background execution

The scheduler installs macOS launchd plists that trigger every interval_hours (default: 6), generating digests and daily reports automatically.

REAL Code Examples from the Repository

Example 1: Basic CLI Workflow Commands

The daily interaction model is intentionally minimal. Here's the complete command surface:

# View your latest scored matches
job-scout list

# Inspect full details for a specific job (by ID)
job-scout view 42

# Mark a job as applied with automatic timestamp
job-scout apply 42

# Re-score all existing jobs after profile updates
job-scout rescore

# Preview duplicate cleanup without committing
job-scout dedup --dry-run

# Execute duplicate removal
job-scout dedup

# View application statistics
job-scout stats

# Manually trigger digest notification
job-scout digest

# Generate and email daily report
job-scout report

# Export all jobs to CSV for external analysis
job-scout export -o jobs.csv

What's happening here: These commands form a complete CRUD-like interface to your job search data. The numeric IDs are persistent SQLite primary keys, so apply 142 today references the same job tomorrow. The --dry-run pattern (also used in scrape --dry-run) follows Unix conventions for safe experimentation. Export supports both CSV and JSON formats via the -o extension detection.

Example 2: Multi-Profile Configuration Launch

For developers running parallel searches, the --config flag provides complete isolation:

# Initialize a new, completely separate search profile
job-scout --config frontend.yaml init

# Validate this alternate configuration
job-scout --config frontend.yaml check

# Execute scraping with isolated database and logs
job-scout --config frontend.yaml scrape

# Install separate background scheduler for this profile
job-scout --config frontend.yaml schedule --install

What's happening here: Each --config invocation creates an independent execution context. The init subcommand generates a template configuration; check validates it against the same strict schema as the default. Databases, log directories, and scheduler plists are prefixed with the config filename (or an explicit config_name override in YAML). This architecture enables true multi-tenancy without containerization overhead.

Example 3: Notification Configuration Patterns

The README provides exact YAML structures for each channel. Here's the Slack webhook pattern:

notifications:
  slack:
    enabled: true
    webhook_url: "https://hooks.slack.com/services/T.../B.../..."

And the Discord equivalent:

notifications:
  discord:
    enabled: true
    webhook_url: "https://discord.com/api/webhooks/ID/TOKEN"

What's happening here: Both use simple webhook URLs rather than OAuth flows or bot tokens—dramatically reducing setup friction. The enabled: true toggle allows quick channel switching without reconfiguration. Multiple channels can be active simultaneously; the tool sends to all enabled endpoints. The webhook approach means no persistent connections, no rate-limit management, no retry logic complexity—just HTTP POSTs with formatted payloads.

Example 4: The AI-Assisted Config Prompt Structure

While not executable code, the config generation prompt demonstrates sophisticated prompt engineering:

STRICT FORMAT RULES (the app validates all of these — violations cause errors):

1. REQUIRED TOP-LEVEL SECTIONS (in this exact order):
   profile, search, scoring, schedule
   Do NOT include: scraping, notifications, or db_path sections.

4. profile.keywords — four tiers, each a YAML list of plain lowercase strings:
   - critical: 8-15 keywords — my core technical identity
   - strong: 10-20 keywords — important skills I use regularly
   - moderate: 8-15 keywords — skills I have but aren't central
   - weak: 4-8 keywords — general terms, tools I've used occasionally

6. profile.dealbreakers — three categories, each a YAML list of REGEX PATTERN strings.
   Every pattern MUST:
   - Start with (?i) for case-insensitive matching
   - Use \b for word boundaries where appropriate
   - Be a valid Python regex

What's happening here: This prompt exemplifies defensive AI interaction design. By specifying exact section ordering, list lengths, regex requirements, and forbidden sections, the creator prevents common LLM hallucinations that would crash the YAML parser or fail validation. The (?i) and \b requirements ensure Python re module compatibility. The tiered keyword system (critical/strong/moderate/weak) enables non-linear scoring where "Rust" in critical carries more weight than "Python" in weak, even if both appear in a posting.

Advanced Usage & Best Practices

Optimize Your Scoring Thresholds Start with scoring.min_alert_score: 45 and scoring.min_display_score: 20. If you're flooded with alerts, raise to 55-60. If you're getting nothing, verify your search.terms match actual job board phrasing—"ML Engineer" vs "Machine Learning Engineer" vs "AI Engineer" return different results.

Master Dealbreaker Regex The built-in patterns catch common exclusion criteria, but customize aggressively. Staffing firms cluttering your results? Add (?i)\b(Robert Half|TekSystems|Aerotek)\b to company_patterns. Remote-only searcher? Add (?i)\bon[- ]?site\b|\bhybrid\b to description_patterns (or invert: require (?i)\bremote\b).

Leverage Content Deduplication Run job-scout dedup --dry-run weekly to audit clone detection. If you're seeing false positives (genuinely different jobs flagged as duplicates), your search.terms may be too broad—refine to reduce near-identical postings.

Telegram LLM Queries The 2026-04-12 Gemini integration enables natural-language status queries. Instead of job-scout list, message your bot: "Show me remote Python jobs over 80 score from this week." The hardened prompt prevents injection while enabling genuine conversational interaction with your job database.

Database Hygiene The SQLite database grows indefinitely. Periodically export and archive old data, or manually prune applied jobs older than your search horizon. The XDG config path compliance ensures your data lives in predictable locations for backup scripts.

Comparison with Alternatives

Why job-scout wins: It occupies the automation sweet spot between "too simple to be useful" (Indeed alerts) and "too complex to maintain" (building on JobSpy). LinkedIn Premium costs $480/year for inferior cross-platform coverage. job-scout delivers superior intelligence with zero recurring cost and complete data sovereignty.

FAQ

Q: Is job-scout legal? Does it violate job board terms of service? A: job-scout performs the same HTTP requests your browser does—no API abuse, no credential stuffing, no circumvention of technical protections. However, automated scraping exists in a legal gray area. Use responsibly, respect rate limits (built-in 6-hour intervals help), and understand that boards may change their HTML without notice.

Q: Can I run job-scout on Linux or Windows? A: The tool is optimized for macOS (launchd scheduling, platform badges). The Python code likely runs on Linux with manual scheduling setup. Windows would require WSL or significant adaptation. The creator explicitly targets Mac users.

Q: What happens when job boards change their HTML? A: Scrapers break. It's inevitable. The open-source model means the community can submit fixes via pull requests. The rapid changelog (multiple updates weekly in April 2026) suggests active maintenance. Pin to a working commit if stability matters more than features.

Q: How accurate is the 0-100 scoring? A: Accuracy depends entirely on config quality. The AI-assisted prompt helps, but garbage in, garbage out. Iterate: run --dry-run, inspect scores, adjust keyword tiers and title signals. Most users converge on useful calibration within 2-3 cycles.

Q: Can I use job-scout for non-tech roles? A: Absolutely. The scoring system is domain-agnostic. A marketing professional would configure profile.keywords with "SEO^{↗ Bright Coding Blog}," "content strategy," "Google Analytics" instead of "Kubernetes" and "Rust." The job board coverage spans all industries.

Q: Is my resume data safe? A: Your resume text goes to your chosen AI chatbot for config generation—standard third-party risk. After that, everything stays local: SQLite database, YAML config, execution logs. No cloud service, no telemetry, no analytics. Review the MIT-licensed source code to verify.

Q: What if I get rate-limited or IP-banned? A: The 6-hour default interval is conservative. If you hit limits, increase schedule.interval_hours. Residential IPs generally tolerate this frequency. Corporate networks or VPN exit nodes may face stricter limits. The --dry-run option lets you test without triggering protections.

Conclusion

job-scout isn't just another job search tool—it's a fundamental workflow upgrade for anyone serious about finding their next role without surrendering their sanity or their data. In a market where LinkedIn extracts $40/month for basic filtering and Indeed drowns you in irrelevant alerts, a free, local, intelligently scoring alternative isn't just nice to have. It's essential.

The technical implementation impresses: multi-platform scraping with normalized scoring, sophisticated deduplication, multi-channel notifications, and a CLI that respects Unix philosophy. But the real magic is removing friction from a friction-heavy process. You configure once, schedule forever, and interact only when something merits your attention.

I've seen too many talented developers burn out on the job search before they find the right role. job-scout won't write your cover letters or ace your interviews—but it will ensure you never miss the opportunity you deserve because it was buried on page four of ZipRecruiter.

Ready to stop scrolling and start scoring? Grab the code, generate your config, and let your Mac hunt while you sleep. Your future self—with that offer letter in hand—will thank you.

👉 Get job-scout on GitHub — Star it, fork it, make it yours. The job market waits for no one, but now, neither do you.

Found this breakdown useful? Share it with that friend who's been "thinking about looking" for six months. Sometimes the best career move is automating the search.