honest-cv

honest-cv

Currículos honestos e compatíveis com ATS, adaptados a cada vaga, gerados pelo seu agente de IA. honest-cv é um servidor MCP, uma CLI e uma skill do Claude Code. Ele mantém uma única fonte de verdade sobre sua experiência e a transforma em PDF e DOCX para cada tipo de vaga. Nunca afirma uma habilidade que você não possui.

Leer en español

Por quê

Muitos currículos que não recebem retorno não falham no design. Eles falham na segmentação e em detalhes que quebram silenciosamente a extração de texto. A IA torna o problema oposto fácil: um modelo pode facilmente preencher um currículo com palavras-chave que você não consegue defender em uma entrevista. honest-cv é construído em torno de três ideias:

• O código impõe honestidade, não um prompt. Cada habilidade tem um nível. Uma habilidade em nível de familiaridade é sempre rotulada como tal, e uma habilidade que você não possui nunca é impressa. Aumentar um nível exige evidência escrita e sua confirmação, que o servidor pede diretamente a você. O modelo não pode confirmar em seu nome.
• As lacunas são medidas contra seu próprio inventário. Para cada palavra-chave que uma vaga pede, honest-cv informa qual dos três casos se aplica:
  • você tem, mas este currículo não mostra;
  • você só conhece em nível de familiaridade;
  • você não tem.
• A segurança ATS é verificada em cada build. Cada PDF passa por dois extratores de texto (pypdf e pdfminer.six). O build verifica se o texto está em uma coluna, não tem ligaduras, mantém cada data na linha da respectiva função, segue a ordem de leitura correta e inclui todos os bullets.

O servidor é determinístico e não precisa de chave de API. O modelo do seu cliente MCP conduz a conversa; honest-cv valida, constrói, verifica e mede. Ele mantém seu perfil em uma pasta na sua máquina e nunca o envia a lugar algum: veja Privacidade para saber o que seu cliente de IA faz com ele.

Início rápido

honest-cv precisa de uv. Typst e as fontes vêm dentro do pacote, então não há mais nada para instalar. Ele roda em Linux (glibc) em x86_64 e ARM64, macOS em Intel e Apple Silicon, e Windows em x64. Alpine Linux e Windows em ARM não são suportados, porque o pacote typst não publica wheels para eles.

Claude Code

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

Para instalar também a skill, que orienta a entrevista e a adaptação:

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

Depois siga Seu primeiro currículo, passo a passo.

Cursor

Adicione isto a ~/.cursor/mcp.json, ou a .cursor/mcp.json em um projeto:

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

Claude Desktop

Edite claude_desktop_config.json:

• no macOS, ~/Library/Application Support/Claude/;
• no Windows, %APPDATA%\Claude\.

Adicione o mesmo bloco mcpServers do exemplo do Cursor e reinicie o aplicativo. Se o aplicativo não encontrar uvx, use o caminho absoluto (which uvx).

Como cada cliente confirma uma atualização de habilidade

Aumentar o nível de uma habilidade exige sua própria confirmação, que o servidor pede por meio de elicitação MCP. Nem todo cliente suporta isso ainda:

Cliente	Onde você confirma
Claude Code	No chat: um formulário com um campo "não / sim" por atualização, até 10 por vez. Apenas as que você responder "sim" são salvas; Decline não salva nada.
Claude Desktop	Em um terminal. O servidor recusa a alteração e fornece o comando para executar: uvx honest-cv skill <profile> "<name>" <level> --evidence "...".
Outros clientes	No chat se suportarem elicitação, caso contrário em um terminal como acima.

Seu primeiro currículo, passo a passo

Este passo a passo usa Claude Code; qualquer cliente MCP funciona da mesma forma, apenas a configuração difere.

1. Instale o uv e adicione honest-cv. Apenas uma vez. No macOS ou Linux:

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 é a pasta onde seu perfil ficará. Ela não precisa existir ainda e não deve estar dentro de um repositório público. Instale também a skill (Claude Code acima).

