Browser Automation

Three layers for reaching the web — static fetch, headless scripts, and the agent-driven session browser.

CareerRat reaches the web three ways. They are not interchangeable — each is right for a different layer.

Layer 1 — Static fetch (WebFetch)

Plain-HTML job postings and board listing pages. Cheapest path; always tried first when you only need the posting text. If the body comes back empty or is an SPA shell, escalate to Layer 3.

Covers: Greenhouse (boards.greenhouse.io), plain ATS URLs, RSS feed items.

Layer 2 — Headless capture (bundled Playwright)

The playwright npm dependency, driven headless and in-process from Node scripts. No setup needed — Chromium ships with the package.

Used for:

npm run capture:search-sources / npm run capture:board — bulk-scrape a board's listing DOM
Document and packet PDF export (careerrat export)

This is for batch, non-interactive rendering where the agent does not need to reason turn-by-turn.

Layer 3 — Interactive session browser

Anything the agent drives step-by-step: rendering JS pages, filling application forms, reading in-platform DMs, polling ATS status. The agent reads the live DOM before each action, never uses hardcoded selectors, and stays confirm-first.

Automatic provider selection: Orca's visible supervised browser is used inside an Orca workspace; CareerRat's app-owned Playwright browser is selected everywhere else. Playwright creates persistent local browser storage when a workflow first needs it. Public application forms open without a login; account-gated sites ask the candidate to sign in only when necessary. If the selected provider cannot execute a workflow, CareerRat shows a supervised/manual handoff instead of claiming it ran.

Automatic is the default. Settings shows the effective browser and allows an explicit override without requiring the candidate to understand their CLI setup during onboarding.

In the legacy browser workspace, saved job-site searches use one point-of-use choice, not the automation capability matrix. When a source is added or first used and login is needed, CareerRat asks “Do you want to log into LinkedIn so I can use it?” Yes opens that exact saved search in the visible session browser. No skips it and keeps searching the other sources.

Private-account capabilities

Reading public posting bodies needs nothing from you. The private-account uses below are on by default, so there is nothing to set up first. Each one still runs through your own signed-in browser, and you can turn any of them off.

Capability	Skill	What it does
`status_polling`	`sync-status`	Read application status from ATS dashboards
`messaging`	`ingest-messages`	Read LinkedIn / Wellfound DMs
`authenticated_apply_preparation`	`apply-job`	Prepare supported ATS forms (not LinkedIn) and follow the `submit` setting at final submit
`profile_optimize`	`optimize-linkedin`	Read LinkedIn profile for analysis
`profile_apply`	`optimize-linkedin`	Write approved edits back to the profile
`mail_access`	`ingest-mail`, `apply-job`	Webmail verification codes + Gmail/Outlook ingest
`relationship_sourcing`	`relationship-sourcing`	Find recruiters and warm contacts
`calendar_read`	`schedule-meeting`	Read free/busy for double-booking avoidance
`calendar_sync`	`calendar-sync`	Write events to a calendar provider

Turning a capability off or back on

A capability runs on a platform unless you switch it off. Two switches matter: the capability's own switch, and that platform's switch under it. Turn either one off and the capability skips that platform.

Settings has one switch per capability. Switches for a single platform are not in Settings: use the careerrat automation disable|enable <capability> <platform> --write commands below, or ask Paul to change one. If something you ask for is turned off, CareerRat says so in plain words and offers a Turn it on button that turns on only the platform that job needs.

careerrat automation status                               # what is on and off
careerrat automation disable mail_access --write          # turn a capability off
careerrat automation disable messaging linkedin --write   # turn off one platform
careerrat automation enable mail_access --write           # turn it back on
careerrat automation session extension --write            # set provider

If CareerRat can't read your automation settings, it treats everything as off until the file is fixed, and careerrat automation status shows the read error.

Safety rules (always enforced)

Never on a schedule. Automation runs only when you initiate it.
Halt on CAPTCHA, 2FA, or unexpected interstitial. The agent stops and tells you what it hit.
Never infer voluntary demographic answers. Race, gender identity, disability, veteran status, and similar self-identification fields stay blank by default. The local-only Profile > Application defaults editor can keep them blank or choose the form's decline option when available. Existing exact answers remain hidden and may be used only when the candidate explicitly saved them.
Submit only complete, verified applications. With submit: auto (the default) CareerRat presses the final submit control once, then waits for a confirmation page. Run careerrat automation submit manual --write and it prepares the form and you press submit. Other outward-facing actions, such as sending a message, require explicit confirmation.
Capture artifacts are scratch. Screenshots go to .careerrat/workspace/captures/ (gitignored), never the repo root.
No credential storage. The session browser holds your logins. CareerRat does not export or cache them.

SPA escalation

When a job link returns an SPA shell (Wellfound, Lever, Ashby), the agent:

For Lever: fetches the JSON API (api.lever.co/v0/postings/{company}?mode=json)
For others: escalates to Layer 3, evaluates document.body.innerText in the session browser

On this page