Skip to content

README_EN.md

Latest commit

 

History

History
411 lines (310 loc) · 13.3 KB

README_EN.md

File metadata and controls

411 lines (310 loc) · 13.3 KB
Raw

中文

       __      __    ________
      / /___  / /_  / ____/ /___ __      __
 __  / / __ \/ __ \/ /   / / __ `/ | /| / /
/ /_/ / /_/ / /_/ / /___/ / /_/ /| |/ |/ /
\____/\____/_.___/\____/_/\__,_/ |__/|__/

JobClaw — Stop Applying Manually. Let AI Do the Grunt Work.

Python License: MIT PRs Welcome

TL;DR: JobClaw is an open-source AI job hunting agent. It scrapes job listings from LinkedIn and Boss直聘, matches them against your profile using LLMs, auto-applies to the best fits, and notifies you of results via Telegram or Discord.
You write the resume. JobClaw does the rest.

😩 The Problem

Job hunting is a grind. Everyone knows it:

  • You scroll through LinkedIn for hours, tweaking keywords, opening tabs
  • You read each JD manually to decide if it's worth applying
  • You click "Easy Apply" dozens of times a day — same info, over and over
  • Half the postings are ghost jobs where the recruiter hasn't logged in for months
  • You lose track of what you applied to, what ghosted you, what's pending

Your time is better spent preparing for interviews and building skills — not being a human apply-bot.

🦀 What JobClaw Does

Step Manual JobClaw
🔍 Find jobs Jump between platforms, try different keywords Auto-scrape LinkedIn + Boss直聘
📖 Evaluate fit Read each JD, gut-feel it LLM-powered matching with scores + explanations
💬 Craft messages Write custom intros for each role Auto-generated greetings with template variables
📤 Apply Click "Apply" 100 times Auto-apply to high-match roles
🧹 Filter junk Pure intuition, often wasted on ghost jobs Recruiter activity filter — skip inactive postings
📊 Track status Spreadsheet? Sticky notes? Memory? Real-time Telegram / Discord notifications

Set up your profile once. Let JobClaw work 24/7.

✨ Key Features

🤖 LLM-Powered Matching Engine

Not simple keyword matching — JobClaw uses large language models to understand your background and job requirements, producing match scores with explanations.

Three authentication methods (in priority order):

Priority Method Cost Notes
🥇 Claude OAuth Free Piggyback on your Claude Code subscription — zero API cost!
🥈 Anthropic API Key Pay-per-use Direct Claude API calls
🥉 OpenAI API Key Pay-per-use GPT model family

💡 Cost-saving tip: If you have a Claude Code subscription ($20/month), JobClaw can reuse your OAuth token to call Claude — no additional API cost whatsoever. Tokens auto-refresh before expiry. Completely seamless.

📮 Boss直聘 Auto-Apply (China Market)

Boss直聘 has no public application API. JobClaw uses Playwright browser automation to simulate the full human interaction flow:

  1. Open job page → Click "Start Chat"
  2. Type greeting message → Send
  3. Random delay → Next job

Anti-detection measures:

  • ⏱️ Random delays: 3-8 seconds between actions (configurable)
  • 📅 Daily cap: Default 100 applications/day to avoid rate limits
  • 👻 Ghost job filter: Skip postings where HR hasn't been active for N days (default: 7)
  • 🔄 Dedup: JSON history prevents re-applying to the same job
  • 🤖 CAPTCHA detection: Auto-pauses and sends Telegram alert for manual intervention

Greeting template:

Hi! I'm very interested in the $title role at $company, $name. Would love to chat!

Variables: $company, $title (job title), $name (recruiter name)

🍪 Cookie Management

  • jobclaw login — Opens browser for interactive login, cookies auto-saved to ~/.jobclaw/cookies/
  • jobclaw login --check — Verify saved cookies are still valid
  • Priority: .env config > persisted files > prompt to re-login
  • Supports Boss直聘 + LinkedIn

🔔 Notifications

Auto-report after each run:

  • Telegram Bot — Set TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID
  • Discord Webhook — Set DISCORD_WEBHOOK_URL

🚀 Quick Start

1. Clone & Install

git clone https://github.com/VPC-byte/jobclaw.git
cd jobclaw
pip install -e .

2. Install Browser Runtime

playwright install chromium

3. Log in to Job Platforms

# Log in to LinkedIn (opens browser for manual login)
jobclaw login --platform linkedin

# Log in to Boss直聘
jobclaw login --platform boss

# Log in to all platforms at once
jobclaw login --platform all

# Check if saved cookies are still valid
jobclaw login --platform linkedin --check

4. Configure Environment

cp .env.example .env

Edit .env with your settings (see Configuration below).

5. Set Up Your Profile

cp profiles/example.yaml profiles/me.yaml

Edit profiles/me.yaml — your skills, salary expectations, preferred locations, etc.

6. Launch!

# Full pipeline: scrape → match → apply → notify
jobclaw run --profile profiles/me.yaml --query "AI Engineer"

Grab a coffee and wait for notifications ☕

🔧 CLI Reference

jobclaw login — Platform Authentication

# Log in to LinkedIn
jobclaw login --platform linkedin

# Log in to Boss直聘
jobclaw login --platform boss

# Log in to all platforms
jobclaw login --platform all

# Set login timeout (minutes)
jobclaw login --platform linkedin --timeout 5

# Check cookie validity (no browser popup)
jobclaw login --platform linkedin --check

jobclaw scrape — Scrape Only (No Applications)

# Scrape LinkedIn jobs
jobclaw scrape --platform linkedin --query "AI Engineer" --limit 20

# Scrape Boss直聘
jobclaw scrape --platform boss --query "后端工程师" --limit 20

# Scrape all platforms
jobclaw scrape --platform all --query "Python Developer" --limit 30

💡 Use scrape first to check listing quality before running the full pipeline.

jobclaw run — Full Pipeline

# Basic usage
jobclaw run --profile profiles/me.yaml --query "AI Engineer"

# Specific platform + limit
jobclaw run --platform linkedin --profile profiles/me.yaml --query "ML Engineer" --limit 20

# All platforms
jobclaw run --platform all --profile profiles/me.yaml --query "Backend Developer" --limit 50

jobclaw validate-profile — Validate Profile YAML

jobclaw validate-profile --profile profiles/me.yaml

Catch YAML errors before running the pipeline.

⚙️ Configuration

.env Environment Variables

Variable Required Default Description
Core
JOBCLAW_ENV No development Runtime environment
JOBCLAW_LOG_LEVEL No INFO Log level
JOBCLAW_HEADLESS No true Headless browser mode (set false to watch)
JOBCLAW_MAX_JOBS No 30 Max jobs to process per run
JOBCLAW_REQUEST_TIMEOUT No 30 Request timeout in seconds
LLM
CLAUDE_CREDENTIALS_PATH No Auto-detect Claude OAuth credentials (default: ~/.claude/.credentials.json)
CLAUDE_MODEL No claude-sonnet-4-6 Model for Claude OAuth
ANTHROPIC_API_KEY No - Anthropic API key
OPENAI_API_KEY No - OpenAI API key
JOBCLAW_LLM_MODEL No gpt-4o-mini Model for OpenAI
Platform Cookies
BOSS_COOKIE No - Boss直聘 cookie (overrides saved file)
LINKEDIN_COOKIE No - LinkedIn cookie
Boss直聘 Settings
BOSS_GREETING No - Greeting template ($company $title $name)
BOSS_APPLY_DELAY_MIN No 3.0 Min seconds between applications
BOSS_APPLY_DELAY_MAX No 8.0 Max seconds between applications
BOSS_DAILY_LIMIT No 100 Daily application cap (1-150)
BOSS_SKIP_INACTIVE_DAYS No 7 Skip jobs where HR inactive for N days
Notifications
TELEGRAM_BOT_TOKEN No - Telegram Bot token
TELEGRAM_CHAT_ID No - Telegram Chat ID
DISCORD_WEBHOOK_URL No - Discord Webhook URL
Network
HTTP_PROXY No - HTTP proxy
HTTPS_PROXY No - HTTPS proxy

🆓 Claude OAuth (Zero-Cost LLM): Install Claude Code CLI (npm i -g @anthropic-ai/claude-code), log in with your subscription, and JobClaw auto-detects ~/.claude/.credentials.json. No API key needed, no extra cost. Token auto-refreshes before expiry.

profiles/me.yaml — Job Seeker Profile

name: "Jane Doe"
email: "jane@example.com"
years_experience: 3

summary: >
  Full-stack developer with experience in AI/ML applications,
  cloud infrastructure, and DevOps. Looking for AI Agent roles.

skills:
  - Python
  - TypeScript
  - LLM/Agent Development
  - Kubernetes
  - Docker
  - AWS/GCP

desired_roles:
  - AI Agent Developer
  - LLM Application Engineer
  - MLOps Engineer
  - Backend Developer (AI)

preferences:
  locations:
    - "San Francisco"
    - "remote"
  salary_min: 120000   # Annual, USD
  salary_max: 200000
  work_schedule: "flexible"
  industries:
    - AI
    - Web3
    - Cloud
  deal_breakers:
    - "no remote option"
    - "contract only"

🏗️ Architecture

+---------------------+
|   Profile Loader    |  Your resume / preferences (YAML)
+----------+----------+
           |
           v
+---------------------+      +----------------------+
|   Scraper Layer     |----->| Unified Job Objects  |
| LinkedIn / Boss直聘 |      | (Pydantic Models)    |
+----------+----------+      +----------+-----------+
           |                            |
           v                            v
+---------------------+      +----------------------+
|   LLM Matcher       |----->| Match Score + Reason |
| Claude OAuth/API/   |      | (SSE streaming)      |
| OpenAI              |      +----------+-----------+
+----------+----------+                 |
           |                            v
+---------------------+      +----------------------+
|  Auto Applier       |----->| Application Status   |
| LinkedIn / Boss直聘 |      | Applied / Failed /   |
+----------+----------+      | Skipped              |
           |                 +----------+-----------+
           +------------+---------------+
                        v
              +--------------------+
              | Notification Layer |
              | Telegram / Discord |
              +--------------------+

📂 Project Structure

jobclaw/
  applier/                 # Auto-application engines
    base.py                #   Applier base class
    boss.py                #   Boss直聘 (greeting + anti-detection)
    linkedin.py            #   LinkedIn Easy Apply
    captcha.py             #   CAPTCHA detection + notification
    history.py             #   Application history (dedup)
  auth/                    # Authentication
    browser_login.py       #   Playwright interactive browser login
    cookie_manager.py      #   Cookie persistence manager
    claude_auth.py         #   Claude OAuth credential reader
    token_refresh.py       #   OAuth token auto-refresh
  matcher/                 # LLM matching engine
    llm_matcher.py         #   Multi-provider match scoring
  models/                  # Claude API client
    claude_api.py          #   Claude API wrapper
    streaming.py           #   SSE streaming + retry/backoff
  notifier/                # Notifications
    telegram.py            #   Telegram Bot notifications
    discord.py             #   Discord Webhook notifications
  profile/                 # Profile loading
    loader.py              #   YAML profile parser
  scraper/                 # Job scrapers
    base.py                #   Scraper base class
    boss.py                #   Boss直聘 scraper
    linkedin.py            #   LinkedIn scraper
  cli.py                   # CLI entry point (Click)
  config.py                # Configuration (pydantic-settings)
  domain.py                # Data models (Pydantic)
profiles/
  example.yaml             # Profile template
docs/
  architecture.md          # Architecture docs
tests/
  test_models.py           # Tests

📋 Platform Support

Platform Scraping Applying Notes
LinkedIn ✅ ✅ Easy Apply automation
Boss直聘 (zhipin.com) ✅ ✅ Playwright-simulated greeting
Lagou (拉勾) 🔜 🔜 Adapter in development
51Job (前程无忧) 🔜 🔜 Adapter in development

🤝 Contributing

PRs welcome! Especially:

  • 🔌 New platform adapters (Indeed, Glassdoor, Lagou…)
  • 🧠 Better matching strategies (prompt tuning, multi-dimensional scoring)
  • 🔒 Reliability improvements (anti-detection, checkpoint/resume)
  • 📢 New notification channels (Slack, WeChat, email)
pip install -e .[dev]
pytest -q

Please run tests, add type hints, and update docs before submitting.

⚠️ Disclaimer

Automated interaction with job platforms may be subject to their terms of service and local regulations. Use this tool responsibly, within your authorized scope. The authors are not liable for misuse.

📜 License

MIT License — see LICENSE.