# Compass by Pragmys

> Compass by Pragmys ranks jobs against your verified skills. Compass Agent is a local MCP server that ranks the jobs your own AI agent finds and writes a report you keep. Compass Browser is the extension that scores the posting you are reading.

Compass runs on your machine with your own AI agent. Your agent finds job postings; Compass cleans them, scores them against the skills you have verified on Pragmys, and writes a report with company names, match %, what you have and what is missing. For the roles you pick, it can run a deeper check.

Page: https://pragmys.com/compass  
Package: [@pragmys/compass](https://www.npmjs.com/package/@pragmys/compass) (current version 0.0.8)  
Contact: hello@pragmys.com

## What it does

1. **Plan.** `compass_plan` takes the role you want. It returns the sources to read and a private folder for the downloads.
2. **Find.** Your agent checks in with Compass before each request, fetches public job feeds and company boards with its own tools, and saves them.
3. **Score.** `compass_score` cleans the postings (company names, links, duplicates, instructions aimed at applicants or AI agents removed) and scores them against your verified skills with the same matcher as Compass Browser. It writes the report.
4. **Deep check.** For the number of jobs you ask for, your agent reads each posting and Compass computes the deeper numbers on your device.
5. **Finish.** `compass_finish` finalises the report, shows what was sent to Pragmys and removes the download folder.

The report is an HTML file on your device: match %, required and preferred skills met, the line of the posting behind each match, a per-company table and a link to Qualify on Pragmys for the gaps that matter.

## What it does not do

- It does not fetch job sites itself, log in anywhere, solve CAPTCHAs or apply to jobs. Your agent fetches public feeds; Compass governs the pace and the sources.
- Compass does not send Pragmys servers any posting text, and Pragmys does not fetch job sites on Compass’s behalf. Radar, a separate feature on pragmys.com, reads public employer career boards.
- It does not claim that using any source complies with that source’s terms. You are responsible for how you use it.
- It does not support LinkedIn, Naukri, Indeed, Glassdoor or Wellfound. Use Compass Browser on the page in front of you for those.

## What you need

- A Pragmys account with skills verified on your profile. That is what jobs are ranked against.
- An agent app that supports local MCP servers and has web search and a shell (for example Claude Code, Cursor, Antigravity, VS Code with Copilot or Codex). A coding agent works best: chat apps such as Claude Desktop can produce file-access errors. Without web search and a shell the agent cannot fetch the feeds.
- Node.js 18 or later, so that `npx` can start Compass. Builds exist for macOS (Apple Silicon and Intel), Linux (x64 and arm64) and Windows (x64).

## Install

Compass is one local MCP server (stdio). Add it to your agent app with the command `npx -y @pragmys/compass@0.0.8`. Pin the version.

Compass works best in a coding agent. Chat apps such as Claude Desktop can produce file-access errors, because Compass saves feeds and the report to your computer.

### Claude Code

Run in your terminal.

```bash
claude mcp add pragmys-compass -- npx -y @pragmys/compass@0.0.8
```

Chat apps such as Claude Desktop can produce file-access errors. A coding agent like this one is the reliable route.

### Cursor

Add to your MCP settings (.cursor/mcp.json).

```json
{
  "mcpServers": {
    "pragmys-compass": {
      "command": "npx",
      "args": [
        "-y",
        "@pragmys/compass@0.0.8"
      ]
    }
  }
}
```

### Antigravity

In Antigravity open Manage MCP Servers, choose View raw config, add this to mcp_config.json, then restart.

```json
{
  "mcpServers": {
    "pragmys-compass": {
      "command": "npx",
      "args": [
        "-y",
        "@pragmys/compass@0.0.8"
      ]
    }
  }
}
```

### VS Code (Copilot)

Add to .vscode/mcp.json.

```json
{
  "servers": {
    "pragmys-compass": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@pragmys/compass@0.0.8"
      ]
    }
  }
}
```

### Codex

Add to ~/.codex/config.toml.

```toml
[mcp_servers.pragmys-compass]
command = "npx"
args = ["-y", "@pragmys/compass@0.0.8"]
```

### Other

Any app that supports local (stdio) MCP servers: add a server that runs npx -y @pragmys/compass@0.0.8. Most accept this JSON. Check your app’s current documentation, because MCP configuration formats change.

```json
{
  "mcpServers": {
    "pragmys-compass": {
      "command": "npx",
      "args": [
        "-y",
        "@pragmys/compass@0.0.8"
      ]
    }
  }
}
```

## First run

1. Add the server to your agent app (above) and restart the app so the `compass_*` tools appear.
2. Ask your agent for jobs, for example: “Find backend engineer jobs using Compass and analyse the top 5 in depth.” Give a location only if you want one judged.
3. The first time, the agent calls `compass_login`. Open the link it shows, sign in to Pragmys if asked, and approve the code at pragmys.com/cli-login. Approve only a code you generated yourself, just now.
4. The agent runs the search. When it finishes it gives you the path of the HTML report.

## Example prompts

Ask your agent in plain words, and say Compass so it uses the tools.

```text
Find backend engineer jobs using Compass and analyse the top 5 in depth.
```

```text
Use Compass to find remote data engineer roles and rank them against my Pragmys skills.
```

```text
Add the Greenhouse boards for Acme and Globex to my Compass list, then search for platform engineer roles.
```

```text
Show me what Compass would send to Pragmys for this run.
```

## Tools

Seventeen tools, in the order a run uses them. Your agent calls them; you rarely need to.

| Phase | Tool | What it does |
|---|---|---|
| Start | `compass_plan` | Start here. Takes the role (and a location only if you give one) and returns the sources to read, a private download folder and the steps. |
| Start | `compass_status` | Sign-in state, version, notices from Pragmys and the next step. |
| Start | `compass_login` | Device-code sign-in with your Pragmys account. The token goes to your OS keychain. |
| Start | `compass_sites` | The sources Compass supports, what each needs, its terms link and the credit it requires. |
| Search | `compass_checkin` | Your agent asks before every request. Compass answers allowed or refused, and how long to wait. |
| Search | `compass_report_failure` | Report a failed request that was not a block, so the attempt is given back. |
| Search | `compass_report_block` | Report a block, CAPTCHA or login wall. Compass switches that source off for 24 hours. |
| Search | `compass_companies` | A small local list of company boards you or your agent chose to keep. |
| Score | `compass_ingest` | Add saved feeds or postings to the run and clean them, without scoring yet. |
| Score | `compass_score` | Clean, score and write the HTML report from the files your agent saved. |
| Deep check | `compass_deep_brief` | The top roles you asked to analyse in depth, plus the public skill list. |
| Deep check | `compass_deep_submit` | Your agent names the skills a posting asks for, with quotes. Compass checks them and computes the numbers on your device. |
| Deep check | `compass_evidence` | Your evidence for given skills, with the lines that support them. |
| Report | `compass_report` | Write or refresh the report for the current results. |
| Report | `compass_finish` | Finalise the report, show what was sent to Pragmys and remove the download folder. |
| Report | `compass_usage_preview` | Show the exact usage record that would be sent. |
| Report | `compass_update` | Check for a newer or security release. Compass never updates itself. |

## Sources and limits

Compass reads feeds and public job-board APIs only: RemoteOK, Jobicy and Arbeitnow, and the company boards on Greenhouse, Lever, Ashby and Workable. Some sources are on a blocklist and refused by every tool. `compass_sites` lists what is supported, what each needs, its terms link and the credit it requires.

| Rule | Value |
|---|---|
| Between requests to one source | 5 to 10 seconds, or the delay the source states |
| Pages per source / per run | 15 / 40 |
| Searches per source per day | 5 |
| Deep checks per run | up to 10 |

At status and plan time Compass reads a small settings record from api.pragmys.com (cached for an hour; if the call fails the built-in rules apply). Pragmys can use it to switch Compass off, pause a source, block a host, lower the limits, switch the deep check off, require a minimum version and show a notice. It never raises a limit above the built-in value and carries nothing about you.

## Configuration

| Setting | What it does |
|---|---|
| `COMPASS_USAGE=0` | Sends no usage record to Pragmys. Run `compass_usage_preview` to see what would be sent. |
| `COMPASS_REPORT_DIR` | The folder the HTML report is written to. Without it, the report goes in `Downloads/Pragmys-Compass` in your home folder, or `~/.pragmys-compass/reports` if that is not writable. |
| `~/.pragmys-compass/` | A small state file and a company index. |
| OS keychain | Your Pragmys token, or a file only you can read. |

Set the variables in the `env` of Compass’s entry in your agent app’s MCP settings, or in your shell before you start the app.

## Compass Agent or Compass Browser

|  | Compass Agent | Compass Browser |
|---|---|---|
| What it does | Ranks the jobs your own AI agent finds for a role you name. | Scores the job posting in front of you as you browse. |
| Where it runs | On your device, through your agent app. | In your browser. |
| Where jobs come from | Public feeds and company boards: RemoteOK, Jobicy, Arbeitnow, Greenhouse, Lever, Ashby and Workable. | LinkedIn, Naukri, Indeed, Glassdoor, Wellfound and Unstop pages you open. |
| What you get | An HTML report with match %, skills met and what is missing. | A match score on the page. |
| Use it when | You want a ranked shortlist for a role. | You are reading one specific posting. |

Both are Compass by Pragmys: same account, same verified skills, same scoring. Agent to find, Browser to check.

## Privacy

- Your Pragmys token is stored in your OS keychain (or a file only you can read) and is sent only to the Pragmys API.
- Each run sends Pragmys one usage record: the role you searched, whether you gave a location and how many terms, how many deep checks you asked for, request, fetch, keep and drop counts per source, timings, and refusal and failure counts. It never contains posting text, links, company names, location terms, results, skills or scores.
- `compass_usage_preview` shows the exact record. Set `COMPASS_USAGE=0` to send nothing.
- Postings stay on your device and with your own agent and its model provider, under their terms.
- Files Compass writes: the HTML report (in `Downloads/Pragmys-Compass`, or `COMPASS_REPORT_DIR`), a small state file and a company index in `~/.pragmys-compass/`, and a temporary run folder that is removed when the run finishes.

| Data | Where it goes |
|---|---|
| Job postings and feeds | Stay on your device and with your own agent and its model provider. |
| Your Pragmys token | Your OS keychain, or a file only you can read. Sent only to the Pragmys API. |
| Your verified skills | Come from your Pragmys account: skill names and confidence scores, nothing else, within read limits. |
| One usage record per run | Sent to Pragmys, unless you set `COMPASS_USAGE=0`. Preview it with `compass_usage_preview`. |
| Your report | An HTML file on your device. |

You can ask for your Compass history to be shown or deleted at hello@pragmys.com.

## Security

- Turn on tool approval in your agent app so you see each Compass call before it runs, and take care when you use Compass next to other MCP servers.
- Approve only a sign-in code you generated yourself, just now.
- Compass cleans postings and removes instructions aimed at applicants or AI agents.
- Compass never updates itself. Pin the version, and update when `compass_status` tells you a newer or security release exists.
- To report a security problem, email hello@pragmys.com. Please do not post it publicly. We aim to acknowledge within 2 business days.

## Troubleshooting

| If | Try |
|---|---|
| The `compass_*` tools do not appear | Quit and reopen your agent app, not just the window. Check the entry is in the right config file, and run `node -v` to confirm Node.js 18 or later. |
| The sign-in link does not work | Ask your agent to call `compass_login` again for a fresh code, then approve the code you just generated at pragmys.com/cli-login. |
| Your agent says it cannot find jobs | Compass needs an agent with web search and a shell. Ask it to run `compass_status` for your sign-in state and the next step. |
| A source returns nothing | If a source blocks a request, Compass switches it off for 24 hours. Other sources keep working. Try again tomorrow. |
| You want jobs from LinkedIn, Naukri, Indeed, Glassdoor or Wellfound | Compass does not support them. Use Compass Browser on the page in front of you. |
| You want to know what was sent | Run `compass_usage_preview`. Set `COMPASS_USAGE=0` to send nothing. |
| You cannot find the report | `compass_finish` gives the path. It is in `Downloads/Pragmys-Compass` in your home folder, or in `COMPASS_REPORT_DIR` if you set it. |
| You see file-access or read-only errors | Chat apps such as Claude Desktop run the agent in a sandbox that cannot reach the files Compass saves. Use a coding agent (Claude Code, Cursor, Antigravity, Codex) instead. |

## Updates, uninstall and cleanup

Pin the version in your config. `compass_status` tells you when a newer or a security release exists; Compass never updates itself. To update, change the version in your config and restart the app.

To remove Compass, delete the entry from your agent app’s MCP settings. To delete what it stored on your device:

```bash
rm -rf ~/.pragmys-compass
rm -f compass-reports/compass-report-*.html
```

To disconnect an agent from your account, sign in and revoke it under Connected agents on your profile (pragmys.com/profile#connected-agents).

## Terms and takedown

- Compass is free to use with a Pragmys account. It is closed source and licensed under the Compass licence that ships in the package. Use is for your own job search on your own device.
- Do not use Compass to get around a block, a login, a CAPTCHA, a rate limit or any access control, and do not build a database of postings or redistribute their content.
- If you operate a site Compass supports and want it removed, email hello@pragmys.com with the domain and a way to verify you control it. We acknowledge within 2 business days and remove a verified site within 7 days.