career-ops-hq/career-opsDokümantasyon

The open-source AI job search agent.

English | Español | Deutsch | Français | Português (Brasil) | 한국어 | 日本語 | 简体中文 | 繁體中文 | Українська | Русский | Polski | Dansk | தமிழ் | العربية | हिन्दी | Türkçe | Tiếng Việt | Bahasa Indonesia

  Created by @santifer, with    700+ contributors

Months of sending CVs into silence.
So I built the filter I needed.

740 listings evaluated. 68 applied. 12 interviews. 1 offer.
I was its first user. I got the job. Then I open-⁠sourced it.

Paste a job. On your machine, it tells you if it's still open and if it fits.
It tailors your CV and drafts your answers. You press Submit.

_{My own search, partway through, with the UI in Spanish.}

Companies use AI to filter candidates.
I just gave candidates AI to choose companies.

Six months later, I left that job.
Now we build career-ops, so you can land yours.

Try it on one job ↓ · Read the full story →

_{Prefer not to use a terminal? Join the waitlist for a web version →}

The people who came after me wrote down how they got hired.

_{Every card is a public issue you can open. Landed yours? Leave your card →}

⭐ If career-ops helped you, a star helps the next person find it.

Paste one job you were about to apply to tonight. If it comes back do not apply, you just got the night back. If it comes back with a plan, you know what to do next.

npx @santifer/career-ops init

_{Open source. Local. In the AI CLI you already use. Free and local models included.}

The silence after you hit send is not about you. Enough people saw the same thing to write the practice down, in six lines:

Apply better to fewer. Signal over volume. Evidence over keywords. A human decides. Local-first. Dignity on both sides of the table.

A few of them, in their own words.

_{Every signature is a commit you can audit. Read them all, or add yours → · What is AI job search?}

Hiring will not fix itself. The people going through it can, and they are already in the room, comparing notes and fixing each other's setups.

This is where the fix gets written. A room, not a club. Let's build together.

career-ops is free for candidates, forever. These companies sponsor the project:

SerpApi · Build a portfolio project with live search data. SerpApi gives developers structured JSON/Markdown from Google Search, Maps, Shopping, and other engines through a simple API call.

Sponsorship buys clearly labeled visibility, never influence: no amount of money changes the roadmap or places anything in the product. Sponsors never appear in evaluations, rankings or recommendations.

Paste a job. It tells you whether that night is worth it.

• Still open? It checks that the posting is still live before you write a word.
• Not you? It scores the role against your real CV and tells you to skip a weak fit. You can override it.
• Worth it? It drafts the CV, the cover letter and the answers. You read them. You send them.
• Who do I talk to? It finds the person and drafts the note. It never sends it.
• Where does it all go? Every application stays on your machine. Nothing is uploaded to us.
• What should I learn? After a run of noes, it names the gap.

The first runs are rough. It does not know you yet. Talk to it: your CV, what you want, what you refuse. Think of it as a recruiter's first week.

On first launch it asks for all that in chat. Nothing to configure by hand.

• Auto-submit an application. It drafts the answer to every field; you review and click Submit. The script never POSTs (prepare-application.mjs).
• Send an email. Drafts only. There is no mail transport anywhere in this codebase.
• Phone home. No telemetry, no backend of ours. Your CV goes from your machine to the AI provider you chose, and nowhere else. The only public ledger is this repo: HIRED.md and its issues.
• Push you to apply below 4.0/5. It will tell you not to. You can override it, and it will say so.

It reformulates your CV; it must never fabricate it. A check in code stops a PDF whose numbers or facts appear in neither your CV nor your article digest, but it cannot judge every rewording yet. Read every CV before you send it. Details in the FAQ.

Fastest way, one command:

npx @santifer/career-ops init

💡 npx ships 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.

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.

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.

• From any folder, as a Claude Code plugin: docs/CLAUDE_PLUGIN.md.
• Without an AI CLI: standalone Gemini, Ollama and OpenAI-compatible scripts evaluate a JD on their own. See docs/SCRIPTS.md.

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.

