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 · machine-translated, 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.
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 (machine-translated, English canonical) + 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):
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. 
