FreeApply technical documentation

Architecture

FreeApply is an MCP server (Model Context Protocol, the standard way AI apps connect to tools). It is a local Node.js process with no dependencies that your AI app starts and talks to over stdio; there is no website you log in to. It has three parts:

• Your AI app (Claude Desktop, Claude Code, Cursor, VS Code in Copilot agent mode, or Windsurf) does the reasoning and the browsing on your own plan: it reads postings, decides what fits and fills in forms in your signed-in browser session.
• FreeApply, on your computer: the MCP server with 18 tools, the signed procedures your AI follows, a local database in ~/.freeapply, and the dashboard at http://127.0.0.1:7878, reachable only from your computer. In Claude Code it also installs three skills (setup, apply, replies) that point to those procedures.
• Our server (www.mybotsai.com): this website, the downloads, signed updates, the sponsored-card pack and the anonymous statistics you choose to share. It never receives your résumé or applications unless you join the Recruiter Talent Pool.

A run, step by step

1. Check: the AI calls freeapply_get_status, which reports whether the Terms are accepted, setup is complete and the signed workflow verifies, and with procedure: "freeapply-apply" returns the apply procedure in the same call.
2. Search: it searches the sources you chose. Company career pages on Greenhouse, Lever and Ashby are read through their public APIs, which saves tokens.
3. Score and claim: each job gets a fit score from 0 to 100. freeapply_claim_job claims it and runs the duplicate check in the same call: a repost of a job you applied to is refused, a site that is signed out or paused takes no new jobs, and posted pay below your floor is recorded as skipped.
4. Fill in: facts come only from your settings, résumé and saved answers. freeapply_fetch_posting lists the posting's keywords your facts support (matched) and those they don't (missing, never claimed). Cover letters and free-text answers go through freeapply_check_text, which also reports matched keywords a text still leaves out.
5. Pace and submit: freeapply_clear_to_submit must clear with the job's ID right before each submit; freeapply_update_job refuses the status "applied" without that clearance. In an unattended run the same call also checks the run's time and application budgets and the dashboard's Stop button.
6. Hand over: CAPTCHAs, new accounts, passwords and unanswered questions go to the dashboard's Needs you list, and the AI moves on.

Guardrails

The rules are enforced by the tools, not only written in a prompt: an AI can be talked out of an instruction, but not out of a tool that refuses the call.

• Signed workflow: the procedures, server instructions and hard limits ship signed with our release key (Ed25519). If anything changes them, the tools lock until the official copy is restored, and an update installs only when its signature verifies.
• Truthfulness check: cover letters and answers that claim tools, numbers or years of experience your résumé and settings don't support are refused; the AI has to ask you instead.
• Pace and limits: a per-minute pace check before every submit, an optional daily cap, and a site that signs you out or shows its own daily limit is paused while the others continue.
• Hands off your accounts: the agent never types, reads or stores a job-site password, never creates accounts and never solves CAPTCHAs. On a sign-in page it clicks into the username field once; if the browser's password manager fills a saved login, it may click Sign in once. With more than one account to choose from it asks you, and it never touches "Sign in with Google" (or Apple, Microsoft) buttons or Google's sign-in pop-up, which sign in with whatever account the browser holds.
• Checked calls: every tool call is checked against the tool's parameters before it runs. A missing, misspelled or wrongly typed parameter, or a value outside its choices, changes nothing and returns one error that names each problem and lists the parameters the tool takes.
• Settings the AI may touch: only known sections and fields, each of the right type and within its choices. The Terms record, sharing choices, job sites, auto-run, the model picks and résumé files stay yours: the AI can save the résumé's text and profile, never point it at another file.
• Right fields for the status: questions go only with needs_info, a sign-up link only with needs_account, and confirmations, files and letters only with applied, so nothing lands on the wrong job record.
• Public pages only: freeapply_fetch_posting reads http and https pages on public hosts. Addresses on your computer or home network, and redirects to them, are refused.

Cover letters, ATS keywords and uploads

