convez.ai
Skill
suraj-davariya

ai-job-search

suraj-davariya/ai-job-search

Ver no GitHub
BomPluginScore · de 0 a 100

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

Instalação

$npx convez-ai suraj-davariya/ai-job-search

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
24
Forks
4
Acompanhando
0
Saúde
57%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

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.

Live Docs Live Dashboard Demo

License: MIT Built with Claude Code AI-Native Agents Skills Commands Prompt-as-code

Next.js React TypeScript Tailwind CSS LaTeX docs-site CI Local-first Country-agnostic PRs Welcome


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:

StepYou sayWhat happens
1. Build your profile/setupClaude reads your existing CV, LinkedIn export, diplomas, or interviews you — then writes your candidate profile
2. Find new jobs/searchClaude 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:

CompilerUsed forWhy
lualatexCVRequired by the fontawesome and lato packages
xelatexCover letterRequired 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

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:

PathWhen to use
A — Scan documentsYou have CVs, a LinkedIn export, diplomas, or reference letters in the documents/ folder
B — Import a CVYou have a single clean CV and want a fast start
C — Live interviewStarting 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:

FileContents
01-candidate-profile.mdIdentity, education, work history, skills, projects
02-behavioral-profile.mdWorking style, culture preferences, motivations
03-writing-style.md(static framework — no personal data)
04-job-evaluation.mdYour strong/weak areas, career goals
05-cv-templates.mdProfile statements per role type
06-cover-letter-templates.md(static templates)
07-interview-prep.mdSTAR stories from your experience
search-queries.mdYour 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:

SyntaxBehaviour
/searchRuns your top 3 priority query categories
/search data sciencePrioritises categories matching "data science"
/search broadRuns 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:

ArgumentBehaviour
(default)Full pipeline with reviewer (--review=full)
--review=quickReviewer skips company research — faster, lower cost
--review=noneSkip 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:

OutputLocation
CV (PDF, 2 pages, English)cv/main_<company>.pdf
Cover letter (PDF, 1 page, posting language)cover_letters/cover_<company>_<role>.pdf
Application rowjob_search_tracker.csv
Fit evaluationIn conversation

Fit scoring (5 dimensions):

DimensionWeight
Technical Skills Match30%
Career Alignment30%
Experience Match25%
Behavioural / Culture Fit15%
Location & LogisticsPass / 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.


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/
SurfaceWhat it does
ApplicationsSort/filter/search the tracker; inline status + notes edits (atomic, state-machine-guarded); + New; detail drawer with guarded PDF preview
OverviewKPI cards (total, applied 7d/30d, avg fit, interview rate) + weekly/status/fit/calendar charts — honest — when a sample floor isn't met
ConsoleRun allowlisted commands and stream their output live; per-company re-run /apply, /upskill, and salary lookups
Companies · Salary · Upskill · Profile · SettingsGrouped/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.


Planned commands (coming in future milestones)

CommandMilestoneWhat it will do
/expandv1.1Enrich your profile with new courses, certifications, or projects
/upskillv1.1Compare your profile against a job or market, produce a skill-gap report and learning plan
/resetv1.2Clear and re-run a specific profile section

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

DataWhere it livesCommitted to git?
Candidate profile.claude/skills/job-application-assistant/No
Generated CVs & cover letterscv/output/, cover_letters/output/No
Application trackerjob_search_tracker.csvNo
Seen-jobs registryjob_scraper/seen_jobs.jsonNo
Source documentsdocuments/No
Salary datasalary_data.jsonNo

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
│   │   ├── expand.md          # /expand — (stub, v1.1)
│   │   └── reset.md           # /reset  — (stub, v1.2)
│   │
│   └── 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
│
├── 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
│
├── 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

MilestoneStatusWhat ships
MVP (Epics 1–5)✅ Complete/setup, /apply (no reviewer), PDF compilation
v1.0 (Epics 6–8)✅ CompleteReviewer agent, /search, application tracker
v1.0 — Dashboard (Epic 9)✅ CompleteLocal tracking dashboard at 127.0.0.1:4480 — view/edit tracker, analytics, run commands from the browser
v1.1 (Epics 10–11)🔜 Planned/expand (profile enrichment), /upskill (skill-gap analysis)
v1.2 (Epic 12)🔜 Planned/reset, interview prep, portal adapter pattern
v2.0💡 FutureTemplate 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):

PathContents
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.mdCanonical 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. Repo views

Ver o original no GitHub

Bom para

Relacionados