CV Agent

Generate an ATS-friendly, JD-tailored CV with a single prompt — powered by OpenCode and Claude Opus 4.

You provide your work experience and a job description. The agent handles everything else: selecting relevant experience, writing the CV, fact-checking every claim, and rendering a one-page PDF.

---

What the agent does

1. Reads your experience file and the target job description.
2. Selects only relevant skills, projects, and bullets for the JD.
3. Writes a concise, ATS-optimized CV draft in markdown.
4. Runs a strict fact-check reviewer (returns PASS or REVISE).
5. Automatically revises the draft if the reviewer flags issues.
6. Saves the review report to output/review_report.md.
7. Renders the final one-page PDF.

---

Prerequisites

Before you start, make sure you have:

• A computer with a terminal (Terminal on macOS, or any terminal on Linux/Windows WSL).
• Python 3.8+ installed (macOS comes with Python; on Windows/Linux you may need to install it).
• An Anthropic account — either a Claude Pro/Max subscription or API credits (explained below).

---

Step 1 — Install OpenCode

OpenCode is the AI coding agent that runs the CV generation workflow. Install it in your terminal.

Any platform:

curl -fsSL https://opencode.ai/install | bash

Verify the installation:

opencode --version

You should see a version number. If you get "command not found", close and reopen your terminal, then try again.

---

Step 2 — Connect Anthropic to OpenCode

This agent requires Claude Opus 4 (model: claude-opus-4-6). You need an Anthropic account connected to OpenCode.

Connect your account

1. Open your terminal and run OpenCode (from any directory — credentials are stored globally):

   opencode

2. Inside the OpenCode TUI, type:

   /connect
   

3. Select Anthropic from the list.

4. Choose Claude Pro/Max — your browser will open and ask you to sign in to your Anthropic account. This connects your existing Claude subscription directly.

   Alternative (API key): If you prefer to use a pay-per-token API key instead of a subscription, choose Manually enter API Key. You can generate one at console.anthropic.com under API Keys (requires adding billing credits).

5. Done. Your credentials are now stored locally.

Select the model

Inside OpenCode, type:

/models

Select claude-opus-4-6 (Claude Opus 4). This is the model that delivers the best CV quality. Other models may work but are not tested with this agent configuration.

---

Step 3 — Clone the repo

git clone https://github.com/apm1001/cv-agent.git
cd cv-agent

---

Step 4 — Install Python dependencies

The PDF renderer uses Python and the reportlab library. Run these commands inside the project folder:

# Create a virtual environment
python3 -m venv .venv

# Activate it
source .venv/bin/activate        # macOS / Linux
# .venv\Scripts\activate          # Windows

# Install dependencies
pip install -r requirements.txt

This installs reportlab (the only dependency), which renders the PDF.

Tip: You only need to do this once. The virtual environment is saved in .venv/ and ignored by git.

---

Step 5 — Set up your files

5a. Create your experience file

This is the most important step. The agent can only write what you provide — it never invents facts.

Copy the template:

cp context/experience.example.md context/experience.md

Now open context/experience.md in any text editor and fill it in with your real work history. See the section "How to build your experience file" below for a practical approach.

5b. Set your contact links

Edit icons/links.txt with your real contact info:

gmail: your.email@gmail.com
github: https://github.com/your-username
linkedin: https://www.linkedin.com/in/your-profile/

These appear as clickable icons in the PDF header. Remove any line you don't want shown.

5c. Add a job description

Place the JD file in the jd/ folder. The agent can read multiple formats:

• Text file (.txt) — just paste the JD text.
• PDF (.pdf) — save or download the JD as PDF.
• Screenshot (.png, .jpg) — take a screenshot of the posting; the agent can read images.

Name the file something descriptive, like jd/solidity-engineer-improvs.txt.

---

Step 6 — Generate your CV

1. Make sure your virtual environment is active:

   source .venv/bin/activate

2. Launch OpenCode from the project root:

   opencode

3. Switch to the Cv agent passing TAB. Send one prompt (replace the filename with yours):

   here is the jd @jd/solidity-engineer.txt
   

That is it. The agent will:

• Read your experience and the JD
• Write a tailored CV
• Run the fact-check reviewer
• Fix issues if flagged
• Render the final PDF

Output files

