Quick Start
Getting Started with career-ops
This guide takes you from zero to your first evaluated job in about five minutes. You will set up the workspace, open your AI coding assistant, let it onboard you conversationally, and then paste a job posting — career-ops gives you back 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, Gemini CLI, Codex, Qwen Code, OpenCode, or GitHub Copilot 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: 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 18+ 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. The command is idempotent — running it again never overwrites files you already have.
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/santifer/career-ops.git
cd career-ops
npm installPDF rendering (one-time)
PDFs are generated by a headless Chromium. Install it once, the first time you set up career-ops on this machine:
npx playwright install chromiumStep 2: Open your AI assistant
From inside the career-ops folder, launch the AI coding CLI you installed.
claudegeminicodexqwenopencodecopilotThe agent will introduce itself
The first time you launch your CLI inside the workspace, the career-ops agent runs a short onboarding conversation. It asks for your CV, the kinds of roles you are targeting, your compensation range, and your location preference. Nothing is edited by hand — you reply in plain language and the agent writes the config files for you. The session takes about two to three minutes.
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. The career-ops onboarding starts right after.
Step 3: Run your first evaluation
Once the agent has onboarded you, you are ready to evaluate a real job posting. Copy the URL of any job ad and paste it into the chat. With Claude Code, 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-aiRun the auto-pipeline command with the job URL: 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 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.
- Block G — posting legitimacy: a check that the listing is real and not a scam or ghost 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:
- 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 to discuss the change, then submit your PR.