remote-job-hunter

A resume-first remote job hunting assistant that searches global job boards, scores role fit, verifies links, and sends a polished daily email report.

remote-job-hunter helps you stop checking the same job boards every morning. It scans remote-friendly sources such as Jobicy, Himalayas, RemoteOK, Remotive, We Work Remotely, Greenhouse, Ashby, Lever, and optional LinkedIn search. It then matches roles against your resume, skills, keywords, remote-region preferences, and exclusion rules before generating a beautiful Daily Job Report for your inbox.

✨ Key Features

• 🌍 Multi-source remote job discovery - Search Jobicy, Himalayas, RemoteOK, Remotive, We Work Remotely RSS, Arbeitnow, Greenhouse, Ashby, Lever, and more.
• 🎯 Resume-first matching - Start from your resume, infer target roles, and score jobs by title, skills, experience, interests, and remote fit.
• 🧠 Smart keyword and skill scoring - Match roles against signals such as Product Design, Figma, B2B SaaS, AI products, or any custom skill set.
• 🚫 Noise and restriction filtering - Filter internships, onsite roles, expired links, US-only/EMEA-only roles, irrelevant titles, and custom dealbreakers.
• ✅ Job verification - Check matched links before sending so closed or expired roles are easier to catch.
• 📬 HTML email daily reports - Receive a clean report with active openings, watch-tier roles, source labels, salary/location notes, and fit reasons.
• 🔁 7-day deduplication - Avoid seeing the same role repeatedly during your search cycle.
• 🕒 Automation-ready - Run manually, from cron, or through GitHub Actions.

📬 Email Report Preview

The generated email is designed for quick morning scanning. It summarizes the search scope, target roles, active openings, roles that need manual verification, and notes about why each opportunity may fit.

flowchart TD
  A[Daily Scheduler] --> B[Fetch Jobs From Multiple Sources]
  B --> C[Normalize Job Data]
  C --> D[Match Keywords + Skills]
  D --> E[Filter Restrictions + Dealbreakers]
  E --> F[Verify Active Links]
  F --> G[Score and Rank Roles]
  G --> H[Generate HTML Job Report]
  H --> I[Send Email via SMTP]

Example Email Layout

┌──────────────────────────────────────────────┐
│ Job Hunter Report - 2026-07-29               │
│ Daily Remote Job Report                      │
├──────────────────────────────────────────────┤
│ Target Roles                                 │
│ Product Manager + Senior Product Designer    │
│                                              │
│ Search Scope                                 │
│ Remote / Worldwide / Global                  │
│                                              │
│ Generated At                                 │
│ 2026-07-29 12:00 GMT+8                       │
├──────────────────────────────────────────────┤
│ 🎯 Product Manager Roles                     │
│                                              │
│ ✅ Active Openings                           │
│ #  Company       Role              Source    │
│ 1  Recast        Product Manager   Greenhouse│
│ 2  Supabase      PM Infrastructure Ashby     │
│ 3  Remote.com    PM Billing        Greenhouse│
│                                              │
│ ⚠️ Watch Tier                                │
│ Roles that need manual verification          │
├──────────────────────────────────────────────┤
│ 🎨 Product Designer Roles                    │
│                                              │
│ ✅ Active Openings                           │
│ #  Company       Role              Source    │
│ 1  Automattic    Sr Product Designer Careers │
│ 2  Remote.com    Sr Product Designer Greenhouse│
├──────────────────────────────────────────────┤
│ Notes                                        │
│ - Location fit                               │
│ - Salary / timezone details                  │
│ - Why the role matches your profile          │
└──────────────────────────────────────────────┘

What the Email Includes

• Report date and generation timestamp
• Target role summary, such as Product Manager + Senior Product Designer
• Search scope, such as Remote / Worldwide / Global
• Active openings grouped by role type
• Watch-tier roles that may need extra review
• Company name, role title, location, salary, source, and notes
• Fit notes such as B2B SaaS, FinTech, AI product, APAC-friendly, or worldwide remote
• Source labels such as Greenhouse, Ashby, RemoteOK, Careers, or RSS

🚀 Quick Start & Installation

Run directly with npx:

npx remote-job-hunter setup
npx remote-job-hunter now
npx remote-job-hunter run

Or install globally:

npm install -g remote-job-hunter

Then run:

remote-job-hunter setup
remote-job-hunter now
remote-job-hunter run

Core Commands

| Command | Description | |---|---| | remote-job-hunter setup | Resume-first interactive setup | | remote-job-hunter now | Run once without sending email and print matches | | remote-job-hunter run | Run the full daily workflow and send the email report | | remote-job-hunter search | Run only the search stage | | remote-job-hunter match | Run only the matching stage, reading JSON from stdin | | remote-job-hunter verify | Verify matched jobs, reading JSON from stdin | | remote-job-hunter email | Send/save the report, reading matched JSON from stdin |

Python entry points are also available:

python3 setup.py
python3 run_now.py
python3 daily_scheduler.py
python3 daily_scheduler.py --dry-run
python3 daily_scheduler.py --no-email
python3 daily_scheduler.py --output-json results.json

⚙️ Configuration

Interactive setup is recommended:

remote-job-hunter setup

Setup will ask for your resume, infer possible target roles, confirm your remote-region preferences, and configure email delivery.

For non-interactive setup:

remote-job-hunter setup --quick \
  --name "Your Name" \
  --title "Product Designer" \
  --email "[email protected]" \
  --skills "Figma,UX Design,Product Design"