• ATS keywords: for each posting, freeapply_fetch_posting matches the skills, tools and credentials it names against the signed vocabulary and the user's résumé profile and target keywords. Terms the user's facts support are matched; the rest are missing. It is the same test the truthfulness check applies, so a matched term can always be used and a missing one never passes. A job claimed with the same URL keeps its keywords.
• Cover-letter preferences: the cover_letter settings section (Settings → Cover letters): write (when_slot or when_required), tone, length (short 120–180, standard 150–250, long 250–380 words), highlights (the user's own words, which count as facts), avoid and sign_off. freeapply_check_text enforces the length and the sign-off.
• PDFs: freeapply_check_text with save: true writes a letter that passes as a text PDF (US Letter, Helvetica, the user's name and contact details on top), so applicant tracking systems can read it, and keeps it with the job, so freeapply_update_job records it (and the résumé copy) without the agent sending the text a second time. A failing letter is never saved, and a submitted one never changes.
• Documents folder: files to upload live in a visible folder, ~/Documents/FreeApply (inside the data folder when FreeApply runs on a custom one): a current copy of the résumé and Cover letters/. freeapply_get_status returns the paths as documents.
• Uploading: files go in by path, so their contents never pass through the AI model (a path costs a few tokens, a PDF thousands). With Claude in Chrome, the agent finds the form's file input with find and calls file_upload with the path; it never clicks the upload button, whose file-select window Chrome's tools can't use. Other browsers and AI apps click the upload button and type the file's full path into the file-select window. If a required file can't be attached, the job goes to the user as blocked.

AI models: which model does what

FreeApply never runs a model; your AI app does the thinking and writing between tool calls. Each part of the work has a level, and FreeApply picks one of your app's models for each, so routine steps run on a small model and only writing gets the strongest.

• Levels: low for searching, sorting employer emails and bookkeeping; mid for filling in application forms and short answers; high for cover letters and long answers. The work is split into four lanes: scout (low), applier (mid), writer (high) and replies (low).
• Scan: at first setup, and again whenever FreeApply, its workflow or the AI app changes (freeapply_get_status returns models.rescan), the agent lists the models its app can hand a step to and the effort levels, and saves them with freeapply_update_settings (models). FreeApply learns the app's name from the MCP handshake.
• Pick: the signed workflow carries a catalog: for each level, model families in order with the effort to use (for example high: Opus at extra-high effort, then Fable; for OpenAI apps GPT-6 Astra, then GPT-6.1 Sol at extra-high effort). The newest version of the first family the app offers wins. The catalog updates with the workflow, without a new app version.
• Your choice wins: Settings → Advanced settings → AI models shows what each level uses and lets you pick another model or effort. A level the catalog can't fill is marked there; until you choose, the app's own model does that work.
• Hand-offs: in Claude Code each lane runs as a helper (subagent) started with that model and effort. Apps that can't hand a step to another model run everything on their current model, as before. Helpers read only the settings sections they need (freeapply_get_settings sections) and pass each other job ids and file paths, not page text.

Data and network

Everything personal lives in ~/.freeapply: résumé, settings, the jobs database and recorded emails. FreeApply contacts our server only for these:

• Updates: about once a day it checks for newer signed instructions; the request carries only the app version.
• Sponsored cards: a few times a day it downloads the current card pack (unchanged packs aren't downloaded again) and picks a card on your computer. Nothing about you is sent.
• Sharing you allow, set in Settings → Data sharing, where you can preview what would be sent and delete what was shared:

Employer replies: freeapply_check_replies frames each check (start, finish). With an email login saved in Settings → Email replies (a Gmail app password, or another mail server's), its read action signs in to the mailbox over IMAP with TLS itself and returns only emails since the last check that name a company you applied to or come from a hiring system; everything else stays on your computer. mark stars and/or labels each recorded email as you chose in Settings. The app password is kept in .env in the data folder, readable only by you, and never appears in a tool result, the dashboard, a log or shared data. Without one, the AI app's Gmail connector does the reading. Setup asks for the email login, or for your choice to enter all passwords yourself.

The legal detail is in the Privacy Policy.

Why not ChatGPT yet

ChatGPT connects only to MCP servers hosted on the internet, and FreeApply runs locally so your job search stays on your computer. A hosted version for ChatGPT is planned, with its own sign-in and privacy terms.

What the installer does

Claude Desktop needs nothing else: it runs the .mcpb extension with its own built-in Node.js. Claude may note that the extension has no code-signing certificate (those are paid); the package is signed with our own release key instead (how to check).

For the other apps, the one-line installer needs Node.js 22.13 or newer. install.ps1 (Windows) and install.sh (macOS, Linux) look for it. Without one, they offer to download the current Node.js LTS from nodejs.org into %LOCALAPPDATA%\FreeApplyNode (Windows), ~/Library/Application Support/FreeApplyNode (macOS) or ~/.local/share/freeapply-node (Linux): no admin rights, no change to your PATH or system, and the file is checked against the SHA-256 list nodejs.org publishes. The apps' settings then point at that Node.js by its full path. The scripts then run install.mjs, which downloads the package, checks its signature and SHA-256, unpacks it into your user folder and asks before adding FreeApply to each app it finds. It edits only each app's MCP settings file and keeps a backup next to it:

• Claude Code: runs claude mcp add -s user freeapply … and installs the skills in ~/.claude/skills.
• Cursor: adds freeapply to ~/.cursor/mcp.json.
• VS Code: adds freeapply to your user mcp.json (use it from Copilot Chat in agent mode).
• Windsurf: adds freeapply to ~/.codeium/windsurf/mcp_config.json.
• Claude Desktop: adds freeapply to claude_desktop_config.json. Quit Claude completely and reopen it afterwards. If you also installed the extension, keep only one of the two.

Browser tool (optional)

FreeApply applies through a browser your AI app controls, such as Claude in Chrome. For apps without one, the installer asks once (default no; --browser adds it without asking, --no-browser never asks) and then installs Microsoft's Playwright MCP 0.0.83 (Apache-2.0) with npm into %LOCALAPPDATA%\FreeApplyBrowser (Windows), ~/Library/Application Support/FreeApplyBrowser (macOS) or ~/.local/share/freeapply-browser (Linux), and adds it to each app it set up as freeapply-browser in extension mode, with --allow-unrestricted-file-access so it can attach your résumé and cover letters from the FreeApply documents folder whatever folder your AI app works in (without it, Playwright MCP reads files only from that working folder). Running the installer again updates the browser tool where it is already added. Add the Playwright Extension to Chrome or Edge; the first time the AI uses the browser, the extension opens a connect page that you approve within 30 seconds. It then works in a tab of your own browser, with the sites you're signed in to.

Claude Code plugin

Instead of the installer, Claude Code can install FreeApply as a plugin from the GitHub repository:

/plugin marketplace add FreeApply/freeapply
/plugin install freeapply@freeapply

Manual setup

Any app that runs local MCP servers over stdio can use FreeApply. Download and unpack freeapply.mcpb (it is a ZIP file), then add a server that runs Node.js on src/main.js:

{
  "mcpServers": {
    "freeapply": { "command": "node", "args": ["/path/to/freeapply/src/main.js"] }
  }
}

FreeApply is listed in the official MCP Registry as io.github.FreeApply/freeapply.

Uninstall

Claude Desktop: Settings → Extensions → FreeApply → Uninstall. For the other apps, run the installer with the uninstall option:

$env:FREEAPPLY_ARGS='--uninstall'; irm https://www.mybotsai.com/appserver/install.ps1 | iex

curl -fsSL https://www.mybotsai.com/appserver/install.sh | bash -s -- --uninstall

If the installer downloaded Node.js for you, delete its folder too (listed under What the installer does) unless something else uses it.

This removes FreeApply and the optional browser tool from your apps and deletes their program folders. Your data in ~/.freeapply (including a saved email login in its .env) stays until you delete that folder.

Verify a download

The current package is (loading). Its signature file (.sig.json) holds the package's SHA-256, signed with an Ed25519 key whose private half never leaves our offline machine. The public key ships inside FreeApply (keys/release.pub) and inside install.mjs; latest.json lists the current version, file name and SHA-256.

SHA-256: see latest.json · signing key: –

To compare the checksum on Windows:

Get-FileHash .\freeapply.mcpb -Algorithm SHA256

On macOS or Linux:

shasum -a 256 freeapply.mcpb

The result must equal the SHA-256 above. The installer does this and the signature check for you, and the app verifies every update the same way: a download that doesn't match is refused.

Source code

The source is on GitHub under the MIT License (the FreeApply name and logo aren't covered). Release notes for every version are on the News page. Bug reports and questions: mybotsai@gmail.com.