Quick Start
Get started with career-ops in about fifteen minutes: install the open-source AI job-search system, open your AI CLI, and evaluate your first job listing. No coding required.
This guide takes you from zero to your first evaluated job in about fifteen minutes the first time. You will set up the workspace, open your AI coding assistant, and paste a job posting. The agent completes any needed onboarding, then gives you a full report, a score, and a tailored PDF resume.
What you need
You do not need to know how to code. You only need to be comfortable opening a terminal and running a command.
New to the terminal?
If you have never used a command line before, that is completely fine — but this guide is not the place to learn it. To get up to speed quickly, read the Command Line for Beginners handbook by freeCodeCamp. It covers everything you need to follow along here. Once you are comfortable opening a terminal and running a command, come back and continue from Step 1.
AI coding assistant
Install Claude Code, Codex, OpenCode, Qwen Code, or GitHub Copilot CLI — the AI coding assistant that runs this system. career-ops works with eleven CLIs first-class; install any one and log in before continuing.
Node.js 22.13+
Install Node.js — version 22.13 or later (on Node 23, 23.4 or later). It runs the helper scripts and generates PDFs. Older versions fail the setup check, because the tracker's SQLite index needs a newer Node. Check your version with node --version.
Step 1: Set up the workspace
Open a terminal in the folder where you want career-ops to live. The recommended path uses one command; an advanced path with git clone is below it. If Node (22.13+, or 23.4+ on Node 23) or Git are missing, npx will refuse to run — install both first (see prerequisites above).
Recommended — one command
npx @santifer/career-ops initThis clones the latest release into ./career-ops, installs dependencies, and scaffolds the workspace structure. It also detects which AI coding CLI you have installed and tells you the right command to start with. It only installs into a new folder: if ./career-ops already exists and is not empty, the command stops with an error and changes nothing, so running it again will not repair or update an existing workspace.
Move into the workspace when it finishes:
cd career-opsAdvanced — clone the repository yourself
Use this path if you want to track a specific branch, contribute back, or audit the code before installing dependencies.
git clone https://github.com/career-ops-hq/career-ops.git
cd career-ops
npm installHeadless browser (one-time)
career-ops uses a headless Chromium for several jobs: rendering PDFs, checking whether listings are still live, and running full ATS scans. The installer sets it up automatically after dependencies; if that step failed on your machine, install it manually:
npx playwright install chromiumnpm install skips that download when PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD is set in your environment to anything other than empty, 0 or false; in that case, run the command above yourself. On NixOS, skip this step: the downloaded browsers cannot start there, and the repository's flake dev shell provides working ones instead, as the core's NixOS guide explains.
Step 2: Open your AI assistant
From inside the career-ops folder, launch the AI coding CLI you installed.
claudecodexopencodeqwencopilotagypiOnboarding starts when you need your profile
Before your first job evaluation or another workflow that needs your profile, the career-ops agent checks your setup and runs a short onboarding conversation if needed. You can also ask it to run onboarding directly. It asks for your CV, the kinds of roles you are targeting, your compensation range, and your location preference. You reply in plain language and the agent writes the config files for you. The session takes about two to three minutes. Exploring the workspace, reviewing code, or diagnosing your setup does not start onboarding or create profile files.
For developers: the setup check is node doctor.mjs --json, which only reads. Onboarding creates the missing personalization files (modes/_profile.md, modes/_custom.md, modes/_brief.md and voice-dna.md) from their templates with node doctor.mjs --json --init-templates, and never overwrites one you already have.
One unrelated prompt you may see
Some CLIs (Claude Code, for example) ask whether you trust the files in a new folder the first time you open it. That prompt comes from the CLI itself, not from career-ops. Say yes to continue. Accepting it does not start career-ops onboarding.
Paying for Claude Pro or Max? Check what this session is billing
Run node doctor.mjs from the career-ops folder before your first evaluation. It reports your billing source in one line.
If ANTHROPIC_API_KEY is set in your environment, your CLI uses it and bills per token, even while you pay for Pro or Max. That precedence is Claude Code's, not career-ops': the doctor only detects it and tells you. To use your subscription instead, remove the export ANTHROPIC_API_KEY=... line from ~/.zshrc, ~/.bashrc, ~/.profile or a project .env, restart your terminal, and run /login. If you meant to use API credits, nothing is wrong.
The other CLIs each set their own subscription-versus-key rule, which career-ops does not check. See the FAQ for the full answer.
Step 3: Run your first evaluation
Copy the URL of any job ad and paste it into the chat. The agent will complete onboarding first if your profile is not ready. With Claude Code, Antigravity CLI or Pi, prefix it with the explicit command; with the other CLIs, paste the URL and ask the agent to run the auto-pipeline:
/career-ops auto-pipeline https://jobs.example.com/senior-engineer-aiRun the auto-pipeline command with the job URL: https://jobs.example.com/senior-engineer-aiRun the auto-pipeline command with the job URL: https://jobs.example.com/senior-engineer-aiRun the auto-pipeline command with the job URL: https://jobs.example.com/senior-engineer-aiRun the auto-pipeline command with the job URL: https://jobs.example.com/senior-engineer-ai/career-ops https://jobs.example.com/senior-engineer-ai/skill:career-ops auto-pipeline https://jobs.example.com/senior-engineer-aiIf you do not have a URL, paste the full job description text into the chat instead. The agent detects either input as a job posting and runs the full pipeline automatically — this is the auto-pipeline.
What happens next
After you paste the job, career-ops does the following on its own:
Reads the job description
Understands the role, requirements, and compensation.
Reads your CV
Pulls from cv.md to find matches and gaps against the role.
Scores the job
Rates the role from 1 to 5 across multiple dimensions, like role fit, compensation, and remote policy.
Writes a report
Saves a detailed breakdown to the reports/ folder.
Generates a tailored PDF resume
Outputs a version of your CV customized for this specific job to the output/ folder.
Adds a row to your tracker
Logs the application in data/applications.md.
The whole process takes about one to two minutes. When it finishes, career-ops shows you the score and a summary of the report.
Reading your results
The report includes Score Evidence after Risk Summary. It covers five dimensions: CV match, North Star alignment, compensation, cultural signals, and red flags. Each row records an evidence status (supported, partial, or unknown), a concrete source or observation, and an unresolved question. The section ends with an evidence-confidence tier (High, Medium, or Low), its reason, and up to three verification priorities.
Open the report file in reports/. The filename follows the pattern {number}-{company}-{date}.md. Inside, you will find:
- Score — a number from 1 to 5. Anything below 4.0 means the job is probably not a strong fit.
- Block A — a plain-English summary of the role.
- Block B — a table showing how your CV matches each job requirement, plus any gaps.
- Block C — a strategy recommendation for how to position yourself for this role.
- Block D — compensation research comparing the offer to market rates.
- Block E — personalization notes for your application.
- Block F — interview preparation with STAR stories tailored to this job.
- Block G — posting legitimacy: a heuristic check of signals such as whether the posting is still open and whether it keeps being reposted. It reports what it finds and leaves the judgment to you.
- Block H — draft answers for the application form, written only when the score is 4.5 or higher.
Right after Block G, the Verdict gives the call in bold (Apply, Consider, Research first or Skip) and one reason drawn from the blocks above, so you know the answer before reading the rest.
Your tailored PDF resume is in the output/ folder. Review it before sending it anywhere — career-ops never submits anything without your approval.
What to do next
Now that your first evaluation is done, here are a few things you can explore:
- Refine your profile. Tell the agent something new about yourself — "Here is more context: I just shipped X." It updates the profile and future evaluations get more accurate.
- Evaluate more jobs. Paste more URLs or descriptions. Each one adds to your tracker.
- Scan job boards. Type
/career-ops scanto search dozens of pre-configured company career pages at once. - Compare offers. If you have several reports, type
/career-ops ofertasto get a ranked comparison.
Troubleshooting
Found a bug or have a question?
If something is not working the way this guide says it should, please report it. Bug reports help everyone who comes after you.
- Report a bug: Open an issue on the GitHub repository. Describe what you expected to happen, what actually happened, and paste any error message you saw.
- Ask a question: Join the Discord community. It is the fastest way to get help from other users and the author.
- Contribute a fix: If you know how to fix the issue yourself, read CONTRIBUTING.md before opening a pull request. The short version: open an issue first for a new feature, a new mode or command, or an architecture change. Bug fixes, new zero-auth scanner providers, docs and translations can go straight to a pull request.