maestro-career-studio

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/brand/maestro_lockup_dark.svg">
    <img src="docs/assets/brand/maestro_lockup_light.svg" alt="Maestro Career Studio" width="460">
  </picture>
</p>

<p align="center">
  <a href="https://github.com/seinun-ai/maestro-career-studio/actions/workflows/ci.yml"><img src="https://github.com/seinun-ai/maestro-career-studio/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://github.com/seinun-ai/maestro-career-studio/actions/workflows/codeql.yml"><img src="https://github.com/seinun-ai/maestro-career-studio/actions/workflows/codeql.yml/badge.svg" alt="CodeQL"></a>
  <a href="https://github.com/seinun-ai/maestro-career-studio/actions/workflows/ci.yml"><img src="https://img.shields.io/badge/tests-8%2C081%20passing-brightgreen" alt="Tests"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License"></a>
  <a href="https://maestrocareerstudio.com"><img src="https://img.shields.io/badge/site-maestrocareerstudio.com-1a3a5c" alt="Project site"></a>
  <a href="https://github.com/seinun-ai/maestro-career-studio/pkgs/container/maestro-career-studio-backend"><img src="https://img.shields.io/badge/ghcr.io-multi--arch-blue" alt="Container images"></a>
</p>
<!-- The ghcr badge went up with v0.1.1, once both packages were public — a
     badge for a private package renders as a broken promise. It and the static
     test-count badge are refreshed from the release checklist in
     docs/RELEASING.md; edit them there, not here. -->

### Tailor your resume to every job, without the AI making things up.

Maestro Career Studio is a free, open-source job application studio that runs on
your computer. Every resume is built from things you actually did, every AI edit
is a change you accept or undo, and the result is a real LaTeX or Typst PDF.

- **Same score, every time.** The match score uses fixed rules and runs on your
  computer with no AI service involved, so the same resume and job always get
  the same score.
- **Every AI edit is a diff.** Suggested changes arrive as a before/after you
  accept or undo, one by one.
- **Fills job applications for you.** The browser Companion fills Workday-style
  forms from your saved answers and attaches your resume. You review and submit.

Your career record and application tracker are stored on your computer. When you
use AI features, resume and job information is sent to the AI service you choose.

