Quick Start
Getting Started with Career Ops
This guide walks you through setting up Career-Ops and running your first job evaluation. By the end, you will paste a job posting and get back a full report, a score, and a tailored PDF resume — all in one step.
What you need before you start
You do not need to know how to code. You only need to be comfortable running commands in a terminal.
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, or Qwen CLI — the AI coding assistant that runs this system. Career-Ops works with all of them. Log in before continuing.
Node.js 18 or later
Install Node.js version 18 or later — a JavaScript runtime used for generating PDFs and running helper scripts.
Step 1: Download the project
Open a terminal and run the following command to clone the project to your computer:
git clone https://github.com/santifer/career-ops.gitThen move into the project folder:
cd career-opsInstall the required packages:
npm installInstall the browser that Career-Ops uses to generate PDF resumes:
npx playwright install chromiumWhen the commands finish, you are ready to configure the system.
Step 2: Verify your setup
Before you configure anything, run the setup checker to make sure everything installed correctly:
npm run doctorThe output tells you what is working and what is missing. Fix any issues it flags before moving on.
Step 3: Create your profile
Your profile is a simple text file that tells the system who you are. Career-Ops uses it to score jobs against your background and preferences.
Copy the example profile to create your own:
cp config/profile.example.yml config/profile.ymlNow open config/profile.yml in any text editor and fill in your details. The most important fields are:
| Field | What to put |
|---|---|
full_name | Your full name |
email | Your email address |
location | Your city and country |
target_roles.primary | The job titles you are looking for |
compensation.target_range | Your salary target (for example, "$120K-160K") |
narrative.headline | One sentence that describes your professional identity |
You do not need to fill in every field right now. The required ones above are enough to get started.
Step 4: Add your CV
Career-Ops reads your CV every time it evaluates a job. It uses your actual experience to check how well you match each role.
Create a file called cv.md in the project's root folder. Paste your CV into it using plain text. Use this structure as a guide:
# Your Name
## Summary
Two or three sentences about who you are and what you do.
## Work Experience
### Company Name — Job Title
2022–Present
- What you did and the impact it had.
- Another accomplishment with a number if you have one.
## Skills
Python, SQL, project management, etc.
## Education
University Name — Degree, YearIf you are not sure what to write, look at examples/cv-example.md in this project for a full example you can model yours after.
Tip
The more detail you put in your CV, the better the evaluations get. Include numbers, team sizes, tools, and specific outcomes where you can.
Step 5: Set your target role types
In Step 3, you told the system who you are. This step tells it what kinds of jobs you are going for.
Career-Ops uses a file called modes/_profile.md to understand your target roles. It reads this file every time it scores a job, so the evaluations match your actual goals — not someone else's.
The template that ships with Career-Ops includes example roles in AI and machine learning. If that is not your field, you will replace them with your own. Either way, you need to create the file first.
Copy the template to create your personal file:
cp modes/_profile.template.md modes/_profile.mdImportant
modes/_profile.md is never saved to version control. It is safe to put personal details, salary expectations, and career notes in it.
Now open modes/_profile.md in a text editor. The template has comments in it that explain each section. The key sections to fill in are:
| Section | What to write |
|---|---|
| Your Target Roles | The role types you are applying for (for example, Senior Backend Engineer or Data Engineer). List each one with a short description of what that kind of employer is looking for. |
| Your Adaptive Framing | For each role type, which of your projects or experiences to highlight. This helps the system talk about your work in terms each employer cares about. |
| Your Exit Narrative | A short summary of your career story — where you have been and where you are headed. The system uses this when writing your CV summary and cover letters. |
| Your Comp Targets | Notes on salary ranges for your target roles. The system uses this to flag whether an offer is above or below market. |
| Your Location Policy | Whether you are open to remote, hybrid, or on-site work, and how strictly to score roles that do not match your preference. |
Once this file exists, Career-Ops uses it for every evaluation going forward.
Step 6: Open your AI assistant
If you are using Claude Code, run this from the project folder:
claudecodexopencodeqwenImportant
The first time your AI assistant opens in this folder, it may ask if you trust the project files. Say yes to continue.
Step 7: Evaluate your first job description
You are ready to run your first evaluation. There are two ways to do this:
Option A — Paste a job URL:
Copy the link to any job posting and paste it directly into your CLI. For example:
/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-aiOption B — Paste the job description text:
If you do not have a URL, copy the full job description text and paste it into the chat.
Career-Ops detects that you shared a job posting and runs the full pipeline automatically. This is called the auto-pipeline.
What happens next
After you paste the job, Career-Ops does the following steps 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 0 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
Open the report file in reports/. The filename follows the pattern {number}-{company}-{date}.md. Inside, you will find:
- Score — a number from 0.0 to 5.0. 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.
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:
- Improve your profile. Open Claude Code and say: "Here is more context about me: [paste details]." The system updates your profile and future evaluations get more accurate.
- Evaluate more jobs. Paste more URLs. Each one adds to your tracker.
- Scan job boards. Type
/career-ops scanin the Claude Code chat to search dozens of company career pages at once. - Compare offers. If you have several reports, type
/career-ops ofertasto get a ranked comparison.
If something goes wrong
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 to discuss the change, then submit your PR.