Paste a job URL or description into your AI CLI. career-ops checks that a linked posting is still live (pasted text has no link to check), scores it against your CV, writes a report, tailors your CV (a PDF by default) and adds a row to your tracker. That covers most days. Everything else is a mode you ask for by name. If a posting can't be read, the pipeline stops and asks you to paste the text or share a screenshot.

/career-ops with nothing after it shows the command menu in the CLIs that use it. Plain language works in every supported CLI. As a Claude Code plugin, the command is /career-ops:career-ops.

All of them share one router, .agents/skills/career-ops/SKILL.md, and the same modes/*.md files, so every CLI routes a request the same way (browser-heavy modes also need Playwright tools). Slash commands are not guaranteed in Codex: ask in plain language, or run one prompt headless with codex exec "Evaluate this JD with career-ops auto-pipeline: https://company.com/jobs/123" (docs/CODEX.md). How to run it in each supported CLI, headless commands where a CLI has one, and per-CLI setup notes are in docs/SUPPORTED_CLIS.md.

The scanner comes with 100+ companies ready to scan and 35+ search queries across major job boards. Copy templates/portals.example.yml to portals.yml and add your own:

AI Labs: Anthropic, OpenAI, Mistral, Cohere, LangChain, Pinecone Voice AI: ElevenLabs, PolyAI, Parloa, Hume AI, Deepgram, Vapi, Bland AI AI Platforms: Retool, Airtable, Vercel, Temporal, Glean, Arize AI Contact Center: Ada, LivePerson, Sierra, Decagon, Talkdesk, Genesys Enterprise: Salesforce, Twilio, Gong, Dialpad LLMOps: Langfuse, Weights & Biases, Lindy, Cognigy, Speechmatics Automation: n8n, Zapier, Make.com European: Factorial, Attio, Tinybird, Clarity AI, Travelperk

Job boards searched: 55+ provider modules cover ATS APIs, board-wide feeds, XML/RSS feeds, markdown feeds, and local parsers. See Supported job boards for the full table.

Keep the list current: portals.yml is designed to stay live, not be a one-time setup file. See Keeping portals.yml live for the house rule that adds new companies automatically and the commands to validate the file after every change.

By default node scan.mjs (a.k.a. npm run scan) trusts what each ATS feed returns. Some companies leave stale postings in their public API even after the role is closed, so those expired entries can leak into pipeline.md. Pass --verify to launch Playwright after the API pass and drop expired postings before they hit the pipeline:

node scan.mjs --verify          # zero-token discovery + Playwright liveness check

The verification is sequential and only runs against new offers (after dedup), so the cost stays bounded.

The built-in terminal dashboard lets you browse your pipeline visually:

npm run serve:dashboard   # launch the TUI
npm run build:dashboard   # optional: build the standalone binary

Features: 10 filter tabs, 8 sort modes, grouped/flat view, lazy-loaded previews, inline status changes.

There is also an experimental web UI (alpha and opt-in: nothing runs unless you start it): see web/README.md.

career-ops/
├── AGENTS.md                    # Canonical agent instructions (all CLIs)
├── CLAUDE.md                    # Claude Code wrapper (imports AGENTS.md)
├── CODEX.md                     # Codex wrapper (imports AGENTS.md)
├── OPENCODE.md                  # OpenCode wrapper (imports AGENTS.md)
├── GEMINI.md                    # Legacy no-op guard to avoid Antigravity duplicate context
├── cv.md                        # Your CV (create this)
├── article-digest.md            # Your proof points (optional)
├── config/
│   └── profile.example.yml      # Template for your profile
├── modes/                       # Skill modes
│   ├── _shared.md               # Shared context (system file; local edit kept unless apply --force)
│   ├── _profile.md              # Your archetypes and framing (customize this)
│   ├── oferta.md                # Single evaluation
│   ├── pdf.md                   # PDF generation
│   ├── cover.md                 # Cover letter generation
│   ├── email.md                 # Formal application email drafts
│   ├── scan.md                  # Portal scanner
│   ├── batch.md                 # Batch processing
│   └── ...
├── templates/
│   ├── cv-template.html         # ATS-optimized CV template
│   ├── portals.example.yml      # Scanner config template
│   └── states.yml               # Canonical statuses
├── batch/
│   ├── batch-prompt.md          # Self-contained worker prompt
│   └── batch-runner.sh          # Orchestrator script
├── dashboard/                   # Go TUI pipeline viewer
├── data/                        # Your tracking data (gitignored)
├── reports/                     # Evaluation reports (gitignored)
├── output/                      # Generated PDFs (gitignored)
├── fonts/                       # Space Grotesk + DM Sans
├── docs/                        # Setup, customization, budget guide, architecture
└── examples/                    # Sample CV, report, proof points

By default, user-layer data (such as cv.md, portals.yml, and data/ / reports/ / output/ folders) lives inside the project root folder.

To separate your personal data from the code (making it easier to switch branches, pull updates, or test multiple profiles), you can configure an external data directory using the following precedence:

1. Environment Variables: Set the CAREER_OPS_ROOT or CAREER_OPS_DATA_DIR environment variable:

   export CAREER_OPS_ROOT=~/my-career-data

2. Marker File: Create a .career-ops-data file in the repository root containing the path to your data directory.
3. Default: Defaults to the repository root.

Once resolved, all user files are resolved and written relative to that folder, while prompt files and scripts continue to resolve relative to the repository.

• Tracker Override: You can also set CAREER_OPS_TRACKER to override the applications tracker file path directly.
• Writes: All write operations (such as merges) canonically target {DATA_ROOT}/data/applications.md.
• Scanner config: portals.yml is read and validated at {DATA_ROOT}/portals.yml, so node validate-portals.mjs checks the same file scan.mjs reads.
• Generated documents: tailored CVs and cover letters are written under {DATA_ROOT}/output/, and the PDF manifest that links them to a report lives at {DATA_ROOT}/data/pdf-index.tsv. While CAREER_OPS_TRACKER is unset, the tracker workspace that bounds those writes is the data root, not the checkout.
• PDFs under a tracker override: generate-pdf.mjs resolves CAREER_OPS_TRACKER before it derives the workspace, so with the override set the workspace is the folder that holds that tracker (or the folder above it, when the tracker sits in a data/ folder). The CV's HTML and every PDF must then sit inside that workspace, and the manifest moves to its data/pdf-index.tsv. Cover letters still target {DATA_ROOT}/output/, so they are refused when that folder falls outside the tracker's workspace.
• Code layer stays put: node_modules/, providers/, modes/ and the scripts themselves always resolve against the repository, never the data root.

The Go dashboard TUI, Node.js scripts, and AI agent modes all automatically respect this resolution hierarchy.

• Agent: AI coding CLI with shared skills and modes (AGENTS.md + CLI wrapper)
• PDF: Playwright + HTML template
• Cover letters: HTML template + Playwright (A4 PDF, same pipeline as CVs)
• Scanner: Playwright + Greenhouse API + WebSearch
• Dashboard: Go + Bubble Tea + Lipgloss (Catppuccin Mocha theme)
• Data: Markdown tables + YAML config + TSV batch files

_{Also runs on any agent-skill-standard CLI. See Supported CLIs.}

• cv-santiago -- The portfolio website (santifer.io) with AI chatbot, LLMOps dashboard, and case studies. If you need a portfolio to showcase alongside your job search, fork it and make it yours.

What is career-ops? career-ops (career-ops.org, also known as careerops) is an open-source AI job search that runs locally in your AI coding CLI (Claude Code, Codex, OpenCode and others) and leaves every decision to you. It evaluates job offers against your CV, generates ATS-tailored PDFs, finds the right person to contact, and tracks everything in one place: you always have the final call. It is the first reference implementation of the CareerOps Manifesto.

Can the tailored CV invent things? It must not, and the prompts say so: reformulate, never fabricate. generate-pdf blocks a CV whose numbers or facts are missing from your sources, unless you pass --skip-fact-check. The pdf mode also runs cv-title-check.mjs, which compares each job title in the tailored CV with the title cv.md gives the same job (matched by company and dates) and asks you to keep or revert any that differ. It warns rather than blocks, because reframing a title is sometimes your call. Nothing judges rewording yet: #1411 (fail-closed faithfulness check) tracks that. Until then, read every CV before you send it. The Legal Disclaimer says the same in longer words.

Can I run career-ops for free, or on a cheaper / local model? Yes. career-ops is CLI-agnostic and runs on free and local models (OpenRouter free models, Ollama or any OpenAI-compatible endpoint), so you are not tied to a paid subscription. See docs/RUNNING_ON_A_BUDGET.md for the full setup.

I pay for Claude Pro/Max but career-ops is burning API credits. Why? Because an ANTHROPIC_API_KEY in your environment takes precedence over your logged-in subscription: the CLI uses the key and bills per token. Run echo $ANTHROPIC_API_KEY, and if it prints anything, remove it from your shell profile, restart the terminal and run /login. Batch mode is the exception, since claude -p workers do not use the interactive login: run claude setup-token once and export the result as CLAUDE_CODE_OAUTH_TOKEN. Full walkthrough in docs/RUNNING_ON_A_BUDGET.md.

Which AI CLIs does career-ops work with? career-ops runs on any major AI coding CLI (Claude Code, Codex, Gemini / Antigravity, OpenCode, Grok, Qwen and more) through the open Agent Skill Standard, so it is never locked to a single vendor. Use the CLI you already have.

How do I install career-ops on Windows? career-ops runs on Windows. Platform-specific setup and the known sharp edges (Git Bash discovery, line endings, Task Scheduler) are in docs/WINDOWS.md. If skills fail to load with a symlink error during install, the fix is in docs/FAQ.md. Full steps are in docs/SETUP.md. On NixOS, use the flake dev shell instead of npx playwright install; see docs/NIXOS.md.

Does career-ops auto-apply to jobs for me? No. career-ops is a filter, not a spray-and-pray auto-applier. The AI evaluates, ranks and drafts; you review and decide. It drafts and fills; it never submits. You press Submit. That human-in-the-loop design is the whole point.

Is career-ops free and open source? Yes. career-ops is free and open source, and for the candidate it always will be. It is the first reference implementation of the CareerOps Manifesto. Read it, and if it says what you believe, sign it.

I'm Santiago Fernández de Valderrama Aparicio (santifer), a former founder: I built and sold a business that still runs with my name on it. I built career-ops to manage my own job search, and it worked: it landed me a Head of Applied AI role. Six months later I left that role to focus on building career-ops full time.

Curious how a repo this size is maintained with a fleet of AI agents and a human deciding every merge? Read Agentic maintenance: how career-ops is run by a fleet of AI agents.

My portfolio and other open source projects → santifer.io

Wikidata: Santiago Fernández de Valderrama Aparicio · career-ops.

career-ops is a local, open-source tool, NOT a hosted service. By using this software, you acknowledge:

1. You control your data. Your CV, contact info, and personal data stay on your machine and are sent directly to the AI provider you choose (Anthropic, OpenAI, etc.). We do not collect, store, or have access to any of your data.
2. You control the AI. The default prompts instruct the AI not to auto-submit applications, but AI models can behave unpredictably. If you modify the prompts or use different models, you do so at your own risk. Always review AI-generated content for accuracy before submitting.
3. You comply with third-party ToS. You must use this tool in accordance with the Terms of Service of the career portals you interact with (Greenhouse, Lever, Workday, LinkedIn, etc.). Do not use this tool to spam employers or overwhelm ATS systems.
4. No guarantees. Evaluations are recommendations, not truth. AI models may hallucinate skills or experience. The authors are not liable for employment outcomes, rejected applications, account restrictions, or any other consequences.

See LEGAL_DISCLAIMER.md for full details. This software is provided under the MIT License "as is", without warranty of any kind.

Every person who has shipped code, docs, translations or tests is listed in CONTRIBUTORS.md, including non-code contributions, which the graph above cannot show.

Got hired using career-ops? Share your story!

The code is licensed under MIT. The "career-ops" name and brand are governed by the Trademark Policy, permissive for community use, reserved for commercial product naming and endorsement.

_{Created and maintained by Santiago Fernández de Valderrama Aparicio (@santifer)}