superresume

A Claude Code / Cowork plugin that turns one rich Master Profile into job-tailored, ATS-safe, provably-truthful resumes and cover letters.

Most resume tools are AI ghostwriters: you paste a job, they invent impressive-sounding bullets, and 49–62% of hiring managers now penalize resumes they suspect were AI-generated. superresume is built the other way around. It keeps one honest record of what you've actually done, does ~70% of the work in deterministic code, and calls the model only where judgment is genuinely needed — extraction, interview dialogue, reframing, and prose. The AI is an editor, not a ghostwriter.

What makes it different

• Master Profile → Tailored Resume. One un-filtered source of truth (every role, every bullet with a stable ID, every metric). Each tailored resume is a deterministic filter + an AI reframe of it — never a fresh invention.
• Zero fabrication, provable. A code-enforced provenance check runs before every render: every tailored bullet must trace back to a real fact in your Master Profile, every number must trace to a recorded metric, and company/title/dates are copied verbatim. If a bullet can't be traced, the render is blocked. Truthfulness isn't a matter of the model behaving — it's checked.
• The file has to actually parse. After rendering, superresume re-extracts the text from the DOCX and PDF and asserts your headings, contact info, and keywords survived. If they didn't, it doesn't tell you the resume is done.
• Honest positioning — no myths, no fake scores. No "ATS score." No "75% of resumes are auto-rejected" (that's a debunked 2012 sales pitch). Match % appears only as a gap diagnostic for you, never as a grade or a gate.
• Transparency by default. Every reframe is shown before→after with a reason; every excluded role is reported; every gap is surfaced honestly.

The seven sub-skills

| Sub-skill | What it does | |---|---| | profile-builder | Interviews you one question at a time to build/extend your Master Profile; can seed from an existing resume | | job-ingest | Pulls a live posting via public ATS APIs (Lever, Greenhouse, Ashby, Recruitee, Workable); falls back to paste | | jd-analyzer | Extracts must-have vs nice-to-have requirements, keywords, red flags, and a success profile | | resume-tailor | Filters by role-visibility, reframes bullets to the JD, runs a gap-discovery interview, and produces a provenance-checked tailored resume | | resume-render | Renders ATS-safe DOCX + PDF and verifies they parse | | resume-review | Audits any resume: AI-tell/readability lint, keyword-gap %, and a 6-second skim test | | cover-letter | Writes a 250–400 word letter grounded strictly in your resume + the JD |

The pipeline

profile-builder → job-ingest → jd-analyzer → resume-tailor → resume-review → resume-render → cover-letter
   (once)          (per job) ──────────────────────────────────────────────────────────────────►

You can enter at any step and skip around — a single "tailor my resume to this posting" request walks the middle of the chain. Two gates are code-enforced and can't be skipped: the provenance check (inside resume-tailor) and the post-render extraction test (inside resume-render).

Your data

Everything lives locally, outside the plugin, so it survives updates. superresume resolves the data directory as ./.superresume/ (project-local) then ~/.superresume/ (home), creating it on your first profile-builder run.

~/.superresume/
├── master-profile.json      # canonical, stable bullet IDs
├── master-profile.md        # generated read-only view
└── jobs/<company>-<date>/    # one resumable folder per job
    ├── posting.json  jd-analysis.json  tailored-resume.json
    ├── resume.docx   resume.pdf   cover-letter.md   provenance-report.md

See PRIVACY.md for the full data story.

Install

1. Set up the Python core (one time)

The sub-skills shell out to the bundled Python library in core/. It needs Python 3.11+ and a few dependencies. From the repo root:

# create an isolated environment
python -m venv .venv

# install the core library and its dependencies (python-docx, jinja2, playwright, pypdf)
.venv/Scripts/python -m pip install -e .        # Windows
# ./.venv/bin/python  -m pip install -e .        # macOS/Linux

# download the Chromium build Playwright uses to render PDFs
.venv/Scripts/python -m playwright install chromium

Verify it works:

.venv/Scripts/python -m pytest -q          # full test suite should pass
.venv/Scripts/python -m core.cli --help    # lists the subcommands the skills call
.venv/Scripts/python -m core.mcp.server --help  # local MCP server entry point

The skills invoke the core through a bundled launcher script, bash "${CLAUDE_PLUGIN_ROOT}/scripts/core.sh" <command>, which resolves this .venv automatically and sets PYTHONPATH. ... core.sh doctor prints what the environment can do.

Cloud / Cowork / web sessions need no manual setup. A SessionStart hook installs the dependencies into a per-environment cache the first time the plugin runs there; PDF's Chromium is fetched on demand by bash "${CLAUDE_PLUGIN_ROOT}/scripts/bootstrap.sh" --pdf, and if the sandbox won't allow it, rendering degrades to DOCX-only with a clear message. See PACKAGING.md for the full story.

2. Use it from Claude Code / Cowork

1. Install the plugin (via your plugin marketplace or by adding this repo).
2. Ask to build your profile — profile-builder walks you through an interview (or imports an existing resume) and creates ~/.superresume/.
3. Point it at a job: paste a posting URL or the JD text and ask it to tailor your resume.

Local MCP server for Claude and OpenAI/Codex hosts

superresume also ships a provider-neutral local MCP server. It exposes the deterministic Python core as tools, resources, and workflow prompts over stdio or Streamable HTTP.

Run it directly:

.\.venv\Scripts\python.exe -m core.mcp.server --transport stdio

or with the Windows launcher:

.\scripts\mcp.ps1

Run Streamable HTTP locally at /mcp:

.\scripts\mcp.ps1 -Transport http -Port 8765

Endpoint:

http://127.0.0.1:8765/mcp

Run from npm with npx:

npx -y superresume-mcp --help
npx -y superresume-mcp

For PDF support in the npm-managed Python environment, install Playwright's Chromium once:

npx -y superresume-mcp --install-pdf

Install/update the editable package entry point:

.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\superresume-mcp.exe --help

Client configuration examples live in mcp/:

• mcp/claude_desktop_config.example.json
• mcp/codex_config.example.toml
• mcp/chatgpt_http_config.example.md

The MCP server resolves data in this order:

1. SUPERRESUME_DATA_DIR, if set.
2. ./.superresume/, when present or when creating data.
3. ~/.superresume/, only if it already exists.
4. ./.superresume/ as the default creation location.

Exposed MCP tools:

• doctor
• data_status
• profile_view
• parse_resume
• ingest_job
• check_provenance
• lint_resume
• score_resume
• render_resume
• verify_extract
• assess_candidate
• record_outcome

Exposed MCP resources:

• superresume://status
• superresume://master-profile.json, when present
• superresume://master-profile.md, when present
• superresume://references/...

Exposed MCP prompts:

• superresume_full_pipeline
• profile_builder
• resume_review
• cover_letter

How it's built (shared-core-ready)

The repo is a clean three-way split:

• skills/ — thin prose orchestrators (this is the plugin's behavior).
• references/ — a myth-corrected, source-traceable knowledge base (Markdown/JSON). One-file edits change a rule.
• core/ — a pure Python library (schema, render, validate, lint, score, ingest, parse) with no skill-isms, exercised through core/cli.py.

core/ and references/ carry no dependency on the skill layer, so a future web app can import them unchanged — the same deterministic engine behind a different front end, with AI kept behind a metered boundary. v1 is the plugin; the split is deliberate.

What it deliberately doesn't do (v1)

Auto-submitting application forms, non-IT role libraries beyond the seeded set, locales beyond en-US, and interview-prep/salary-negotiation sub-skills are out of scope for v1. The knowledge for form-fill is captured in references/ats-patterns.md for later.

License

MIT — see LICENSE.