2. Inicie a entrevista. Abra o Claude Code em qualquer pasta (claude) e escreva, no seu idioma, "Entreviste-me para meu currículo", ou execute /mcp__honest-cv__interview. O assistente mantém seu idioma durante toda a conversa. Você pode responder por voz com a ditado do seu sistema (no macOS: Ajustes do Sistema → Teclado → Ditado): ele lê nomes e números de volta para você antes de salvá-los, pois o ditado os entende errado. Funciona assim:

Você: Entreviste-me para meu currículo.

Assistente: A pasta ~/cv-profile não existe ainda. Devo criá-la? … Toda a entrevista pode levar algumas horas, mas tudo é salvo conforme avançamos. Uma primeira sessão com seus dados de contato, suas duas funções mais recentes e a lista de verificação de habilidades é suficiente para um primeiro currículo. Você tem uma exportação de dados do LinkedIn ou um JSON Resume para começar?

• Importe, se puder (opcional). Baixe a exportação de dados do LinkedIn (veja Importação) e dê ao assistente o caminho para o ZIP. Suas funções, educação e conquistas entram, e as habilidades chegam sem nível para você marcar.
• Contato, funções e educação. Ele pergunta algumas por vez e lê nomes e números de volta antes de salvar. Depois pergunta uma vez sobre certificações, cursos e qualquer coisa que você escreveu.
• Conquistas, função por função. Para cada função: o que o time fez, o que você fez e o que mudou, com números. Ele rascunha um bullet e só salva após você aprovar o texto.
• Habilidades. Ele oferece uma lista de verificação, ex. backend-jvm + engineering-lead, ou a sua própria para qualquer profissão. Abra ~/cv-profile/checklist.md no seu editor, coloque P, L, F ou X em cada linha, adicione onde você usou após " — ", salve e diga ao assistente "done". Ele pede as evidências que faltam, em grupos. Depois um formulário pede que você confirme as atualizações: apenas o que você responder "sim" é salvo.
• Suas maiores conquistas. Uma conquista geralmente cobre várias habilidades. Ele então pergunta sobre suas principais habilidades P que nenhuma conquista mostra ainda; o resto pode esperar por uma vaga.

3. Construa seu primeiro currículo. O assistente propõe uma variante por tipo de vaga a que você se candidata (por exemplo "plataforma" ou "gerente de engenharia"): título, resumo e quais bullets mostrar. Depois que você aprovar:

Você: Construa meu currículo de plataforma em inglês e espanhol.

O PDF e o DOCX ficam em ~/cv-profile/out/, já verificados quanto à segurança ATS. Sem um cliente de IA, o mesmo é uvx honest-cv build ~/cv-profile -v platform -l en.

4. Adapte-o a uma vaga. Cole a vaga, ou execute /mcp__honest-cv__tailor_for_job:

Você: Aqui está uma vaga: (cole-a). Quão bem eu me encaixo e o que devo mudar?

Você recebe a cobertura de cada variante, as palavras-chave ausentes divididas em você tem, mas este currículo não mostra, apenas familiaridade e você não tem, além das que você marcou na sua lista de verificação mas ainda não respaldou com evidências (ele pergunta onde você as usou), uma variante adaptada para aprovar e o build. Depois ele pode rascunhar uma carta de apresentação, que check_claims verifica antes de ser construída, e registrar a candidatura com o texto da vaga e o que preparar para a entrevista. Quando você conseguir a entrevista, "ajude-me a preparar a entrevista" rascunha perguntas prováveis com respostas das suas próprias conquistas.

5. Volte qualquer dia. Diga "vamos continuar minha entrevista de currículo": ele começa pelo que está faltando. Quando precisar atualizar seu perfil do LinkedIn, diga "atualize meu LinkedIn".

Seu perfil

Um perfil é uma pasta com quatro arquivos YAML. Crie um com honest-cv init ~/cv-profile, ou deixe o prompt interview preenchê-lo com você. Mantenha-o fora de repositórios públicos.

