Job Agent

AI-powered job search and application assistant: multi-source hunting, OpenAI matching, cover letters, and hybrid apply (Playwright ATS → Chrome CDP → optional screen OCR → manual assist).

Safety first: read DISCLAIMER.md. Keep require_submit_confirmation: true and prefer --dry-run until you trust the flow.

Architecture

┌─────────────┐   ┌──────────────┐   ┌─────────────────────────────┐
│ Job sources │ → │ OpenAI match │ → │ today.json + daily_report   │
│ LinkedIn    │   │ gpt-4o-mini  │   │ + optional Canvas sidecars  │
│ JobsDB      │   └──────────────┘   └──────────────┬──────────────┘
│ Adzuna …    │                                     │ approve
└─────────────┘                                     ▼
                                         ┌─────────────────────┐
                                         │ ApplyRouter         │
                                         │  Playwright ATS     │
                                         │  LinkedIn CDP       │
                                         │  Screen OCR (macOS) │
                                         │  Manual assist pack │
                                         └─────────────────────┘

Related MCP server: Shortlist MCP Server

Requirements

• Python 3.11+

• OpenAI API key (matching + cover letters)

• Optional: Adzuna App ID/Key

• Chrome (LinkedIn Easy Apply via CDP)

• macOS (Screen OCR fallback; Accessibility + Screen Recording permissions)

Setup

git clone https://github.com/<you>/job-agent.git ~/job-agent
cd ~/job-agent
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
playwright install chromium
cp .env.example .env          # OPENAI_API_KEY, optional ADZUNA_*
cp profile/profile.example.json profile/profile.json
cp profile/answers.example.json profile/answers.json
python -m src.cli onboard     # or edit profile JSON directly

Edit config.yaml for search sources, match threshold, Chrome CDP URL, and paths. Optional Canvas sync: set canvas_dir (or env CURSOR_CANVAS_DIR) to your Cursor canvases folder.

Four ways to use Job Agent

1. CLI

python -m src.cli launch              # tune (if needed) + hunt
python -m src.cli list                # markdown report
./scripts/approve_and_apply.sh <id>   # approve + apply + cover letter
python -m src.cli apply <id> --dry-run
./scripts/start_chrome_debug.sh       # LinkedIn Easy Apply via CDP
python -m src.cli cdp-status

2. Web Dashboard

python -m src.cli dashboard
# or macOS Desktop shortcut:
./scripts/install_desktop_shortcut.sh

Open http://127.0.0.1:8787 — run hunts, batch-approve, paste ATS URLs, manage applied history.

3. Cursor Agent + MCP

1. Open this folder as the Cursor workspace

2. Create the venv and install deps (MCP uses .venv/bin/python — see .cursor/mcp.json)

3. Run ./scripts/verify_mcp.sh

4. Use the job-hunt skill (.cursor/skills/job-hunt/SKILL.md)

Example chat prompts:

• "Run today's job hunt and show top 3 matches"

• "Approve job <id> with cover letter, dry-run only"

• "Tune my profile — ask about missing salary and notice period"

Optional Canvas UI samples live in canvases/. Sync sidecars with python scripts/sync_canvas.py after setting canvas_dir.

4. Cursor Automation

Import automation/daily-job-hunt.yaml:

1. Open Automations in Cursor

2. Import the YAML (cron: weekdays 08:00)

3. Point gitConfig.repo at your clone (~/job-agent)

4. Ensure .env is available to the agent runtime

The automation runs ./scripts/daily_hunt.sh only — no automatic submit. Review matches in the dashboard.

Learning loop (review before it changes your profile)

Nothing is written to your profile automatically. After each apply the agent files proposals into a review inbox; you approve or reject them in the dashboard's Learning tab (or via CLI). Password-like fields are never proposed.

python -m src.cli learn list              # pending proposals (JSON)
python -m src.cli learn approve <id>      # apply it
python -m src.cli learn reject <id>       # drop it

CRM statuses close the loop on their own: interview / offer boost similar companies and titles in future scoring, while rejected / withdrawn down-weight them.

Reliability & ops CLI

python -m src.cli apply-report --days 7    # success rates, failure types, timings
python -m src.cli crm list
python -m src.cli source-eval              # which search sources actually convert
python -m src.cli export-applications --output ~/Desktop/applications.csv
python -m src.cli profile list             # multi-profile switching

Failures are bucketed into login_gate, empty_required, resume_upload, captcha, timeout, and unsupported so apply-report can tell you what to fix next. ATS account walls (Workday and friends) are reported as login_gate with the credential key to add — not as "unsupported ATS".

Config highlights

Tests

pytest

License

MIT — see LICENSE.