h2o-agent

AI-powered local resume and cover letter generator for H2O.

Start the server in a working directory, submit a job description, and it uses the Cursor CLI agent to produce tailored resume.md / cover.md files plus PDF output.

Requirements

• Node.js 18+
• Cursor CLI with agent available on your PATH
• Chrome/Chromium for PDF generation (Puppeteer will download a matching browser on first PDF convert if needed)

Quick start

Run from the directory where you want resumes created (profile + job folders live here):

cd /path/to/your/resume-workspace
npx h2o-agent

Or install globally:

npm install -g h2o-agent
cd /path/to/your/resume-workspace
h2o
# or: h2o-agent

Note: The npm package name is h2o-agent (not h2o-server). Use npx h2o-agent.

Default port is 3000. Override with:

PORT=4000 npx h2o-agent

First run

In the current working directory the server will:

1. Ask for your name (used in PDF filenames)
2. Create career_profile.md — replace the placeholder with your real career details
3. Create .h2o-resume-prompt.md — generation instructions (editable)

Then fill in career_profile.md before submitting jobs. Thin/placeholder profiles produce weak resumes.

Generate a resume

# Health check
curl -s http://localhost:3000/health

# Submit a job
curl -s -X POST http://localhost:3000/generate \
  -H "Content-Type: application/json" \
  -d '{
    "name": "acme/senior-frontend-engineer",
    "description": "We are looking for a senior frontend engineer...",
    "theme": "modern"
  }'

# Poll status (use requestId from the response)
curl -s http://localhost:3000/status/REQUEST_ID

Output appears under ./<name>/ in your working directory, for example:

acme/senior-frontend-engineer/
  job_description.txt
  resume.md
  cover.md
  YourName_resume.pdf
  YourName_cover.pdf

Regenerate PDFs only (no AI re-run)

If markdown already exists for that job name:

curl -s -X POST http://localhost:3000/generate \
  -H "Content-Type: application/json" \
  -d '{
    "name": "acme/senior-frontend-engineer",
    "theme": "executive",
    "pdf_only": true
  }'

API

GET /health

Health check.

GET /themes

Lists PDF themes.

{
  "themes": ["classic", "modern", "minimal", "executive", "newspaper"],
  "default": "classic",
  "descriptions": {
    "classic": "Traditional professional with uppercase section headers and subtle line separators",
    "modern": "Contemporary with accent color and custom bullet points",
    "minimal": "Clean and simple with maximum readability",
    "executive": "Sophisticated serif headers with centered name",
    "newspaper": "Editorial newspaper-inspired layout"
  }
}

POST /generate

Queue a generation job (returns immediately).

| Field | Required | Description | | --- | --- | --- | | name | yes | Job folder / identifier | | description | for full runs | Job description text | | theme | no | classic (default), modern, minimal, executive, newspaper | | pdf_only | no | true = rebuild PDFs from existing markdown only |

Example response:

{
  "requestId": "a1b2c3d4e5f6g7h8",
  "name": "acme/senior-frontend-engineer",
  "theme": "modern",
  "pdf_only": false,
  "status": "pending",
  "message": "Job accepted and queued for processing"
}

GET /status/:requestId

Poll job status: pending → processing → completed or failed.

Customizing generation

Edit .h2o-resume-prompt.md in your working directory to change how resumes are written. On startup, if that file differs from the built-in template, the server asks before replacing it.

Tips

• Always start the server from your resume workspace (cd there first), not from the package install directory.

• Keep career_profile.md detailed — the agent only uses facts from that file plus the job description.

• First PDF conversion may need Puppeteer Chrome installed:

  npx puppeteer browsers install chrome

Chrome extension

Pair with the H2O Chrome extension from the GitHub repo to capture job descriptions from the browser and submit them to this local server.

License

MIT