Arquivo	O que contém
profile.yaml	Dados de contato, funções, educação, certificações, publicações, cursos e idiomas.
bullets.yaml	Um conjunto de conquistas, cada uma com um id, um role e tags.
skills.yaml	Seu inventário de habilidades, com níveis e evidências.
variants.yaml	Um plano de currículo por tipo de vaga. Uma variante pode herdar de outra com extends:.

Qualquer texto pode ser uma única string ou uma string por idioma: {en: ..., es: ...}. Currículos podem ser construídos em inglês e espanhol.

Nível	Significado	No currículo
P	Usado em produção em um emprego	Mostrado
L	Seu próprio projeto ou laboratório	Mostrado
F	Familiaridade	Apenas na linha rotulada "Familiaridade"
X	Você não tem	Nunca mostrado, mas registrado para que os relatórios de lacunas sejam honestos

Listas de verificação de habilidades

Registrar dezenas de habilidades uma pergunta por vez é lento. Uma lista de verificação é um arquivo Markdown que você marca no seu editor, uma letra por linha:

## Messaging and streaming
evidence: Payments platform at Acme, 2020–2026
- [P] Kafka — reconciliation flow, 2M events a day · years: 6 · last year: 2026
- [F] RabbitMQ — a workshop and the official tutorials
- [X] NATS

Texto após " — " é a evidência, e uma linha evidence: sob um cabeçalho cobre essa seção. Linhas sem evidência nunca são salvas: elas voltam como pendentes, e seu assistente pergunta sobre elas em grupos. As atualizações são confirmadas uma vez para o arquivo inteiro.

As listas de verificação vêm em inglês e espanhol (--lang es): os nomes em espanhol são sinônimos dos em inglês, então uma habilidade que você marca em espanhol ainda corresponde a uma vaga em inglês.

honest-cv checklist list                                     # backend-jvm, platform-sre, ...
honest-cv checklist new ~/cv-profile backend-jvm engineering-lead
honest-cv checklist apply ~/cv-profile ~/cv-profile/checklist.md

Qualquer profissão funciona. As listas de verificação integradas cobrem software (backend, frontend, mobile, dados, plataforma/SRE, QA, segurança, ML/IA, embarcados, desenvolvimento de jogos, arquitetura, liderança de engenharia) e análise de dados/BI, gestão de produtos e projetos, design de UX, marketing, vendas, suporte ao cliente, finanças e contabilidade, recursos humanos, cadeia de suprimentos, enfermagem e ensino. Um modelo é apenas uma lista Markdown neste formato: salve o seu (ou um que alguém compartilhou) em ~/cv-profile/checklists/ e ele aparece em checklist list e se combina com os outros em checklist new, que também aceita um caminho. Um modelo pode declarar sinônimos, como same: Work Breakdown Structure = WBS, e a pontuação da vaga, as lacunas e a verificação da carta os usam, junto com seus nomes de habilidades. Comece de examples/checklists/event-planning.md. Você também pode aplicar um arquivo que marcou você mesmo, em inglês ou espanhol (años, último uso). Quando terminar, honest-cv nomeia as habilidades P e L que nenhuma conquista mostra, e seu assistente pede um exemplo real de cada uma.

honest-cv checklist list ~/cv-profile                        # yours too, e.g. accounting
honest-cv checklist new ~/cv-profile accounting engineering-lead

Novas listas de verificação para outros tipos de funções são bem-vindas: veja CONTRIBUTING.md.

Veja examples/ada/ para um perfil completo e fictício com três variantes, uma vaga e suas palavras-chave.

Privacidade

