honest-cv

# honest-cv

[![CI](https://github.com/JesusCabreraReveles/honest-cv/actions/workflows/ci.yml/badge.svg)](https://github.com/JesusCabreraReveles/honest-cv/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/JesusCabreraReveles/honest-cv/blob/master/LICENSE)

<!-- mcp-name: io.github.JesusCabreraReveles/honest-cv -->

**Honest, ATS-safe CVs tailored to each role, generated by your AI agent.** honest-cv is an MCP
server, a CLI and a Claude Code skill. It keeps one source of truth about your experience and
turns it into a PDF and DOCX for each type of role. It never claims a skill you don't have.

[Leer en español](https://github.com/JesusCabreraReveles/honest-cv/blob/master/README.es.md)

![Demo: skill checklists including your own, scoring a job post, a verified build, a cover letter that refuses a skill the person lacks, LinkedIn texts and logging the application](https://raw.githubusercontent.com/JesusCabreraReveles/honest-cv/master/docs/assets/demo.gif)

## Why

Many CVs that get no callbacks don't fail on design. They fail on targeting, and on details that
quietly break text extraction. AI makes the opposite problem easy: a model will happily stuff a CV
with keywords you can't defend in an interview. honest-cv is built around three ideas:

- **The code enforces honesty, not a prompt.** Every skill has a level. A skill at familiarity
  level is always labeled as such, and a skill you don't have is never printed. Raising a level
  takes written evidence and *your* confirmation, which the server asks you for directly. The
  model can't confirm on your behalf.
- **Gaps are measured against your own inventory.** For each keyword a job post asks for,
  honest-cv tells you which of three cases it is:
  - you have it, but this CV doesn't show it;
  - you only know it at familiarity level;
  - you don't have it.
- **ATS safety is checked on every build.** Every PDF goes through two text extractors (pypdf and
  pdfminer.six). The build checks that the text is one column, has no ligatures, keeps each date on
  its role's line, follows the right reading order and includes every bullet.

The server is deterministic and needs no API key. Your MCP client's model runs the conversation;
honest-cv validates, builds, verifies and measures. It keeps your profile in a folder on your
machine and never sends it anywhere: see [Privacy](#privacy) for what your AI client does with it.

<p align="center"><img src="https://raw.githubusercontent.com/JesusCabreraReveles/honest-cv/master/docs/assets/ada-platform-en.png" width="560" alt="A generated one-page CV for the fictional Ada Example"></p>

## Quick start

honest-cv needs [uv](https://docs.astral.sh/uv/). Typst and the fonts ship inside the package,
so there is nothing else to install.
It runs on Linux (glibc) on x86_64 and ARM64, macOS on Intel and Apple
Silicon, and Windows on x64. Alpine Linux and Windows on ARM aren't supported, because the `typst`
package doesn't publish wheels for them.

### Claude Code

```bash
claude mcp add honest-cv -- uvx honest-cv serve --profile ~/cv-profile
```

To install the skill as well, which guides the interview and the tailoring:

```bash
mkdir -p ~/.claude/skills/honest-cv
curl -fsSL https://raw.githubusercontent.com/JesusCabreraReveles/honest-cv/master/skills/honest-cv/SKILL.md \
  -o ~/.claude/skills/honest-cv/SKILL.md
```

Then follow [Your first CV, step by step](#your-first-cv-step-by-step).

### Cursor

Add this to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` in a project:

```json
{
  "mcpServers": {
    "honest-cv": {
      "command": "uvx",
      "args": ["honest-cv", "serve", "--profile", "/absolute/path/to/cv-profile"]
    }
  }
}
```

### Claude Desktop

Edit `claude_desktop_config.json`:
- on macOS, `~/Library/Application Support/Claude/`;
- on Windows, `%APPDATA%\Claude\`.

Add the same `mcpServers` block as in the Cursor example and restart the app. If the app can't
find `uvx`, use its absolute path (`which uvx`).

### How each client confirms a skill upgrade

Raising a skill's level needs your own confirmation, which the server asks for through MCP
elicitation. Not every client supports it yet:

| Client | Where you confirm |
|---|---|
| Claude Code | In the chat: a form with one "no / sí" field per upgrade, up to 10 at a time. Only the ones you answer "sí" are saved; Decline saves nothing. |
| Claude Desktop | In a terminal. The server refuses the change and gives you the command to run: `uvx honest-cv skill <profile> "<name>" <level> --evidence "..."`. |
| Other clients | In the chat if they support elicitation, otherwise in a terminal as above. |

## Your first CV, step by step

This walkthrough uses Claude Code; any MCP client works the same way, only the setup differs.

**1. Install uv and add honest-cv.** One time only. On macOS or Linux:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh        # Windows: see docs.astral.sh/uv
claude mcp add honest-cv -- uvx honest-cv serve --profile ~/cv-profile
```

`~/cv-profile` is the folder where your profile will live. It doesn't have to exist yet, and it should
not be inside a public repository. Install the skill too ([Claude Code](#claude-code) above).

**2. Start the interview.** Open Claude Code in any folder (`claude`) and write, in your own
language, *"Interview me for my CV"*, or run `/mcp__honest-cv__interview`. The assistant keeps
your language for the whole conversation. You can answer by voice with your system's dictation
(on macOS: System Settings → Keyboard → Dictation): it reads names and numbers back to you before
saving them, since dictation mishears them. It goes like this:

> **You:** Interview me for my CV.
>
> **Assistant:** The folder `~/cv-profile` doesn't exist yet. Shall I create it? … The whole interview
> can take a few hours, but everything is saved as we go. A first session with your contact
> details, your two most recent roles and the skills checklist is enough for a first CV. Do you
> have a LinkedIn data export or a JSON Resume to start from?

- **Import, if you can** (optional). Download LinkedIn's data export (see
  [Import](#import-what-you-already-have)) and give the assistant the path to the ZIP. Your roles,
  education and achievements come in, and skills arrive without a level for you to mark.
- **Contact, roles and education.** It asks a few at a time and reads names and numbers back
  before saving. Then it asks once about certifications, courses and anything you wrote.
- **Achievements, role by role.** For each role: what the team did, what *you* did, and what
  changed, with numbers. It drafts a bullet and saves it only after you approve the wording.
- **Skills.** It offers a checklist, e.g. `backend-jvm` + `engineering-lead`, or your own for any
  profession. Open `~/cv-profile/checklist.md` in your editor, put P, L, F or X on each line, add where
  you used it after " — ", save, and tell the assistant *"done"*. It asks for the evidence it is
  missing, in groups. Then a form asks you to confirm the upgrades: only what you answer
  "sí" is saved.
- **Your biggest achievements.** One achievement usually covers several skills. It then asks
  about your main P skills that no achievement shows yet; the rest can wait for a job post.

**3. Build your first CV.** The assistant proposes one *variant* per kind of role you apply to
(for example "platform" or "engineering manager"): title, summary and which bullets to show. Once
you approve it:

> **You:** Build my platform CV in English and Spanish.

The PDF and DOCX land in `~/cv-profile/out/`, already checked for ATS safety. Without an AI client,
the same is `uvx honest-cv build ~/cv-profile -v platform -l en`.

**4. Tailor it to a job post.** Paste the post, or run `/mcp__honest-cv__tailor_for_job`:

> **You:** Here is a job post: *(paste it)*. How well do I fit, and what should I change?

You get the coverage of each variant, the missing keywords split into *you have it but this CV
doesn't show it*, *familiarity only* and *you don't have it*, plus the ones you marked in your
checklist but haven't backed with evidence yet (it asks where you used them), a tailored variant to approve, and
the build. Then it can draft a cover letter, which `check_claims` checks before it is built, and
log the application with the post's text and what to prepare for the interview. When you get the
interview, *"help me prepare the interview"* drafts likely questions with answers from your own
achievements.

**5. Come back any day.** Say *"let's continue my CV interview"*: it starts from what is missing.
When you need to update your LinkedIn profile, say *"update my LinkedIn"*.

## Your profile

A profile is a folder with four YAML files. Create one with `honest-cv init ~/cv-profile`, or let
the `interview` prompt fill it in with you. Keep it out of public repositories.

| File | What it holds |
|---|---|
| `profile.yaml` | Contact details, roles, education, certifications, publications, courses and languages. |
| `bullets.yaml` | A pool of achievements, each with an `id`, a `role` and `tags`. |
| `skills.yaml` | Your skill inventory, with levels and evidence. |
| `variants.yaml` | One CV plan per type of role. A variant can inherit from another with `extends:`. |

Any text can be a single string or one string per language: `{en: ..., es: ...}`. CVs can be
built in English and in Spanish.

| Level | Meaning | On the CV |
|---|---|---|
| `P` | Used in production at a job | Shown |
| `L` | Your own project or lab | Shown |
| `F` | Familiarity | Only on the line labeled "Familiarity" |
| `X` | You don't have it | Never shown, but recorded so gap reports are honest |

### Skill checklists

Recording dozens of skills one question at a time is slow. A checklist is a Markdown file you mark
in your editor, one letter per line:

```markdown
## Messaging and streaming
evidence: Payments platform at Acme, 2020–2026
- [P] Kafka — reconciliation flow, 2M event