MCPcopy Create free account
hub / github.com/MadsLorentzen/ai-job-search

github.com/MadsLorentzen/ai-job-search

Chat with this repo
repository ↗ · DeepWiki ↗ · release v2.0.0 ↗ · + Follow · compare 12 versions
1,614 symbols 4,561 edges 89 files 331 documented · 21% ● updated 46d agov1.7.2 · 2026-09-29★ 44,9824 open issues

Browse by type

⨍ Functions 1,370◇ Types & classes 229↳ Endpoints 15
What it actually does AI analysis from the code graph — generated when you open this
loading…
README

AI Job Search. Pip the courier bird carries an application along a flight path to its destination. The job search that runs on your machine.

CI   Built on Claude Code   MIT license

MadsLorentzen%2Fai-job-search | Trendshift

An AI-powered job application framework built on Claude Code.

Fork it, fill in your profile, and let Claude evaluate job postings, tailor your CV,

write cover letters, and prepare you for interviews.

Quick start     Commands     How /apply works     Customization     Setup guide

[!NOTE] This is an independent open-source project and is not affiliated with, endorsed by, sponsored by, or maintained by Anthropic. Anthropic and Claude Code are referenced only to describe the toolchain this workflow uses.

This project has no affiliated cryptocurrency, token, or paid sponsorship program. Anything claiming otherwise is unauthorized and should be treated as a scam. The only ways to support the project are the Ko-fi link below and contributing on GitHub.

Does it actually work?

I'm a geophysicist by training. When my position was cut in late 2025, I built this framework to run my own job search - the same /scrape, /apply, and /interview workflow in this repo, used weekly, on my own career. I was upfront about it with every employer I spoke to, and instead of counting against me, it usually sparked a genuine technical conversation.

69 envelopes for 69 tailored applications. 20 of them light up as first interviews, and one is sealed as the signed contract.

Sixty-nine tailored applications, twenty first interviews, and one signed contract later, I started as an AI engineer in June 2026. People kept asking whether this actually works. It got me hired. Now it's yours.

The longer version, including the full application funnel, is on LinkedIn.

Did this save you a Sunday of cover-letter writing? Consider a coffee.

Did it land you the job? Maybe two. ☕

Buy me a coffee at ko-fi.com

What this is

A structured workflow that turns Claude Code into a full-stack job application assistant. Six commands carry you from an empty profile to a tracked result:

The workflow in order: /setup builds your profile, /scrape finds new postings, /rank shortlists the fits, /apply tailors a CV and cover letter, /interview preps every round, /outcome tracks each result.

The core workflow (self-profiling, fit evaluation, and the drafter-reviewer application pipeline) is language- and country-agnostic. Job portal search skills live in community-portals, one folder per job board, owned by the people who use it: copy in the ones for your market, or build your own with /add-portal.

The framework encodes career guidance best practices, including structured evaluation criteria, forward-looking cover letter framing, and optional salary benchmarking.

Quick start

🎥 Prefer to see it in action first? The Next New Thing did a hands-on walkthrough of how the workflow is actually used, from setup to a finished application (recorded August 2026 - commands may have evolved since).

What you need

Claude Code The CLI. No free tier: a Claude Pro/Max/Team subscription or Anthropic API credits (pay-per-token, usually cheaper for occasional use).
Python 3.10+ For the tools in tools/.
Bun Runs the job portal CLI tools you copy in from community-portals.
LaTeX A distribution with lualatex and xelatex: TeX Live, MacTeX, TinyTeX, or MiKTeX.
pypdf (optional) pip install pypdf for /apply's ATS parseability check.

Fine print: other agents, LaTeX engines, PDF text extraction

  • Using a different agent tool (Codex, Antigravity, Gemini CLI)? Start at AGENTS.md - portal search skills you copy into .agents/skills/ work there out of the box, and community forks adapt the full workflow.
  • LaTeX engines. The CV compiles with lualatex (pdflatex often fails on modern MiKTeX installs with fontawesome5 font-expansion errors); the cover letter compiles with xelatex because cover.cls requires fontspec. If using a minimal TeX install such as TinyTeX or BasicTeX, install the extra packages listed in SETUP.md.
  • PDF text extraction. pypdf is BSD-licensed and needs no Poppler. Poppler pdftotext remains a fallback (macOS: brew install poppler, Debian/Ubuntu: apt install poppler-utils, Windows: choco install poppler). If both are missing, the check degrades to a visual keyword review.

1. Fork and clone

For your own job search, start from a private copy:

gh repo clone ai-job-search-dev/ai-job-search
cd ai-job-search
git remote rename origin upstream
gh repo create ai-job-search --private --source=. --remote=origin --push
gh repo set-default <your-github-username>/ai-job-search

To contribute changes back, fork instead:

gh repo fork ai-job-search-dev/ai-job-search --clone
cd ai-job-search

[!IMPORTANT] A fork of this repo is always public — GitHub does not allow private forks of public repositories — and /setup (step 3 below) writes your personal data (name, contact details, employment history, salary expectations) into tracked files. Fork only to contribute. Updates work the same way from a private copy; see SETUP.md section 8.

2. Add job portals for your market (optional)

AI Job Search ships no job-board CLIs; without one, /scrape searches with WebSearch. Pick your boards in community-portals (portals/<country>/, or portals/global/ for LinkedIn and multi-market boards), and ask your agent, swapping in your board's folder:

Copy https://github.com/ai-job-search-dev/community-portals/tree/main/portals/dk/jobindex-search into .agents/skills/ and show me its code and what it does. Once I confirm, run python3 tools/install_portal_clis.py (Windows: python tools\install_portal_clis.py).