• O próprio honest-cv não faz chamadas de rede. Sem contas, sem telemetria, sem chaves de API. Seu perfil é uma pasta de arquivos YAML na sua máquina, e o mecanismo de PDF e as fontes rodam localmente. Você pode verificar: todos os comandos funcionam com a rede desligada.
• Seu cliente de IA é outra questão. O que o modelo do cliente lê por meio das ferramentas vai para o provedor desse modelo, sob os termos do provedor, como qualquer outra coisa que você compartilha em um chat. Isso inclui suas habilidades, bullets e o texto dos seus currículos.
• Alguns clientes copiam arquivos para a nuvem. Para editar arquivos diretamente, o Claude Desktop pode pedir acesso à pasta do perfil e dizer que os arquivos saem do seu dispositivo. As ferramentas de edição do honest-cv tornam isso desnecessário: recuse a solicitação e peça ao assistente para usar as ferramentas.
• Executá-lo em um serviço hospedado o tira da sua máquina. Diretórios como Glama oferecem implantar honest-cv em seus servidores ou testá-lo no navegador. Funciona, mas então seu perfil e seus currículos ficam nesse serviço, sob seus termos. Para seus dados reais, execute-o no seu próprio computador com uvx honest-cv.
• Se você não quer que nada saia da sua máquina, use apenas a CLI (build, verify, score, skill) e edite os arquivos YAML você mesmo.

Importe o que você já tem

honest-cv import lê um arquivo JSON Resume ou a exportação de dados do LinkedIn (Configurações → Privacidade de dados → Baixe seus dados, um ZIP de CSVs, ou sua pasta se o seu navegador descompactou). Peça o arquivo completo: o básico, oferecido quando você escolhe arquivos, tem apenas seu título e resumo, sem cargos. Contato, cargos, educação, certificações, idiomas e as realizações de cada cargo vão para o seu perfil; com um título e um resumo, também cria uma primeira variante, para que build funcione imediatamente.

• Ele apenas adiciona o que falta no seu perfil e nunca sobrescreve. Tente --dry-run primeiro.
• Realizações importadas são marcadas com imported: revise a redação delas.
• Habilidades chegam sem nível, porque nenhum dos formatos diz se você usou uma habilidade em produção. Elas vão para imported-skills.md, uma lista de verificação para você marcar.

O perfil "Salvar em PDF" do LinkedIn muda o layout sem aviso, então ele não é analisado: com um cliente MCP, o prompt import_linkedin_pdf lê o texto e propõe cada seção para você aprovar.

Acompanhe suas candidaturas

honest-cv apps mantém um registro em applications.yaml, dentro da sua pasta de perfil: qual variante e arquivos foram para qual empresa, e cada status com sua data (draft, applied, interview, offer, rejected, withdrawn). Registrar a mesma empresa e cargo novamente atualiza o registro. Com um cliente MCP, seu assistente se oferece para registrar uma candidatura após criar o CV ou a carta, e list_applications aponta aquelas sem novidades há duas semanas. Ele mantém uma cópia de cada arquivo que você enviou em sent/, já que a próxima compilação sobrescreve out/, e o texto da vaga em posts/, já que os links expiram, e o que preparar para a entrevista: pergunte ao seu assistente "o que eu precisava preparar para a Acme?".

Quando você conseguir a entrevista, diga "me ajude a preparar a entrevista da Acme" (ou execute o prompt interview_prep). Para cada palavra-chave da vaga salva, honest-cv apresenta seu nível, suas evidências e os bullets que as sustentam, começando pelos do CV que você enviou. Seu assistente rascunha as perguntas prováveis com respostas STAR tiradas apenas desses bullets, respostas honestas para o que você só conhece em nível de familiaridade ou não tem, e perguntas para fazer a eles. As anotações que você aprovar são salvas em prep/. Sem um cliente de IA: honest-cv apps prep ~/cv-profile acme_sre -k "Kafka,Scala".

LinkedIn

honest-cv linkedin transforma uma variante nos textos do LinkedIn, cada um dentro do seu limite: o título (seu cargo e até cinco habilidades de produção), Sobre (o resumo e os bullets de impacto), uma descrição por posição a partir dos seus bullets e a lista de habilidades. Ele os escreve em um arquivo Markdown para você copiar. As habilidades são apenas P e L: o LinkedIn não consegue rotular familiaridade, então habilidades F ficam de fora, e habilidades X nunca aparecem. Com um cliente MCP, o prompt linkedin_profile aprimora a redação e a verifica com check_claims.

Exportação