Setup generates a local config.json. Do not commit this file because it can contain personal email settings.

Example config.json

{
  "profile": {
    "name": "Alice Chen",
    "title": "Senior Product Designer",
    "years_experience": 8,
    "skills": [
      "Product Design",
      "UX Design",
      "Figma",
      "Design Systems",
      "UX Research",
      "Information Architecture",
      "B2B SaaS",
      "AI Products"
    ],
    "interests": [
      "remote work",
      "design consulting",
      "product strategy",
      "AI products",
      "FinTech"
    ],
    "dealbreakers": [
      "on-site required",
      "no remote",
      "intern",
      "junior",
      "US only",
      "United States only",
      "requires US work authorization"
    ],
    "resume_summary": "8+ years designing complex B2B/SaaS products across fintech, AI infrastructure, and data-heavy workflows.",
    "portfolio_url": "https://example.com",
    "contact_email": "[email protected]"
  },
  "search": {
    "keywords": [
      "Senior Product Designer",
      "Product Design",
      "UX Designer",
      "Figma",
      "B2B SaaS",
      "AI Product"
    ],
    "locations": [
      "Worldwide",
      "Global",
      "Remote Anywhere",
      "APAC",
      "Asia"
    ],
    "sources": {
      "jobicy": true,
      "himalayas": true,
      "remoteok": true,
      "remotive": true,
      "weWorkRemotely": true,
      "greenhouse": true,
      "ashby": true,
      "lever": true,
      "linkedin": false
    },
    "daily_target": 10,
    "dedupe_window_days": 7
  },
  "matching": {
    "minimum_score": 70,
    "prefer_worldwide_remote": true,
    "prefer_async_teams": true,
    "verify_links_before_email": true
  },
  "email": {
    "enabled": true,
    "smtp_host": "smtp.gmail.com",
    "smtp_port": 587,
    "smtp_secure": false,
    "from": "[email protected]",
    "to": "[email protected]",
    "auth": {
      "user": "[email protected]",
      "pass": "your-app-password"
    }
  }
}

Use an email app password for SMTP instead of your main email password.

🧠 Matching Logic

Each job is scored with configurable signals:

| Signal | Description | |---|---| | Role match | Whether the job title matches your target roles | | Skill match | Whether the description includes your skills | | Keyword match | Whether the role aligns with your preferred domains | | Remote fit | Whether the role is worldwide, global, APAC, or remote-anywhere | | Seniority | Whether the role matches your experience level | | Exclusions | Whether the job contains blocked terms or location restrictions | | Freshness | Whether the role is new, active, or recently reposted |

Example scored match:

{
  "company": "Automattic",
  "title": "Senior Product Designer",
  "location": "Worldwide",
  "source": "Careers",
  "score": 94,
  "reasons": [
    "Matches Senior Product Designer target role",
    "Worldwide remote",
    "Strong match for Figma and design systems",
    "Relevant to large-scale product ecosystems"
  ]
}

⏱ Automated Workflow

Option 1: Cron

Run the workflow every day at 9 AM:

0 9 * * * remote-job-hunter run --config ~/remote-job-hunter/config.json

Save logs:

0 9 * * * remote-job-hunter run --config ~/remote-job-hunter/config.json >> ~/remote-job-hunter.log 2>&1

Option 2: GitHub Actions

Create .github/workflows/job-hunter.yml:

name: Daily Job Hunter

on:
  schedule:
    - cron: "0 1 * * *"
  workflow_dispatch:

jobs:
  job-hunter:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install remote-job-hunter
        run: npm install -g remote-job-hunter

      - name: Run job hunter
        env:
          SMTP_USER: ${{ secrets.SMTP_USER }}
          SMTP_PASS: ${{ secrets.SMTP_PASS }}
          SMTP_TO: ${{ secrets.SMTP_TO }}
        run: |
          remote-job-hunter run --config ./remote-job-hunter.config.json

Store email credentials as GitHub Actions secrets:

• SMTP_USER
• SMTP_PASS
• SMTP_TO

🗺 Roadmap

• [ ] AI-powered resume-to-job fit analysis
• [ ] AI-generated cover letter drafts
• [ ] Telegram bot notifications
• [ ] Slack and Discord integrations
• [ ] More ATS support, including Workable and SmartRecruiters
• [ ] Browser-based application assistant
• [ ] Location-restriction verification
• [ ] Salary normalization across countries
• [ ] Web dashboard for saved jobs and application status
• [ ] Multi-profile support for different career tracks

🤝 Contributing

Contributions are welcome.

You can help by:

• adding new job sources
• improving matching logic
• improving email templates
• adding notification integrations
• fixing source parsers
• improving documentation

Development Setup

git clone https://github.com/aliceyuruchan/remotejobhunter.git
cd remotejobhunter
npm install
npm run test:cli

Open a pull request with a clear description of the change and, if possible, example output.

🔐 Security Notes

Never commit credentials, app passwords, or a personal config.json.

Recommended:

• use environment variables
• use GitHub Actions secrets
• keep .env.local out of Git
• rotate SMTP app passwords regularly

Example .env:

[email protected]
SMTP_PASS=your-app-password
[email protected]

📄 License

MIT

Why remote-job-hunter?

Finding high-quality remote work should not mean checking ten job boards every morning, manually filtering irrelevant roles, and losing track of promising opportunities.

remote-job-hunter turns that routine into a daily automated workflow so you can focus on evaluating the best matches, tailoring your applications, and moving forward.