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.

RenderCV renders one CV beautifully; cvloom manages twenty tailored variants of one dataset — with an agent-safe MCP layer.

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