Para ir no outro sentido, honest-cv export escreve uma variante como JSON Resume para outras ferramentas e sites de CV, com as mesmas regras do CV: habilidades X nunca aparecem, e habilidades F apenas em um grupo "Familiaridade" com esse nível.

Cartas de apresentação

O prompt cover_letter rascunha uma carta de uma página para uma vaga a partir dos seus próprios bullets. Antes de ser compilada, check_claims lê o texto contra o seu perfil:

• Problemas bloqueiam a compilação: uma habilidade marcada como X, ou uma habilidade de familiaridade apresentada como experiência ("Uso Rust em produção" quando Rust é F; "Estou familiarizado com Rust" é aceitável).
• Avisos são para você revisar: uma tecnologia que nem seu inventário nem seus bullets mostram, ou um número que não aparece em nenhum lugar do seu perfil. Se for verdade, registre-o primeiro; se não, ele sai da carta.

A carta usa as fontes do CV e passa nas mesmas verificações de ATS. Sem um cliente de IA, escreva-a em um arquivo de texto (parágrafos separados por linhas em branco) e use honest-cv letter check e letter build.

CLI

Execute qualquer comando com uvx honest-cv ..., ou instale-o uma vez com uv tool install honest-cv para digitar apenas honest-cv.

honest-cv init ~/cv-profile                        # create the profile templates
honest-cv build ~/cv-profile -v backend -l en -l es # PDF + DOCX, verified on every build
honest-cv verify any-cv.pdf --text                  # check any PDF, even one made elsewhere
honest-cv score ~/cv-profile -k "Kubernetes,Go" -p "Rust"   # coverage per variant, with gaps
honest-cv skill ~/cv-profile "Rust" L --evidence "CLI tool on GitHub"  # asks you to confirm
honest-cv import ~/cv-profile linkedin-export.zip --dry-run         # or resume.json
honest-cv export ~/cv-profile -v backend -l en                       # JSON Resume
honest-cv apps log ~/cv-profile --company Acme --role "SRE" -s applied -v platform
honest-cv apps list ~/cv-profile                                     # latest first, with counts
honest-cv apps prep ~/cv-profile acme_sre -k "Kafka,Scala"           # what backs each keyword, for the interview
honest-cv linkedin ~/cv-profile -v platform -l en                    # texts to paste into LinkedIn
honest-cv remove skill ~/cv-profile "Kafka"                          # asks you to confirm
honest-cv letter check ~/cv-profile letter.txt -k "Kubernetes,Go"     # claims your profile doesn't support
honest-cv letter build ~/cv-profile letter.txt --company Acme --role "Platform Engineer" -l en
honest-cv serve --profile ~/cv-profile              # the MCP server, over stdio

verify funciona em qualquer PDF. Use --text para ver exatamente o que um analisador extrai. Sua verificação single_column também detecta um defeito comum: uma data alinhada à direita, que os analisadores separam do cargo.

Ferramentas e prompts MCP

