CareerRat Docs

CareerRat is a local, skill-driven job-search workspace. A supported local AI CLI runs inside the CareerRat workspace and drives a set of skills that cover every step of the job-search loop, from sourcing and vetting to tailoring, tracking, and interview prep.

The Mac app is the front door. The agent is the runtime. Download the app, open it, and pick an AI engine on first run. You paste a job posting (or a recruiter email, or a link) into the agent chat and say what you want to do. The skills handle the work. For developers, the careerrat CLI runs the same engine from a terminal: it scaffolds the workspace, serves the local app, checks health, and exposes safe config helpers — it is not a job board or separate cloud service.

Quick start

Download the Mac app. On an Apple Silicon Mac, get the signed, notarized build from the latest release, or install it with Homebrew:

brew install --cask codeswhat/tap/careerrat

Open CareerRat. It needs one AI engine to do the work: Claude Code or OpenAI Codex. You do not need it before you open the app. If neither is installed, CareerRat can install Claude Code from inside the app on first run, or point you at the Codex setup guide. CareerRat detects which one is ready and lets you pick it. Local availability, authentication, and the complete readiness check decide whether an engine is Ready. An older Claude Code shows as Update needed in the picker until you update it. See Install & First Run for install links.

The provider-neutral AI controls work the same with Claude Code and OpenAI Codex. Automatic chooses the right level for each task, so Paul stays strong while web search and small helpers stay efficient. Faster, Balanced, and Best change overall quality, and Thinking depth sets how much reasoning time the selected runtime uses.

Once an engine is ready, drop a résumé or start talking. Paul uses plain English during setup and gives examples when a question asks for an abstract choice, such as “What would make one job worth applying to before another?” As soon as it knows enough about the roles and locations you want, CareerRat starts the first search. Finishing setup opens Search and tells you whether that search is running, has matches, needs a retry, or is ready to start.

Search combines built-in public job-board sources with broad AI open-web discovery for the roles you set, then discovers additional specialist boards and employer pages for that search. An AI result that cannot be fully read stays in Search as an AI · unverified lead instead of disappearing. Evaluate later verifies the live posting, captures the full description, and applies the candidate's hard rules before tailoring or form preparation.

When a saved site is added or first used and login is needed, CareerRat asks “Do you want to log into LinkedIn so I can use it?” with Yes and No choices. Yes opens that exact search in the visible app browser. No skips it and keeps searching the other sources. Job-site search does not have a separate permission checklist in Settings.

You can also paste a job posting and say "evaluate this". CareerRat returns a verdict on whether to keep or cut it, how well it fits, whether the pay clears your floor, and what to do next.

For developers

CareerRat also ships as an npm package, so you can run the same engine from a terminal on any platform (requires Node.js 24.15 or newer):

npm install -g careerrat
careerrat start claude
# or
careerrat start codex

This scaffolds your workspace, boots the same local app at http://localhost:7777, and launches your agent with a starter message, just like the Mac app. See Install & First Run for the npm and source-checkout paths.

Two reading tracks

Not sure where to start?

Go to Getting Started. It walks you from downloading the Mac app through your first job evaluation in under ten minutes.

Already running, want to go deeper?

• Guides — step-by-step walkthroughs for each main workflow
• Advanced — architecture, the agent contract, data model, and configuration
• Reference — every skill in one table, CLI command index, disclaimer

Key ideas

Body-read gate. CareerRat does not tailor or apply until a job passes a real read of the posting. Title and keyword matches are triage, not truth. Before any artifact is generated, the gate weighs the posting against your own constraints and returns a keep/cut call, a fit score, a comp check, and a recommended next step — printed as a GATE / FIT / COMP / ACTION block, with further lines added when the posting warrants them (a comp anchor, a legitimacy warning).

Evidence-only tailoring. Resumes and cover letters are built exclusively from an evidence bank you supply during onboarding. The agent cannot invent facts. A placeholder-lint step blocks any artifact that contains an unresolved token.

Config-driven, field-neutral. Every preference — comp floor, excluded companies, role buckets, keep/cut signals — lives in your private local candidate state. SQLite is authoritative in new workspaces; .careerrat/candidate/ files are private compatibility exports. The skills are the same for any candidate; your config is what makes them yours.

Local by default. CareerRat stores your workspace on your machine and has no CareerRat-hosted account or data service. Relevant context sent through your selected AI runtime follows that provider's privacy and retention terms. Comp inputs marked private never appear in outbound application artifacts.

Provider-neutral continuity. CareerRat owns the workflows and threads in its local data. Switching a selected engine does not make a provider's session history the source of truth, and the app never silently falls back to another provider.

Durable background work. Searches and intake can continue while you move between views. Reloading restores their saved status. A runtime restart turns interrupted work into a visible retry instead of a false completed result.