Reading the repo
Reading the repo
Assembly instructions
Open-source AI job search agent and job finder: scan job boards, score each job 1-5 against your CV before you apply, tailor an ATS-friendly resume and cover letter, get interview prep and an application tracker. It helps you fill in each application; you press Submit. Runs locally in Codex, OpenCode and other AI CLIs, or as a Claude Code plugin.
Saved setup from 3 h ago
Will it work on my device?
docs/SETUP.mdgit (npx ships with Node — the installer refuses to run without them). 22.13 is the first release where node:sqlite, used by the tracker index (see tracker), needs no flagClaude Code on the web can run career-ops without a local checkout. It is currently a research preview for eligible Claude plans. A web session clones a GitHub repository into an isolated cloud VM; it does not have your machine's files or local configuration.
Put career-ops in a private GitHub repository that your account can
access. You can use GitHub Importer
with https://github.com/career-ops-hq/career-ops.git as the source. A normal
fork of this public repository is public, so do not use one for personal
career data.
Open claude.ai/code, connect GitHub, and select the private repository and branch. The Default cloud environment is enough for the first run; Anthropic's quick start explains plan-specific onboarding.
Submit this first task:
Set up career-ops in this checkout. Run npm install, then start the first-run
onboarding. Keep cv.md, data/, and reports/ out of Git.
career-ops still uses ordinary workspace files in the cloud checkout, not browser storage:
| Path (from the repository root) | What it holds |
|---|---|
| cv.md | Your master CV |
| data/ | Tracker and other private workflow state |
| reports/ | Job evaluations and generated reports |
cv.md, runtime content under data/, and Markdown files directly under
reports/ are intentionally git-ignored because they contain personal data.
That also means a normal web-session branch push does not persist them to
GitHub: a new cloud session starts from the repository again, without the
ignored files from the previous VM. Keep a personal workflow in one session
and move any output you need to secure storage before its environment expires
(backup patterns). Never force-add these paths. For a durable workspace shared across many
sessions, use the local quick start below.
npx @santifer/career-ops init
npx ships with Node.js — it runs the installer once without installing anything globally. This clones the latest release into ./career-ops and installs dependencies. Then move into the workspace and open your AI CLI:
cd career-ops
claude # or codex / qwen / opencode / agy / grok
On first launch, career-ops walks you through setup by chatting — it asks for your CV, your details (name, target roles, salary), and sets up the job scanner with pre-configured companies. Nothing to edit by hand: just answer its questions. Then paste a job offer URL or description and it evaluates it, writes a report, generates a tailored PDF, and tracks it.
If you are using Codex, start the interactive session with codex. Slash commands are not guaranteed in Codex, so use the same mode names in a prompt if /career-ops is unavailable:
Evaluate this JD with career-ops auto-pipeline: https://company.com/jobs/123
Run the career-ops scan mode.
Run the career-ops pipeline mode.
Run the career-ops pdf mode.
Run the career-ops email mode for the latest evaluated role. Draft only; never sends, submits, or clicks.
Run the career-ops tracker mode.
For one-shot workers or batch tasks in Codex, use codex exec. See docs/CODEX.md for the full guide.
codex exec "Evaluate this JD with career-ops auto-pipeline: https://company.com/jobs/123"
codex exec "Run career-ops scan mode in this repo."
codex exec "Run career-ops pipeline mode for data/pipeline.md."
codex exec "Run career-ops pdf mode for the latest evaluated role."
codex exec "Run career-ops email mode for the latest evaluated role. Draft only; do not send, submit, or click anything."
codex exec "Run career-ops tracker mode and summarize the current statuses."
git clone https://github.com/career-ops-hq/career-ops.git
cd career-ops
npm install
Then open your AI CLI in the folder — the same first-run onboarding applies. Use this path if you want to track a specific branch, contribute, or audit the code before installing dependencies.
</details>If you want to contribute to career-ops, start with a small, focused change. Bug fixes, documentation, translations, and new zero-auth scanner providers can go straight to a pull request; new features, modes, commands, or architecture changes should start with an issue first.
The basic workflow is:
main.cv.md, profile.yml, applications, and reports out of the commit.node test-all.mjs --quick.career-ops-hq/career-ops and explain what changed and why.See CONTRIBUTING.md for the full contribution guidelines and examples of good first contributions.
PDFs are rendered with a headless Chromium. Install it once per machine:
npx playwright install chromium
On NixOS, skip this step: the browsers it downloads can't run there. Use the flake dev shell instead, as described in NIXOS.md.
On macOS releases where Playwright fails to install or launch bundled Chromium (e.g. macOS 12 Monterey), point Playwright to your system Google Chrome installation:
export PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
Node's ordinary fetch() may ignore HTTP_PROXY, HTTPS_PROXY and NO_PROXY in a proxy-only sandbox. Provider requests can use those variables with CAREER_OPS_TRUST_PROXY_EGRESS=1 node scan.mjs. This uses a request-scoped proxy dispatcher; unrelated requests are unaffected, and NO_PROXY destinations still use the local private-address guard.
Set this flag only when the configured proxy itself blocks connections to private, loopback and metadata addresses. When a proxy resolves the destination remotely, career-ops cannot verify that final address locally; the proxy must enforce that part of the SSRF boundary. Without this explicit trust setting, provider requests keep their normal direct transport and a DNS failure names the proxy setup needed. Proxy URLs containing credentials must use HTTPS, except a loopback proxy (localhost, 127.* or ::1), where the credentials never leave the machine; credential-free HTTP proxies remain supported. Existing installations keep direct transport after a system update; proxy environment variables alone do not enable it. Before enabling the flag, run npm install in the career-ops directory to install the added undici dependency. It is loaded only for an opted-in request with a configured proxy, so direct scanning continues to work even before that dependency is installed.
| Action | How |
|--------|-----|
| Evaluate an offer | Paste a URL or JD text |
| Search for offers | /career-ops scan or ask the agent to run scan |
| Process pending URLs | /career-ops pipeline or ask the agent to run pipeline |
| Generate a PDF | /career-ops pdf or ask the agent to run pdf |
| Draft application email | /career-ops email or ask the agent to run email; draft-only, never sends, submits, or clicks |
| Batch evaluate | /career-ops batch or use codex exec "Run career-ops batch mode ..." |
| Check tracker status | /career-ops tracker or ask the agent to run tracker |
| Fill application form | /career-ops apply or ask the agent to run apply |
node cv-sync-check.mjs # Check configuration
node verify-pipeline.mjs # Check pipeline integrity
npm run serve:dashboard # Opens TUI pipeline viewer
npm run build:dashboard # Optional: build the standalone binary
Then run bash setup.sh. It stops at the first error and is safe to run again. Servers and tests aren't started; it lists them at the end. Read it first.
Needs Git: xcode-select --install
git clone https://github.com/career-ops-hq/career-ops.git cd career-ops
Node.js ^22.13.0 || >=23.4.0
# needs nvm: brew install nvm (or https://github.com/nvm-sh/nvm) nvm install 22
Fill in secrets: GEMINI_API_KEY, OPENROUTER_API_KEY
cp .env.example .env
npm install
Fastest way, one command:
npx @santifer/career-ops init
💡
npxships with Node.js: it runs the installer once, without installing anything globally. No Node yet? Install it first. (Already using a Claude Code / Codex CLI? Then you already have it.)
This clones the latest release into ./career-ops and installs dependencies. Then:
cd career-ops
claude # or codex / qwen / opencode / agy / grok — open your AI CLI here
On first launch, career-ops walks you through setup (your CV, profile and target roles) just by chatting. Nothing to edit by hand.
<details> <summary><b>Prefer to set it up manually? (git clone)</b></summary>git clone https://github.com/career-ops-hq/career-ops.git
cd career-ops && npm install
npx playwright install chromium # only needed for PDF generation
# On a non-Debian/Ubuntu Linux distro (Fedora, Arch, ...), Chromium's system
# libraries aren't installed by the line above — install them yourself with
# your distro's package manager if PDF generation fails to launch the browser
# (Playwright's own docs list the required libraries per platform).
# 2. Open your AI CLI in this directory. On first launch it walks you
# through setup (your CV, profile and target roles) by chatting
claude # or codex / opencode / qwen / agy / grok
# Then ask your CLI to adapt the system to you:
# "Change the archetypes to backend engineering roles"
# "Translate the modes to English"
# "Add these 5 companies to portals.yml"
# "Update my profile with this CV I'm pasting"
# 3. Start using
# Paste a job URL or JD text to trigger auto-pipeline.
# Every other mode, and how to ask for it in your CLI: see Usage below.
LinkedIn job alerts: paste the email. No Google account. See docs/LINKEDIN_JOBS.md.
</details>npm i -g @santifer/career-ops
This installs the career-ops binary globally, so you can run career-ops init [folder] without npx. init is its only command: it sets up a workspace, and everything after that happens inside your AI coding CLI (see Usage below), not through this binary.
Which one should you use?
npx @santifer/career-ops init: best for first use; creates a dedicated project folder.npm i -g @santifer/career-ops: if you'd rather type career-ops init than the npx form. It adds no other commands.The system is designed to be customized by your AI coding CLI itself. Modes, archetypes, scoring weights, negotiation scripts -- just ask it to change them. It reads the same files it uses, so it knows exactly what to edit.
See docs/SETUP.md for the full setup guide (including scanning through an outbound proxy), docs/SUPPORTED_CLIS.md for how to run career-ops in each supported CLI, and its headless command where it has one, docs/RUNNING_ON_A_BUDGET.md for instructions on running career-ops cheaply using custom or local models (and docs/FREE_TIER.md for running it at zero cost on Antigravity CLI's free tier), docs/AUTOMATION.md for scheduling recurring scans and a zero-token triage-to-shortlist recipe, docs/KEEPING_PORTALS_LIVE.md for keeping your company list current, docs/BACKUP_STRATEGIES.md for backing up your CV, tracker and reports, docs/APPLY_AUTOFILL.md for details on the ATS auto-fill flow, docs/LINKEDIN_JOIN.md for cross-referencing a LinkedIn connections export against the companies in your funnel, and docs/FAQ.md for answers to common setup questions, including how story provenance prevents invented numbers. Design principles live in ARCHITECTURE.md; runtime flows in docs/ARCHITECTURE.md.
No reports for macOS yet.
Claude reads the 12 key files and writes a step-by-step guide for macOS. Once written, it's saved for everyone.