Nome	O que faz
init_profile	Cria uma pasta de perfil com modelos comentados.
get_inventory	Retorna suas habilidades, agrupadas por nível, com anos e evidências.
set_skill	Adiciona ou altera uma habilidade. Para aumentar o nível, precisa de evidências e pede confirmação.
set_skills	Adiciona ou altera várias habilidades de uma vez. Atualizações são confirmadas com uma pergunta que lista cada mudança.
checklist_list	Lista as listas de verificação integradas.
checklist_new	Mescla listas de verificação integradas em um arquivo, pré-preenchido a partir do seu inventário.
checklist_apply	Salva as habilidades marcadas em uma lista de verificação e retorna as linhas que ainda precisam de evidências.
add_bullet	Adiciona uma realização ao pool.
remove_skill, remove_bullet, remove_role, remove_publication	Exclui permanentemente e remove todos os usos nas variantes. Um cargo com bullets precisa de with_bullets. Os clientes pedem confirmação antes de executá-los.
set_contact	Altera detalhes de contato: nome, e-mail, telefone, localização, links.
set_profile_details	Substitui a lista de certificações, a lista de cursos e a linha de idiomas falados.
upsert_role	Adiciona um cargo em ordem de data, ou altera campos de um existente.
upsert_education	Adiciona ou altera uma entrada de educação.
upsert_publication	Adiciona ou altera um livro, artigo ou trabalho que a pessoa escreveu. Cada variante mostra todos, ou os que lista.
save_variant	Adiciona ou substitui uma variante. Toda referência é verificada antes de salvar.
list_variants	Lista as variantes após herança, com seus textos de bullets e os bullets que nenhuma variante usa.
build_cv	Renderiza um PDF e/ou DOCX e o verifica.
verify_pdf	Executa as verificações de ATS em qualquer PDF e retorna seu texto extraído.
score_job	Mede a cobertura de palavras-chave de cada variante. O cliente extrai as palavras-chave.
gap_report	Agrupa palavras-chave ausentes pelo que você pode fazer honestamente sobre cada uma.
prompt interview	Preenche seu inventário e pool de bullets, uma pergunta por vez.
check_claims	Verifica qualquer texto contra seu perfil: bloqueia habilidades X e familiaridade vendida como experiência, sinaliza o que o perfil não mostra.
build_letter	Renderiza uma carta de apresentação em PDF e DOCX, uma página, com as verificações de ATS do CV. Recusa enquanto check_claims encontrar problemas.
prompt tailor_for_job	Pontua as variantes, explica as lacunas, adapta uma variante e recompila.
prompt cover_letter	Rascunha uma carta para uma vaga a partir dos seus bullets, verifica suas afirmações e a compila.
import_profile	Importa JSON Resume ou uma exportação de dados do LinkedIn, adicionando apenas o que falta. Para um PDF do LinkedIn, retorna o texto.
export_json_resume	Exporta uma variante como JSON Resume; habilidades X nunca aparecem e habilidades F mantêm seu rótulo.
log_application	Registra uma candidatura (empresa, cargo, variante de CV, arquivos enviados, texto da vaga, o que preparar) ou um novo status, com sua data.
linkedin_profile	Título do LinkedIn, Sobre, descrições de posição e habilidades (apenas P e L) a partir de uma variante, dentro dos limites do LinkedIn.
list_applications	Lista candidaturas, mais recentes primeiro, com uma contagem por status e as que estão sem novidades há 14+ dias.
interview_prep	Para uma candidatura: a vaga salva e, por palavra-chave, seu nível, evidências e os bullets que a sustentam. Salva as anotações de preparação.
prompt import_linkedin_pdf	Transforma o PDF do "Salvar em PDF" do LinkedIn em um perfil, seção por seção, com sua aprovação.
prompt linkedin_profile	Aprimora os textos do LinkedIn de uma variante sem adicionar afirmações, verificado com check_claims.
prompt interview_prep	Prepara uma entrevista: perguntas prováveis, respostas STAR dos seus próprios bullets, respostas honestas para as lacunas.

Garantias de ATS

O modelo impõe estas. verify as verifica em toda compilação, e a suíte de testes roda em CI no Linux, macOS e Windows:

• Uma coluna. Sem tabelas de layout, imagens, ícones, cabeçalhos ou rodapés.
• Ligaduras e kerning desativados, sem hifenização, e termos como "CI/CD", URLs e e-mails nunca divididos entre linhas.
• Ordem de leitura igual à ordem de origem. Datas ficam na mesma linha do cargo.
• Texto extraível tanto por pypdf quanto por pdfminer.six, e os dois concordam.
• As fontes (Carlito, metricamente compatível com Calibri) são incorporadas e idênticas em todas as máquinas.

Desenvolvimento

uv sync
uv run pytest
uv run honest-cv build examples/ada -l en -l es

O .mcp.json do repositório registra honest-cv-dev com o perfil fictício, para que o Claude Code nesta pasta possa usar sua cópia de trabalho. Veja CONTRIBUTING.md.

Licença

MIT. A fonte Carlito incluída está sob a SIL Open Font License; veja src/honest_cv/render/fonts/OFL.txt.