Install & First Run

Install with npm

CareerRat runs in a terminal window. Prerequisites:

• Node.js >= 24.22.1. Check with node -v.
• Python 3.11 or newer, with venv. Check with python3 --version. On Windows, install it from python.org so the py launcher is available. Some Linux systems package venv separately (sudo apt install python3-venv).
• Claude Code or OpenAI Codex, one of them. You can install it after CareerRat. See below.

npm i -g careerrat
careerrat start

careerrat start opens the CareerRat workspace inside your terminal. It needs a real terminal window, not a script or a pipe.

What happens on first run

1. CareerRat creates your private data folders (safe to re-run).
2. It builds a private Python environment for the workspace. This takes about a minute and needs an internet connection. It does not touch your other Python packages, and it only happens once. You can do it ahead of time with careerrat tui setup.
3. The workspace opens. Saved jobs are on one side, and a chat with your AI assistant is on the other. CareerRat installs its skills so the assistant can run them.
4. On a brand new install, the chat begins setup on its own: it asks about your resume, target roles, location and pay.

CareerRat uses Claude Code if it finds it, otherwise Codex. If neither is installed, the workspace still opens and tells you. Install one, then run careerrat start again:

• Claude Code needs a paid Claude plan. Pro is enough; Max provides more usage. You can use Scott's disclosed referral. Install it with npm install -g @anthropic-ai/claude-code (claude.com/claude-code) and sign in.
• Codex: npm install -g @openai/codex, then follow the official guide.

To choose one yourself, run careerrat start claude or careerrat start codex. CareerRat never switches agents on its own.

Keys in the workspace: click a job to see its details, press F6 to move between the jobs and the chat, and press Ctrl+Q to quit. The Search, Review and Apply buttons put a request in the chat for you to read and send.

If something does not open, run careerrat doctor. It reports whether the terminal workspace is set up and whether the Linux build step worked.

Claude Code and OpenAI Codex are the two supported product choices. Both run the same CareerRat-owned workflows and skills against the same durable local state. CareerRat invokes the selected installed CLI directly and never falls back to or silently switches providers. Claude Code and Codex run the same complete CareerRat workflow. A runtime counts as ready only after local availability, authentication, and its readiness check pass. Long searches, drafts, choices, and selected views survive navigation and restart. Built-in job boards run alongside AI open-web discovery, and AI leads stay clearly unverified until Evaluate reads the posting.

Application questions stay with the exact job thread. CareerRat can fill reviewed fields and advance safe form steps, but CAPTCHA, sensitive attestations, and uncertainty stop it and hand the form to you. It presses Submit itself only when the application is complete and verified, unless you run careerrat automation submit manual --write.

On Windows, CareerRat looks for the py -3 launcher, then python. The terminal workspace has not been tested end to end on Windows yet, so tell us if it fails on your machine. Separately, the Windows x64 installer passes build, install, launch, export, and uninstall QA, but it is not a public release asset yet. SignPath Foundation signing requires project reputation CareerRat does not yet have. Unsigned CI packages are QA-only and never public release assets. See the repository's Windows status and code signing policy.

The Mac app has ended

The Mac app ended at v0.19.2. Later releases ship only through npm, and the .dmg and Homebrew cask stay frozen at that version. If you use the old app, it keeps working; switch with npm i -g careerrat.

Source checkout

Developing from a source checkout uses the same command shape after linking the local binary:

git clone https://github.com/CodesWhat/careerrat
cd careerrat
npm install
npm run hooks:install
npm link
careerrat start

Useful flags

Manual wiring

If you prefer to open your agent yourself:

careerrat doctor     # verify environment + scaffold state

Then open your compatible agent in the repo root and say:

familiarize yourself and let's get started

The agent reads AGENTS.md, verifies the skills shim, and runs ingest-profile conversationally if your candidate profile is not yet set up.

Custom data location

By default .careerrat/ (holding both workspace/ and candidate/) lives inside the cloned repo. Set CAREERRAT_HOME to put it somewhere else:

export CAREERRAT_HOME=~/careerrat-data
careerrat start claude

Everything under CAREERRAT_HOME is gitignored and never touches the repo tree.

Running CareerRat for more than one person

Each person gets their own workspace under your data root, in people/<name>/. Their profile, evidence, tracker and exported documents never mix with anyone else's.

careerrat people add maria
careerrat start --for maria
careerrat people list

--for <name> works on every command, for example careerrat --for maria doctor. You can also set CAREERRAT_PERSON=maria. Documents for Maria export to ~/Documents/careerrat/_people/maria/ under the default directory. An explicit CAREERRAT_DOWNLOADS_DIR is used as-is, so it is shared between people. If you override it, set a different value for each person. Without --for, you get your own workspace, exactly as before.

See Running CareerRat for someone else for authorization notes, AI routes and removing a person.

Health check

careerrat doctor

Reports environment health (Node version, agent CLI on PATH), skills discoverability, workspace scaffold state, setup completeness, and any config schema errors. Run this any time something feels off.