/setup prints this prompt for the boards you name.

What the installer does

It runs bun install in every portal CLI under .agents/skills/*/cli/ - discovered, not listed, so a portal you copy from community-portals or add with /add-portal is included on a fresh clone. With no portal installed it does nothing. Every install runs with --ignore-scripts, and a CLI whose package.json declares an install-time lifecycle script, trustedDependencies or workspaces, or that has a bunfig.toml or .npmrc beside it, is skipped and reported rather than run. --dry-run shows what it would install.

For zero-dependency portals such as linkedin-search and freehire-search the install is optional: they run with plain bun; bun install only pulls TypeScript dev types.

3. Set up your profile

claude
# Then inside Claude Code:
/setup

/setup offers three paths: read your documents/ folder if you have one populated (CV PDF, LinkedIn export, diplomas, reference letters, past applications), import a single CV pasted in chat, or walk through an interview. It auto-detects what you have and asks. Documents-folder mode is idempotent and safe to re-run as you add more material; see documents/README.md for the layout.

4. Search for jobs

/scrape

This searches multiple job portals for positions matching your profile, deduplicates results, and presents them sorted by fit. Pick a match to run /apply on it directly — or, when a scrape returns more jobs than you want to eyeball, run /rank to batch-score them all against the fit framework and get a ranked shortlist first.

5. Apply to a job

/apply https://boards.greenhouse.io/acme/jobs/1234567

If the URL can't be fetched (some job portals block automated access), you can paste the job description directly instead:

/apply <paste the full job description here>

This runs the full workflow: evaluate fit, draft CV + cover letter, review with a second agent, revise, and present the final output. The posting passes a deterministic integrity gate first (hidden text, invisible characters, instruction-shaped lines, hidden links), and its one-line verdict opens the evaluation; the agents that fetch and review read-only.

[!WARNING] Postings are treated as untrusted input (the workflow follows no instructions embedded in them and fetches no links from their body), but agentic defenses are instruction-level, not a sandbox - on an unfamiliar job board, skim what was fetched and written before you hit send. Details in SECURITY.md.

Commands

/setup, /scrape, and /apply form the core workflow. Ten more commands extend it once your profile is in place.

Command What it does
/setup Builds your profile from your documents, a pasted CV, or an interview
/scrape Searches job portals for postings that match your profile
/apply Evaluates fit, then drafts, reviews, and compiles a tailored CV and cover letter
/rank Batch-scores a scrape into a ranked shortlist
/interview Builds a stage-specific prep pack and runs a mock interview
/outcome Records results, archives what you sent, and drafts follow-ups
/gmail-sync Proposes application status updates from your Gmail
/notion-sync Publishes a read-only view of your pipeline to Notion
/html-report Generates an offline dashboard of your applications
/expand Adds competencies found in your public profiles and course syllabi
/upskill Maps your skill gaps and builds a learning plan
/add-template Registers your own CV or cover letter template
/add-portal Generates a search skill for a job board in your market
/reset Wipes profile data or documents - see Starting over

Full command reference

  • /interview preps you for a scheduled interview on a tracked application. It builds a stage-specific prep pack from the application's archive (the exact posting, the CV and cover letter the interviewer actually read, feedback recorded from earlier rounds), researches the company and interviewers with a verify-before-use rule, maps likely questions to your STAR examples, and offers a mock interview following the roleplay protocol in 07-interview-prep.md. Gaps get honest bridge answers, never invented experience.
  • /outcome records what happened to an application - interview stages, offers, rejections, silence. It archives the submitted CV, cover letter, and posting text into documents/applications/<company>_<role>/, keeps outcome.md in the format /setup Path A parses, and updates the tracker. It also owns the stretch before there is an outcome to record: /outcome followup surfaces open applications that have gone quiet (default 10 days), drafts a short channel-appropriate follow-up in your writing style using only claims from the materials you already submitted (drafts only, never sends; at most twice per application), and offers a thank-you note in the same turn an interview stage is recorded. Once a few applications resolve, it points you back to /setup to calibrate the fit framework from what actually got interviews.
  • /notion-sync publishes a one-way, read-only view of the pipeline into a Notion database via the official Notion MCP server (OAuth, no API keys) - one row per ranked job plus every tracked application, with a write-once briefing page per row. The repo files stay the system of record: nothing syncs back, and documents sync as filenames only. Complements /html-report: that is the deep offline dashboard you regenerate at your desk; this is the glanceable live view from anywhere Notion runs (desktop, web, phone).
  • /gmail-sync reads your Gmail (via the Gmail connector) for sta

Core symbols most depended-on inside this repo

browse all functions →

Shape

Method 1,136
Function 234
Class 229
Route 15

Languages

Python100%

Modules by API surface

tests/test_security_guards.py122 symbols
tests/test_posting_guard.py92 symbols
tests/test_salary_lookup.py91 symbols
tests/test_verify_pdf.py70 symbols
tests/test_robots_check.py69 symbols
tests/test_rank_state.py66 symbols
tests/test_job_key.py63 symbols
tests/test_convert_salary_excel.py58 symbols
tests/test_verify_layout.py55 symbols
tests/test_rank_command.py51 symbols
tests/test_fetch_page.py40 symbols
tests/test_apply_host_check.py40 symbols

For agents

$ claude mcp add ai-job-search \
  -- python -m otcore.mcp_server <graph>

⬇ download graph artifact

Ask about this repo answers extend the page