File	Description
output/*.md	CV in markdown (editable source)
output/*.pdf	Final one-page PDF (send this to employers)
output/review_report.md	Fact-check review log

---

How to build your experience file

The context/experience.md file is your personal knowledge base. The more detail you put in, the better CVs the agent produces. Think of it as a master document that contains everything about your career — the agent will select only what is relevant for each specific JD.

What to include

• Every job with company name, role, and exact date range (MM/YYYY - MM/YYYY).
• Every project with what you built, what stack you used, and measurable outcomes.
• Specific numbers: TVL, users, TPS, latency improvements, gas savings, percentage improvements.
• Tools and technologies you actually used (exact names — "Ethers.js" not "ethers").
• Leadership signals: team size, interviews conducted, mentoring, code reviews.
• Security work: audits passed, vulnerabilities found, practices implemented.
• Publications, talks, certifications with dates and verifiable IDs.
• Education with degree, institution, years, and thesis title if relevant.
• STAR examples (Situation, Task, Action, Result) for your best achievements.

Practical approach: voice-to-text with ChatGPT

Building this file from scratch can feel overwhelming. Here is a method that works well:

1. Open ChatGPT (or any voice-capable AI assistant) on your phone.
2. Switch to voice mode.
3. Just talk — describe each job, each project, what you built, what challenges you solved, what the results were. Don't worry about structure.
4. ChatGPT will transcribe and organize your spoken words into structured text.
5. Copy the output into context/experience.md.
6. Repeat for each role / project.
7. Do a final pass to add exact dates, correct company names, and specific numbers.

This approach lets you dump a large amount of information quickly. The more raw material you provide, the better the agent can tailor each CV.

Your experience file is never committed to git (it's in .gitignore). It stays local on your machine.

Template structure

See context/experience.example.md for the recommended structure:

# Your Name — Work Context & Experience Reference

## Snapshot
- Seniority and total years
- Core stack and domains
- Key leadership / security highlights

## Professional Experience

### Company - Role (MM/YYYY - MM/YYYY)
- Action + stack + domain + measurable impact
- Action + security/reliability signal + metric

## Selected Projects
- Project: what you built, stack, outcome

## Publications / Speaking
- Title (Year)

## Education
- Degree, Institution, Years

## Certifications
- Name, Issuer, Year, ID

## Languages
- English (Professional)

---

Project structure

cv-agent/
  context/
    experience.md          # Your private experience (you create this)
    experience.example.md  # Template to get started
    ats_rules.md           # ATS formatting rules (used by agent)
    cv_example_1.pdf       # Reference CV layout
  icons/
    links.txt              # Your contact links
    gmail.png              # Header icons (pre-included)
    github.png
    linkedin.png
  jd/                      # Drop job descriptions here
  output/                  # Generated CVs and review reports
  prompts/
    cv-writer.txt          # Agent system prompt
    cv-fact-reviewer.txt   # Fact-checker system prompt
  scripts/
    render_cv_pdf.py       # PDF renderer
  opencode.json            # OpenCode agent configuration
  requirements.txt         # Python dependencies (reportlab)

---

Important notes

• Privacy: Your context/experience.md and generated outputs are excluded from git via .gitignore. Your personal data stays on your machine.
• Model: This agent is built for and tested with claude-opus-4-6 (Claude Opus 4). Other models may produce lower quality results or fail to follow the multi-step workflow correctly.
• One page: The PDF renderer automatically adjusts font size to fit everything on a single page.
• Multiple JDs: You can generate CVs for different positions by simply dropping a new JD file and running the prompt again. Each run produces separate output files.
• JD formats: The agent accepts .txt, .pdf, and image files (.png, .jpg) as job descriptions. Just tag the file with @jd/filename in your prompt.

---

Troubleshooting

Problem	Solution
opencode: command not found	Close and reopen your terminal after installing. Or install via npm install -g opencode-ai.
No module named reportlab	Activate the virtual environment first: source .venv/bin/activate
python3: command not found	Install Python from python.org
Agent picks wrong model	Run /models in OpenCode and select claude-opus-4-6
PDF renders on 2+ pages	The renderer auto-shrinks font. If still too long, trim lower-priority bullets in the markdown.
Review says REVISE	The agent handles this automatically — it fixes flagged issues and re-runs the reviewer.