What is ai-job-search?

CareerForge — AI job-search assistant inside Claude Code. /search ranks postings from your portals; /apply tailors a CV + cover letter (posting's language), gets a second-AI review, and compiles print-ready LaTeX PDFs; a local dashboard tracks every application. Local-first, country-agnostic — prepares applications, never submits them. It is open-source on GitHub.

Is ai-job-search free to use?

ai-job-search is open-source under the MIT license, so it is free to use.

What category does ai-job-search belong to?

ai-job-search is listed under other in the Claudeers registry of Claude-compatible tools.

CareerForge

An AI job-search assistant that finds postings, writes tailored CVs and cover letters, and compiles them to print-ready PDFs — all on your own machine.

🌍 Read this in your language (alphabetical · 12 available · all beta, English is canonical):

العربية (Arabic) · বাংলা (Bengali) · 简体中文 (Chinese, Simplified) · Deutsch (German) · English · Español (Spanish) · Français (French) · हिन्दी (Hindi) · Bahasa Indonesia (Indonesian) · 日本語 (Japanese) · Português BR (Portuguese) · Русский (Russian)

_{Planned (help translate — i18n/CONTRIBUTING.md): Chinese (Traditional), Dutch, Filipino, Hebrew, Italian, Korean, Malay, Marathi, Persian, Polish, Portuguese (Portugal), Romanian, Swahili, Tamil, Telugu, Thai, Turkish, Ukrainian, Urdu, Vietnamese.}

New here? Start with the guide. The friendliest way to understand CareerForge is the documentation site — Quick Start, all three commands, the dashboard with live demos, privacy, and FAQ. No programming needed to read it.

🌐 Read it now: suraj-davariya.github.io/ai-job-search — hosted, nothing to install.

📊 Click through the dashboard: suraj-davariya.github.io/ai-job-search/dashboard — the real UI on fictional sample data, read-only.

💻 Prefer local? Run npm run dev inside docs-site/ (or see its README for the one-command static build).

What is this?

CareerForge is a job-search toolkit you run inside Claude Code — an AI assistant that lives in your terminal. You type commands and plain-English prompts; the AI does the work. No programming knowledge required.

Here is what it can do for you today:

Step	You say	What happens
1. Build your profile	`/setup`	Claude reads your existing CV, LinkedIn export, diplomas, or interviews you — then writes your candidate profile
2. Find new jobs	`/search`	Claude searches your configured job portals, deduplicates against jobs you've already seen, scores each one for fit, and shows you a ranked table
3. Apply	`/apply <url or paste>`	Claude scores your fit, tailors your CV, writes a cover letter in the posting's language, has a second AI reviewer critique both, applies the edits, compiles two PDFs, and runs a final verification checklist

Your data never leaves your machine. Your profile, CVs, cover letters, and application log are all stored locally and are never committed to git.

How it works — the 3-minute version

Your documents                  CareerForge                     Output
─────────────    ──────────────────────────────────────    ──────────────
  CV / LinkedIn  →  /setup  →  Candidate profile           Profile files
                                    ↓
  Job portals    →  /search →  Ranked job list              Console table
  (configured)           ↓
                      Pick a job
                           ↓
  Job posting    →  /apply  →  Fit score & verdict
                               Tailored CV  (2 pages)  →  cv/main_<co>.pdf
                               Cover letter (1 page)   →  cover_letters/cover_<co>.pdf
                               Reviewer critique
                               Revision pass
                               Verification checklist

What CareerForge does not do:

Submit applications on your behalf (you review and send)
Invent skills or experience you don't have
Upload anything to the cloud

What you need

1. Claude Code

Claude Code is the AI assistant that runs CareerForge. Install it once:

npm install -g @anthropic-ai/claude-code

Then log in:

claude

Claude Code requires an Anthropic account. The Free and Pro plans both work; Pro is recommended for heavy usage.

Not sure what Claude Code is? Think of it as a smart terminal assistant that can read files, search the web, and run commands — guided by the CareerForge instructions.

2. LaTeX (for PDF generation)

CareerForge compiles your CV and cover letter to PDF using LaTeX. Two compilers are needed:

Compiler	Used for	Why
`lualatex`	CV	Required by the `fontawesome` and `lato` packages
`xelatex`	Cover letter	Required by `fontspec` for bundled fonts

macOS (recommended — installs both compilers):

brew install --cask mactex

Or download from tug.org/mactex.

After installing, add the extra CV packages:

sudo tlmgr install fontawesome lato tcolorbox dashrule enumitem multirow \
                   ifmtarg fontaxes mweights pgfopts

Linux (TeX Live):

sudo apt-get install texlive-full   # Debian/Ubuntu

Windows: Install MiKTeX — it fetches missing packages automatically.

3. Python 3.10+ (optional — for salary benchmarking)

python3 --version    # must be 3.10+
pip install openpyxl # only needed if importing salary data from Excel

4. pandoc & poppler (optional — for ATS-safe CV exports)

pandoc --version     # generates the .docx export (and higher-fidelity .txt)
pdftotext -v         # poppler — runs the ATS parse self-check

Without these, /apply still produces the polished PDF and a plain-text .txt; only the .docx export and the PDF parse-check are skipped (graceful degradation).

Quick Start

# 1. Clone the repo
git clone https://github.com/suraj-davariya/ai-job-search.git
cd ai-job-search

# 2. Open CareerForge in Claude Code
claude

# 3. Build your profile (answer Claude's questions or point it at your documents)
/setup

# 4. Search for jobs
/search

# 5. Apply to one
/apply https://company.com/jobs/your-role

Commands in depth

`/setup` — Build your candidate profile

Populates seven profile files from your real data. Claude asks questions or reads your documents — no typing if you have files.

Three onboarding paths:

Path	When to use
A — Scan documents	You have CVs, a LinkedIn export, diplomas, or reference letters in the `documents/` folder
B — Import a CV	You have a single clean CV and want a fast start
C — Live interview	Starting fresh; Claude interviews you

Example prompts:

/setup

/setup --section search

(Jumps straight to updating your target job portals and location preferences without re-running the full interview.)

/setup --section experience

(Updates just your work history — useful after a job change.)

What gets built:

File	Contents
`01-candidate-profile.md`	Identity, education, work history, skills, projects
`02-behavioral-profile.md`	Working style, culture preferences, motivations
`03-writing-style.md`	(static framework — no personal data)
`04-job-evaluation.md`	Your strong/weak areas, career goals
`05-cv-templates.md`	Profile statements per role type
`06-cover-letter-templates.md`	(static templates)
`07-interview-prep.md`	STAR stories from your experience
`search-queries.md`	Your target job portals, queries, location tiers

`/search` — Find new job postings

Searches your configured job portals via web search, deduplicates against jobs you've already seen, assigns a fit signal (High / Medium / Low), and presents a ranked table. When you pick a number, the job is handed straight to /apply.

Arguments:

Syntax	Behaviour
`/search`	Runs your top 3 priority query categories
`/search data science`	Prioritises categories matching "data science"
`/search broad`	Runs all configured query categories

Example prompts:

/search

/search machine learning

/search broad

Example output:

Found 7 new positions (2 high, 3 medium, 2 low match)

 #  Fit     Title                    Company        Location        Deadline   URL
 1  High    Senior Data Engineer     Acme Corp      Amsterdam, NL   2026-06-20  …
 2  High    ML Platform Engineer     Beta Labs      Remote (EU)     Open        …
 3  Medium  Data Analyst             Gamma AG       Berlin, DE      2026-06-15  …
…

Want me to evaluate any of these in detail? Just give me the number(s).

All portals come from your config. Nothing is hardcoded — add any job board (LinkedIn, Indeed, Jobindex, Stepstone, etc.) to search-queries.md and it is automatically included.

`/apply` — Produce a tailored CV and cover letter

Takes a job URL or pasted description and runs the full application pipeline:

Step 0  Parse posting (URL or paste)
Step 1  Score fit across 5 dimensions → verdict + approval gate
Step 2  Draft tailored CV (English, 2 pages) + cover letter (posting language, 1 page)
Step 3  Spawn a fresh AI reviewer → critique both documents
Step 4  Apply reviewer edits + verify every company claim independently
Step 5  Compile PDFs (lualatex for CV, xelatex for cover letter) → inspect layout
Step 6  Record application in tracker → run full verification checklist

Arguments:

Argument	Behaviour
(default)	Full pipeline with reviewer (`--review=full`)
`--review=quick`	Reviewer skips company research — faster, lower cost
`--review=none`	Skip reviewer entirely — fastest, lowest cost

Example prompts:

/apply https://careers.acme.com/jobs/senior-data-engineer-42

/apply --review=quick https://careers.acme.com/jobs/ml-platform-engineer

Or paste the job description directly:

/apply
[paste job description here]

What you get:

Output	Location
CV (PDF, 2 pages, English)	`cv/main_<company>.pdf`
Cover letter (PDF, 1 page, posting language)	`cover_letters/cover_<company>_<role>.pdf`
Application row	`job_search_tracker.csv`
Fit evaluation	In conversation

Fit scoring (5 dimensions):

Dimension	Weight
Technical Skills Match	30%
Career Alignment	30%
Experience Match	25%
Behavioural / Culture Fit	15%
Location & Logistics	Pass / Fail

Verdict: Strong (75+) · Good (60–74) · Moderate (45–59) · Weak (30–44) · Poor (<30)

Language rule: the cover letter is always written in the job posting's language. A Danish posting → Danish cover letter. The CV is always in English.

`/upskill` — Find your skill gaps and a plan to close them

Compares your profile against demand and produces a prioritised gap heatmap, a learning plan built from real, web-searched resources, and a dependency-aware study order — then saves it all as a report the dashboard can show you.

Two modes:

Syntax	Mode	What it analyses
`/upskill`	Aggregate	Every job in your tracker, weighted so the roles you fit least count most
`/upskill <url>`	Targeted	One posting (paste the text if the URL won't fetch)

What you get:

Output	Location
Gap heatmap (Critical / High / Medium / Low)	In conversation
Learning plan — 2–3 resources per gap, with study direction + time estimate	In the report
Study order with total time	In the report
Saved report (with since-last-run delta in aggregate mode)	`upskill/report-*.md`

Reports appear in the dashboard's Upskill tab. Nothing is fabricated — every resource comes from a live web search, and an empty tracker gets an honest nudge toward targeted mode rather than an empty report.

`/expand` — Grow your profile from everything you've already done

Finds competencies you have but haven't written down — from your documents, your public GitHub repos, and the web — and adds them to your profile. It never edits or removes what's already there.

How it works:

Scans documents/, your GitHub repositories (READMEs, languages, topics), and other profile links (portfolio, Kaggle, Scholar).
Enriches each find via web search — both a direct lookup (course syllabi, certification skill lists, tool docs) and inference about the methods and toolchains the work implies.
Shows you a competency map grouped by category, each item traced to its source and marked direct / inferred — for your review before anything is written.
Adds only what you approve, each with a source note like (Coursera — Deep Learning Specialisation). Those notes make re-runs idempotent, and inferred behavioural traits are clearly labelled.

Example prompts:

/expand

/expand github

(Prioritises your GitHub repositories as the source to mine.)

Because every addition is additive and source-annotated, you can run /expand again after a new course or project and it only brings in what's genuinely new.

`/reset` — Start over, safely

Clears your personal data so you can begin again — a new career direction, a fresh profile, or handing the repo to someone else — without touching the framework that makes CareerForge work.

Scopes:

Syntax	Clears
`/reset profile`	Your profile skill files (back to blank templates)
`/reset documents`	Your files in `documents/` (folder structure + README kept)
`/reset all`	Both

It always shows you an inventory first (what will be cleared vs. what's preserved), and nothing happens until you type RESET in capitals — any other reply cancels. The writing-style guide, scoring framework, cover-letter templates, and the interview-prep framework are never touched; only your data is. There's no undo, so it points you at your git history as the only recovery, then suggests running /setup to rebuild.

The tracking dashboard

A local-only web UI that reads and atomically writes your job_search_tracker.csv as the single source of truth, visualises your pipeline, and can drive the CLI (/apply, /upskill, salary lookups) from the browser. It is an optional companion — deleting it leaves your data and the /apply pipeline untouched.

Try it without installing → Live demo — a read-only walkthrough with fictional sample data. Editing, the Console, and PDF previews are disabled there (they need the app running locally); everything else is the real UI.

cd dashboard
npm install
npm run build
npm run serve          # prints  ▶  http://127.0.0.1:4480/

Surface	What it does
Applications	Sort/filter/search the tracker; inline status + notes edits (atomic, state-machine-guarded); `+ New`; detail drawer with guarded PDF preview
Overview	KPI cards (total, applied 7d/30d, avg fit, interview rate) + weekly/status/fit/calendar charts — honest `—` when a sample floor isn't met
Console	Run allowlisted commands and stream their output live; per-company re-run `/apply`, `/upskill`, and salary lookups
Companies · Salary · Upskill · Profile · Settings	Grouped/benchmarked/report/profile views; theme + read-only preferences

Local by design: binds 127.0.0.1 only (no LAN, no auth, no accounts), makes no outbound network calls, runs commands via a fixed allowlist with no shell, and stores no secrets. A --read-only mode disables every edit and action. See dashboard/README.md and dashboard/ARCHITECTURE.md.

Requires Node 18+. The action layer (running commands from the browser) needs the claude and/or python3 binaries on PATH; when absent, those triggers are disabled and the rest keeps working.

All planned commands have shipped. /setup, /search, /apply, /upskill, /expand, and /reset are all live (v1.0–v1.2). See the Roadmap for what's next.

Example session

Here is a realistic end-to-end walkthrough.

1. First-time setup

you:   /setup
claude: I found files in documents/cv/ and documents/linkedin/. I'll scan them.
        … (reads your CV) …
        Here is what I extracted. [shows proposed profile content]
        Shall I write this to your profile files?
you:   Yes
claude: Done. Your profile is ready.

2. Searching for jobs

you:   /search
claude: Searching your configured portals for the last 14 days…
        Found 9 new positions (3 high, 4 medium, 2 low match)

         #  Fit     Title                Company      Location
         1  High    ML Engineer          Acme Corp    Amsterdam
         2  High    Data Scientist       BetaTech     Remote (EU)
         3  Medium  Analytics Engineer   Gamma GmbH   Berlin
        …
        Want me to evaluate any of these? Just give me the number(s).

you:   1

3. Applying

claude: Running full pipeline for Acme Corp — ML Engineer.

        Fit Evaluation
        ──────────────────────────────────────────────
        Technical Skills Match    92/100  Strong
        Career Alignment          85/100  Strong
        Experience Match          78/100  Good
        Behavioural Fit           80/100  Strong
        Location & Logistics      Pass
        ──────────────────────────────────────────────
        Weighted Total            84 — Strong Fit ✓

        Proceed with drafting?

you:   Yes

claude: Drafting CV and cover letter…
        Spawning reviewer agent…
        Applying reviewer edits…
        Compiling cv/main_acme_corp.tex → main_acme_corp.pdf ✓ (2 pages)
        Compiling cover_letters/cover_acme_corp_ml_engineer.tex → …pdf ✓ (1 page)
        Verification checklist: all 15 items passed.

        Files ready for review:
          • cv/main_acme_corp.pdf
          • cover_letters/cover_acme_corp_ml_engineer.pdf

Privacy

Data	Where it lives	Committed to git?
Candidate profile	`.claude/skills/job-application-assistant/`	No
Generated CVs & cover letters	`cv/output/`, `cover_letters/output/`	No
Application tracker	`job_search_tracker.csv`	No
Seen-jobs registry	`job_scraper/seen_jobs.json`	No
Source documents	`documents/`	No
Salary data	`salary_data.json`	No

The .gitignore enforces all of these exclusions. If you push your fork to GitHub, use a private repository so your profile files are never exposed.

Directory structure

ai-job-search/
│
├── .claude/
│   ├── commands/              # Slash commands you type in Claude Code
│   │   ├── setup.md           # /setup  — build your profile
│   │   ├── apply.md           # /apply  — full application pipeline
│   │   ├── search.md          # /search — discover new job postings
│   │   ├── upskill.md         # /upskill — skill-gap analysis + learning plan
│   │   ├── expand.md          # /expand — competency expansion (additive)
│   │   └── reset.md           # /reset  — clear data, preserve framework
│   │
│   └── skills/
│       ├── job-application-assistant/   # AI knowledge for CV/CL/interview work
│       │   ├── 01-candidate-profile.md  # Your identity, experience, skills
│       │   ├── 02-behavioral-profile.md # Working style, culture fit
│       │   ├── 03-writing-style.md      # Rules: no em-dashes, no buzzwords…
│       │   ├── 04-job-evaluation.md     # 5-dimension scoring framework
│       │   ├── 05-cv-templates.md       # LaTeX CV guide + tailoring rules
│       │   ├── 06-cover-letter-templates.md
│       │   └── 07-interview-prep.md     # STAR stories + practice questions
│       │
│       ├── job-scraper/
│       │   ├── SKILL.md                 # Job-search workflow (REQ-1001–1012)
│       │   └── search-queries.md        # Your portals, queries, location tiers
│       │
│       └── career-development/
│           └── SKILL.md                 # Skill-gap analysis (REQ-3001–3011)
│
├── cv/
│   ├── cfcv.cls               # Custom LaTeX CV class (compile with lualatex)
│   └── main_example.tex       # CV template — copy per application
│
├── cover_letters/
│   ├── cfcl.cls               # Custom LaTeX cover letter class (xelatex)
│   ├── main_example.tex       # Cover letter template
│   └── OpenFonts/fonts/       # Bundled Lato, Raleway, FontAwesome 6 Free TTFs
│
├── i18n/                      # Localization tree — UI/README in 12 languages
│   ├── _meta/languages.json   # Language registry (12 Tier-1 + 20 Tier-2)
│   ├── ui/<lang>/             # ICU UI strings (en = source of truth)
│   └── readme/                # Localized READMEs (English is canonical)
│
├── locale-packs/              # Per-market CV conventions (us, de, jp, br, in, eu…)
│
├── trust-safety/              # Scam-pattern catalog for the legitimacy gate
│
├── documents/                 # Drop your source docs here (gitignored)
│   ├── cv/                    # Existing CVs (PDF or DOCX)
│   ├── linkedin/              # LinkedIn data export
│   ├── diplomas/
│   ├── references/
│   └── applications/
│
├── dashboard/                 # Local tracking dashboard (Next.js, loopback-only)
│   ├── app/                   #   App Router pages + API routes
│   ├── lib/                   #   pure core: parsers, atomic writer, allowlist…
│   ├── components/            #   applications · dashboard · console · views
│   ├── README.md              #   how to launch + security/privacy model
│   └── ARCHITECTURE.md        #   layers, file contracts, perf baseline
│
├── docs-site/                 # Documentation website (newcomer-first guide)
├── upskill/                   # Upskill reports (report-*.md)
│
├── tools/
│   └── convert_salary_excel.py   # Excel → salary_data.json (Epic 7, stub)
│
├── salary_lookup.py           # Salary benchmarking CLI (used by the dashboard)
├── job_search_tracker.csv     # 14-column application log (gitignored)
└── job_scraper/               # Deduplication state (gitignored)

Compiling templates manually

If you want to test the LaTeX templates independently:

CV (run from the cv/ directory):

cd cv
lualatex main_example.tex
# → main_example.pdf

Cover letter (run from cover_letters/ — the working directory matters for font loading):

cd cover_letters
xelatex main_example.tex
# → main_example.pdf

Roadmap

Milestone	Status	What ships
MVP (Epics 1–5)	✅ Complete	`/setup`, `/apply` (no reviewer), PDF compilation
v1.0 (Epics 6–8)	✅ Complete	Reviewer agent, `/search`, application tracker
v1.0 — Dashboard (Epic 9)	✅ Complete	Local tracking dashboard at `127.0.0.1:4480` — view/edit tracker, analytics, run commands from the browser
v1.1 (Epics 10–11)	✅ Complete	`/upskill` skill-gap analysis + learning plan, and `/expand` competency expansion from your docs, GitHub, and the web
v1.2 (Epic 12)	✅ Complete	`/reset`, interview-prep framework, ADR-0004 portal-adapter pattern + example, research agent
v1.3 — Global Reach & Trust (Epics 13–19)	✅ Complete	UI + README in 12 languages (beta) + pluggable locale packs (CV conventions per market); posting-legitimacy gate (scam/ghost-job shield); ATS-safe CV exports (`.txt`/`.docx`) + parse self-check; fabrication-audit Provenance panel; token-free scan tier
v2.0	💡 Future	Template marketplace, community portal adapters, GUI

See the full plan in docs/plan/delivery-strategy.md.

Documentation

Start here → docs-site/ — the documentation website: a newcomer-first guide to the whole product (Quick Start, all three commands, the dashboard with live demos, your data, privacy, FAQ, glossary). Run it locally with npm run dev inside docs-site/, or build it static with npm run build.

Engineering documentation (specifications, architecture, plans):

Path	Contents
`docs/requirements/`	Complete functional requirements (`REQ-####` IDs)
`docs/architecture/`	Technology stack, component design, ADRs
`docs/plan/`	Milestones, epics, work breakdown
`docs/development/`	Coding standards, project structure, contribution guide
`docs/testing/`	Test strategy, test cases (`TC-####` IDs)
`docs/glossary.md`	Canonical terms

Contributing

Contributions are welcome — new CV/cover-letter templates, locale packs, portal adapters, bug fixes, and documentation improvements all help.

⚠️ Use a private fork. Your candidate profile lives in the same directory as the source code. Always work in a private GitHub repository to keep your personal data out of the public internet.

See CONTRIBUTING.md for the full guide, branch naming, PR checklist, and how to add a new job portal or locale.

Licence

MIT — see LICENSE.

Platforms	cli, api, web
Operating systems	—
AI compatibility	claude
License	MIT
Pricing	open-source
Language	MDX

ai-job-search

CareerForge

What is this?

How it works — the 3-minute version

What you need

1. Claude Code

2. LaTeX (for PDF generation)

3. Python 3.10+ (optional — for salary benchmarking)

4. pandoc & poppler (optional — for ATS-safe CV exports)

Quick Start

Commands in depth

`/setup` — Build your candidate profile

`/search` — Find new job postings

`/apply` — Produce a tailored CV and cover letter

`/upskill` — Find your skill gaps and a plan to close them

`/expand` — Grow your profile from everything you've already done

`/reset` — Start over, safely

The tracking dashboard

Example session

Privacy

Directory structure

Compiling templates manually

Roadmap

Documentation

Contributing

Licence

// compatibility

// faq

// embed badge

// retro hit counter

// reviews

// guestbook

// related in Automation & Workflows

CareerForge

What is this?

How it works — the 3-minute version

What you need

1. Claude Code

2. LaTeX (for PDF generation)

3. Python 3.10+ (optional — for salary benchmarking)

4. pandoc & poppler (optional — for ATS-safe CV exports)

Quick Start

Commands in depth

/setup — Build your candidate profile

/search — Find new job postings

/apply — Produce a tailored CV and cover letter

/upskill — Find your skill gaps and a plan to close them

/expand — Grow your profile from everything you've already done

/reset — Start over, safely

The tracking dashboard

Example session

Privacy

Directory structure

Compiling templates manually

Roadmap

Documentation

Contributing

Licence

// compatibility

// faq

// embed badge

// retro hit counter

// reviews

// guestbook

// related in Automation & Workflows

`/setup` — Build your candidate profile

`/search` — Find new job postings

`/apply` — Produce a tailored CV and cover letter

`/upskill` — Find your skill gaps and a plan to close them

`/expand` — Grow your profile from everything you've already done

`/reset` — Start over, safely