**Get started:** [install it](#quickstart) → add your resumes → save a job and
get your tailored resume. New to this? The
[Getting Started guide](docs/GETTING_STARTED.md) walks you through every step.

<!-- P4 hero.gif — CLEARED for publish 2026-08-20. Recorded on the mock instance:
     contact header scrubbed (ajey@seinun.com, placeholder phone), lift
     49.2 -> 70.8 is a real deterministic score. Two items reviewed and
     accepted by the owner rather than fixed: the real Visa posting stays (an
     employer-published public document), and the "Liberty Hill, TX" experience
     location stays (already the contact city on the public resume).
     1000px / 10fps / 64 colors, 1.8 MB; re-encode any replacement to match. -->

![Score, tailor, see every AI edit, download the PDF — end to end](docs/assets/hero.gif)

**Works with Claude, Codex or the ChatGPT desktop app** (83 tools) ·
**bring your own AI key** — OpenAI or Gemini; scoring, PDFs and tracking work
without one · **runs on your computer, no account** · **take everything with
you** — your whole record exports to one `career.md` file

> **Made for one person on one computer.** There is no login: anything that can
> reach the app can read and change your whole career record and your saved API
> keys. Out of the box it only listens on your own machine (`127.0.0.1`), so
> that's safe. **Never expose it to a network** — not the internet, your home
> network, or a tunnel. [`SECURITY.md`](SECURITY.md) has the details.

**Contents:** [Why Maestro CS?](#why-maestro-cs) ·
[Prerequisites](#prerequisites) · [Quickstart](#quickstart) ·
[Updating](#updating) ·
[Using it well](#using-it-well) ·
[Driving it from Claude, Codex, or ChatGPT (MCP)](#driving-it-from-claude-codex-or-chatgpt-mcp) ·
[The rest of the toolkit](#the-rest-of-the-toolkit) ·
[Where your files live](#where-your-files-live) ·
[Community & contributing](#community-documentation--contributing) ·
[Licensing](#licensing) ·
[Troubleshooting](#troubleshooting--common-questions)

---

## Why Maestro CS?

**Your time belongs in your career, not in the paperwork around it.** Most of a
job search goes into documents thrown away a week later: a resume rebuilt for
each role, a cover letter written again from memory, the same "tell us about a
time you…" answered for the fourth time. Here you record what you actually did
once, and every document after that is assembled from that record.

**It never writes things you didn't do.** Your work goes into one **career
history**. Resumes are built from the bullets you approved, word
for word; rewording a bullet is a separate step that asks you first. When a job
asks for something your resume doesn't show, Maestro asks you about it — if it's
true, it's saved for every future application; if not, it stays a gap. Every
change is saved as a **resume version**, so you can always compare or go back.

**Real, professional PDFs without the formatting headache.** You edit content in
a simple editor — a bullet is a bullet — and a template handles the layout, so
changing a word can never break the formatting. Switch templates any time
without touching your content, or bring your own design.

**Nothing here is rented.** Free and open source (Apache 2.0), no account, no
subscription. Use the AI service you choose and pay only for what you use —
about a penny per application.

### How it works

- **Your career record.** Upload every resume version you have. Maestro merges
  them into one record of your jobs, projects and skills, removing duplicates.
  Bullets taken unchanged from your files are approved automatically; anything
  merged or written by AI waits for your review.
- **The match score.** Maestro compares your resume with a saved job using
  fixed scoring rules plus a small model that runs on your computer — no AI
  service is involved, so the same resume and job always get the same 0–100
  score. It is **not** an employer's score or a prediction of an interview; use
  it to compare your own drafts and catch gaps. One thing moves over time:
  recent experience counts more, so a score can shift slightly as months pass
  ([`KNOWN_ISSUES.md`](KNOWN_ISSUES.md)).
- **Tailoring.** Suggested changes arrive as a before/after view you accept or
  undo, one by one.
- **PDFs.** Built on your computer with LaTeX or Typst, two professional
  typesetting systems.

### How it compares

Only claims you can check yourself (as of August 2026 — tell us if a row has
gone stale):

| | Typical AI resume builders | CLI skill frameworks (e.g. career-ops) | **Maestro CS** |
|---|---|---|---|
| Match scoring | An AI guesses — same input, different score each run | AI judgment | **Fixed rules — same input, same score, every time** |
| Shows whether tailoring helped | Static score only | Not measured | **Score before and after, per application** |
| See what the AI changed | No history | No | **Every change shown, undoable** |
| PDF output | House web templates | HTML → PDF | **LaTeX and Typst, bring your own template** |
| Career record | None (per document) | Plain markdown/YAML files | **Organized, versioned — exports to one `career.md`** |
| Works with AI assistants | No | Command-line skill files | **83 tools for Claude, Codex, ChatGPT desktop — on your own computer** |
| Submits applications for you | N/A | Never (stated) | **Never without your yes, per application** |
| Cost | $15–75/month | Free + AI usage | **Free (Apache 2.0) + your own AI usage — [≈1¢ per application](#do-you-need-an-api-key)** |

---

## Prerequisites

- **Docker Desktop** (or Docker Engine + Compose v2). Docker runs the app in a
  self-contained box on your computer, so you don't install anything else.
- **On Windows, WSL.** Install Docker Desktop with its WSL 2 engine, and run
  every command below in the Ubuntu (WSL) window from your WSL home folder —
  [step by step](docs/GETTING_STARTED.md#on-windows-use-wsl).
- **Git** — it downloads the app and, later, its updates (macOS offers to
  install it on first use; on Windows, install it inside WSL with
  `sudo apt install git`).
- **Disk space** — about a 1 GB download, roughly 3–4 GB once unpacked. Most of
  it is the PDF tools and the small scoring model.
- **An AI key — OpenAI or Gemini; either one is enough.** It powers tailoring,
  cover letters and screening answers, building your career history, the
  Companion's form filling, and the Assistant. Without a key, scoring, PDFs and tracking
  still work — see [Do you need an API key?](#do-you-need-an-api-key)

---

## Quickstart

> **New here?** [`docs/GETTING_STARTED.md`](docs/GETTING_STARTED.md) is the
> step-by-step version — from installing Docker to your first tailored PDF.

The app is the only required piece; the rest are optional and can be added any
time:

| Piece | What it takes |
|---|---|
| **1. The app** | one `docker compose up -d` (below) — runs on your own computer only |
| **2. An AI key** | **Settings › AI & models** in the app; OpenAI *or* Gemini, [either alone is enough](#5-choose-your-models-deliberately) |
| **3. Your AI assistant** | **optional.** Claude: install the `.mcpb` extension from Settings → Extensions. Codex / ChatGPT desktop: add the plugin from Settings → Plugins. [Details](#driving-it-from-claude-codex-or-chatgpt-mcp) |
| **4. The Companion (browser extension)** | **optional.** `chrome://extensions` → Developer mode → **Load unpacked** → the repo's `extension/` folder. Nothing to configure — [full steps](extension/README.m