cvloom

Manage your CV as one YAML dataset and generate any number of per-job-tailored PDFs from it — deterministically, with an agent-safe MCP layer and PII kept out of git.

Per-job overlays let you tailor a CV for each application by declarative config, not by copying files — so twenty variants stay consistent with one source of truth, and every variant is diffable and reviewable.

Most CV tools render one document well. cvloom manages twenty tailored variants of one dataset — deterministically, with an agent-safe MCP layer and PII kept out of git.

Every command below is runnable in examples/:

$ cvloom build --profile general          # your full CV, from one dataset
  ✓ HTML  → dist/cv.html
  ✓ PDF   → dist/Your_Name_Resume.pdf

$ cvloom build --profile example-job      # …same data, tailored for a specific role
  ✓ HTML  → dist/example-job-cv.html

$ cvloom diff general example-job         # tailoring is declarative + diffable
  Words: 195 vs 184 (-11)
  Highlights: 12 vs 12

$ cvloom check --profile example-job      # writing lint — no fake "ATS score"
  wl-002  writing  projects  cvloom  No quantification found  Add metrics.

$ cvloom match --jd stripe-infra-jd.txt --profile example-job
  Coverage: 41% (27 of 66 JD keywords found)

Change a fact once in data/ and every profile that uses it updates on the next build. See the worked one dataset, N applications example.

Features

Quickstart

Install

# Install globally:
uv tool install cvloom

# Development setup:
git clone https://github.com/SWEStash/cvloom
cd cvloom
uv sync --all-extras

The repo root is the tool itself; a runnable demo CV lives in examples/ (cd examples && cvloom build --profile general --public). examples-es/ is the same project in Spanish — a separate directory because a cvloom project operates in one language. See Locales.

Initialise a new CV project

mkdir my-cv && cd my-cv
cvloom init                # or: cvloom init --locale es

Scaffolds the directory structure, creates sample YAML files, writes cvloom.yaml, and installs the pre-commit PII scanner. cvloom list-locales shows the languages available and how completely each is supported.

Upgrade

uv tool upgrade cvloom
cvloom sync   # refresh scaffolded files (hook, publish workflow); reports first, --force applies

See Keeping your instance updated; check the CHANGELOG for breaking changes before a major upgrade.

Edit your content

cvloom.yaml              # project settings — `locale:` is the language it operates in

data/
├── basics.yaml          # headline, summary, public links
├── work.yaml            # work history
├── education.yaml       # education
├── skills.yaml          # skills by category
├── projects/            # one .yaml per project
└── (optional)           # publications, certifications, awards, languages

private/
└── contact.yaml         # name, email, phone, address — GITIGNORED

Build

cvloom build                          # default profile, HTML + PDF
cvloom build --profile backend-role   # specific profile
cvloom build --public --skip-pdf      # HTML only, placeholder contact
cvloom build --profile NAME --check   # build + writing-lint breakdown

Outputs land in dist/. See docs/user/cli-reference.md for the full command reference.

AI Features

Optional AI-powered analysis layered on top of the rules-based tools. Works with any OpenAI-compatible backend — local models via Ollama, cloud routing via LiteLLM, or OpenAI directly. All existing commands work unchanged when AI is not configured.

Setup

uv tool install 'cvloom[ai]'   # see docs/user/ai-features.md#installation for pipx/pip/dev-checkout

export CVLOOM_AI_BASE_URL=http://localhost:11434/v1   # Ollama, LiteLLM, OpenAI, etc.
export CVLOOM_AI_API_KEY=ollama                        # or your real key
export CVLOOM_AI_MODEL=gemma3:27b                      # or gpt-4o, claude-sonnet-4-6

cvloom ai config   # verify — prints where each value came from

The endpoint and model can live in the project's cvloom.yaml instead, under an ai: block, so the repo records which backend analyses it; the environment overrides that. The API key stays in the environment either way — cvloom.yaml is committed.

Commands

ai review — band each CV section strong / adequate / needs work against written criteria, with strengths, weaknesses, and the three highest-impact improvements across the whole CV.

cvloom ai review --profile general

ai cover — generate a tailored cover letter from your CV and a job description file.

cvloom ai cover --profile backend-role --jd stripe-infra.txt --output cover.md
cvloom ai cover --profile cover-letter --jd stripe-infra.txt --body-only

--body-only writes the body paragraphs alone, as a pasteable job_context.notes block — a cover-letter/* template supplies the greeting, closing and signature from the locale pack, so the finished letter has exactly one of each.

ai suggest — get specific content improvements: new bullet points, skill additions, rewordings, and removals for a target role.

cvloom ai suggest --profile backend-role --role "Senior Platform Engineer"

ai align — qualitative analysis of how well your CV is positioned for a specific JD — tone, framing, narrative gaps — beyond keyword coverage.

cvloom ai align --profile backend-role --jd stripe-infra.txt

See docs/user/ai-features.md for backend quickstarts (Ollama, LiteLLM, OpenAI) and all configuration options.

Templates

Parses is how the rendered PDF survives text extraction — the step every ATS runs first. Ratings are measured with five independent extractors, from raw content-stream order through geometric reconstruction to the PDF structure tree; only what survives all five is rated safe. It is a property of the layout, not of your writing, so cvloom check does not cover it; cvloom list-templates prints this table, and build warns on anything not rated safe. See ATS-readiness for the measurements.

The non-CV templates are unrated — they are not documents an ATS parses:

Profiles and Overlays

Each profile in profiles/ controls template, section visibility, content selection, section order, and heading text:

# profiles/backend-role.yaml
template: cv/ats-clean
output_filename: jane-smith-backend
sections:
  work: true
  education: true
  skills: true
  projects: true
select:
  work:
    tags: [python, kafka, aws]
section_titles:
  work: "Professional Experience"   # text only — styling stays in the template
job_context:
  company: Stripe
  role: Senior Platform Engineer

Overlays let you patch data per job application — override highlights, exclude entries, filter skills — without duplicating your base CV:

overlays:
  work:
    - match: {company: "Acme Corp"}
      highlights:
        mode: pick
        items: [perf-boost, api-redesign]

Choosing which content appears is a separate select block — per-section, so narrowing work leaves education alone:

select:
  work:
    tags: [python, kafka, aws]
  skills:
    categories: [Languages, Cloud]

Because tailoring is declarative config, two variants are diffable (cvloom diff A B) and always consistent — update a fact once in data/ and every profile that uses it updates on the next build. See the worked one dataset, N applications example, or the full overlay reference.

MCP Server

cvloom includes an MCP server exposing 17 tools for LLM-driven CV management. Data stays local — nothing leaves your machine.

uv tool install 'cvloom[mcp]'   # see docs/reference/mcp-server.md#installation for pipx/pip/dev-checkout
cvloom-mcp

AI tools require the ai extra and a provider — CVLOOM_AI_BASE_URL, or an ai.base_url in the project's cvloom.yaml.

See docs/reference/mcp-server.md for setup with Claude Desktop, Claude Code, and example workflows.

Directory Structure

my-cv/
├── .gitignore          # private/ is LINE 1
├── cvloom.yaml         # project settings — the language it operates in
├── data/               # CV content (committed, PII-free)
├── profiles/           # build configs (committed)
├── private/            # GITIGNORED — contact.yaml, cover letters
├── dist/               # GITIGNORED — build output
├── templates/          # Jinja2 templates (or use built-in)
├── .github/workflows/  # publish-cv.yml, scaffolded by `init`
└── .git/hooks/         # pre-commit PII scanner, installed by `init`

Documentation

User Guides

Reference

Developer Guides

License

MIT