Getting started

Setup & connection

Connect SQUAT to the AI client you already use, then create or join your workspace. Hosted protection is automatic.

Your license key

A license key is required for the hosted workspace and every call to the SQUAT server. The free Starter key takes a minute at www.squat.pro (no card required) and connects you to the live methodology, your squad, and your ledger. The client layer can also run in a local no-key mode and write JSON under your project's .squat/ directory; that mode has no hosted sync, seats, live knowledge, or hosted ledger.

Your key works on up to three devices; manage them from the Devices page of your account (www.squat.pro/account/devices), and a device pack adds three more. A repository set up for CI counts as one shared device (see Device identity below).

Connect from the Claude app (recommended)

If you use SQUAT inside Claude — Cowork, claude.ai, or the Claude desktop app — start here. You add SQUAT as a connector and sign in once in your browser. Nothing to create on your machine, no key to store anywhere, no files to keep in sync.

1. Add the connector. In your Claude app's connector settings, choose to add a custom connector and paste your SQUAT server address (https://api.squat.pro/mcp).

2. A SQUAT sign-in page opens in your browser. It tells you which app is asking and what it's asking for. This page is SQUAT's own — you're never typing your key into the AI app.

3. Paste your license key once and submit. You're sent straight back to Claude, connected.

4. Verify: ask Claude to check the SQUAT workspace connection. A successful workspace identity/member response means you're in.

The connector brings the skills too. SQUAT publishes its guided flows — recruit, run a round, review, steward, maintain, plus the concierge and the journey and menu wayfinders — as standard MCP prompts, so any client that supports them can offer them by name. You do not need the plugin to use SQUAT properly; asking plainly (“interview me to build a tester persona”) works everywhere.

What the plugin adds is ergonomics: slash commands in Claude, and a few conveniences on top. Worth having, not required.

How SQUAT finds your key

Everywhere you're not using a connector — Claude Code in the terminal, LM Studio, Codex — SQUAT looks for the same two settings: a server address and a license key, resolved in this order, checked field by field:

1. Environment variables — SQUAT_SERVER_URL and SQUAT_LICENSE_KEY. Best for terminal clients.
2. Config file — ~/.squat/config.json. Best for desktop apps, which don't see your shell environment.

Environment variables win where both exist; the file fills in whatever the environment doesn't set. To create the config file:

mkdir -p ~/.squat && cat > ~/.squat/config.json <<'EOF'
{ "serverUrl": "https://api.squat.pro/mcp", "licenseKey": "sqk_..." }
EOF
chmod 600 ~/.squat/config.json

Claude Code (terminal)

1. Install the plugin:

   /plugin marketplace add ElucidateDigital/SQUAT-Plugin
   /plugin install squat@squat

2. Set your key in your shell profile, then restart Claude Code:

   export SQUAT_SERVER_URL="https://api.squat.pro/mcp"
   export SQUAT_LICENSE_KEY="sqk_..."

3. Verify: ask Claude to check the SQUAT workspace connection. A successful workspace identity/member response means you're in.

Claude desktop app and Cowork

Connect with the connector above — that's the first choice here, and in sandboxed sessions (Cowork especially) it's the only one that reliably works. That alone gives you the tools and the skills.

Adding the plugin

The plugin lives at github.com/ElucidateDigital/SQUAT-Plugin. It adds slash commands and a few conveniences on top of the connector; it is not required to use SQUAT.

1. Claude desktop app or Cowork: Customize menu → Plugins → Personal plugins → “+” → Add marketplace → enter ElucidateDigital/SQUAT-Plugin → Sync, then install squat.

2. Codex: add the same repository as a marketplace, then select the SQUAT connector before you send your first message. Codex binds a task's tool list when the task begins, so naming the connector mid-task does not rebind it — if SQUAT's tools are missing from a task already running, quit and reopen Codex and start a fresh one.

3. Verify: ask your client to check the SQUAT workspace connection. A workspace identity response means you're in.

If you'd rather not use a connector, the config-file path still works in the desktop app: put your key in ~/.squat/config.json (see above) — the app launches without a shell environment, so the file is the only place it can look — and restart. In Cowork, that file is out of reach; use the connector.

ChatGPT and other MCP Apps hosts

Use the host's standard MCP connector or MCP Apps setup and add the same SQUAT endpoint shown above. Sign in on SQUAT's browser page when the host offers OAuth; do not paste a license key into the chat. SQUAT does not require a custom ChatGPT extension or a host-specific data contract.

Hosts that render standard MCP Apps resources can show interactive cards. Other clients receive the same facts and actions as complete Markdown. If the host does not load SQUAT's guided skills, ask plainly for the workflow you want — for example, “interview me to build a tester persona” or “run a panel with this project's default squad.”

For ongoing work, the same rule applies: ask for “run a SQUAT maintenance sweep”, “review this project's ledger and saved reports”, or “help me prepare a deletion request”. A client with MCP prompt support may offer maintain, review, and concierge directly — plus journey and menu for “where am I?” wayfinding and mid-session steering.

LM Studio (local models)

LM Studio can run your entire squad on a model that lives on your machine — your compute, your data, nothing metered. This is the fullest version of SQUAT's bring-your-own-compute promise.

Two ways in — both work today:

Option A — connect by URL (nothing to install)

Try this one first. Add SQUAT to LM Studio's MCP configuration (mcp.json — see LM Studio's docs for its exact location on your version):

{
  "mcpServers": {
    "squat": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://api.squat.pro/mcp"]
    }
  }
}

The first connection opens SQUAT's sign-in page in your browser. Paste your license key there once and you're in — no SQUAT files on your machine, and no key sitting in mcp.json or any other file on disk. The pass renews itself quietly from then on.

Option B — the local launcher

Use the launcher when you'd rather keep your key in ~/.squat/config.json, or when you need its local-file abilities: importing personas from a folder, resuming an interrupted panel from a saved file, or sending a round's work to a second local model.

1. Add the launcher to LM Studio's MCP configuration. Straight from GitHub, with nothing to clone:

   {
     "mcpServers": {
       "squat": {
         "command": "npx",
         "args": ["-y", "github:ElucidateDigital/SQUAT-Plugin", "squat-mcp"],
         "env": { "SQUAT_SERVER_URL": "https://api.squat.pro/mcp" }
       }
     }
   }

   Or from a copy on your disk — you'll need Node.js installed and the SQUAT plugin files locally (clone the ElucidateDigital/SQUAT-Plugin repository):

   {
     "mcpServers": {
       "squat": {
         "command": "node",
         "args": ["<path-to-plugin>/lib/mcp-launcher.mjs"],
         "env": { "SQUAT_SERVER_URL": "https://api.squat.pro/mcp" }
       }
     }
   }

2. Set your key in ~/.squat/config.json (see above) — it doesn't need to appear in mcp.json.

Two LM Studio–specific notes:

• No slash skills, tools and prompts. LM Studio drives SQUAT through tools directly. Ask “Use the SQUAT tools to run a maintenance sweep for this project and show proposed changes first”, “list the trash and prepare, but do not execute, a purge”, or “show the audit history for this action.” If the host exposes MCP prompts, choose maintain, review, concierge, or journey; otherwise call squat_help or keep using plain language. If your model refuses to use tools at all, a short fallback system prompt fixes it — see Troubleshooting.
• Pick your model realistically. Squad members are only as convincing as the model that plays them; small models produce flat personas and generous grading. Every round records which model ran it, so your ledger stays accurate either way — and if a round's failures look off, check whether they're classed as agent failures (the model erred) before blaming your app.

Codex CLI

Two ways in — both work today:

Option A — repo marketplace

Add SQUAT's repository as a plugin marketplace in ~/.agents/plugins/marketplace.json (create the file if it doesn't exist):

{
  "name": "squat",
  "plugins": [
    {
      "name": "squat",
      "source": { "source": "github", "repo": "ElucidateDigital/SQUAT-Plugin" },
      "policy": { "installation": "AVAILABLE" },
      "category": "Testing"
    }
  ]
}

Then open the plugin browser in Codex CLI and install squat.

Option B — direct MCP server

Add the launcher to ~/.codex/config.toml:

[mcp_servers.squat]
command = "node"
args = ["<path-to-plugin>/lib/mcp-launcher.mjs"]

Then set your server address and key via environment variables (SQUAT_SERVER_URL, SQUAT_LICENSE_KEY) or ~/.squat/config.json.

Which model runs what

Model choice is part of your setup, never part of a scenario — scenarios stay model-agnostic so rounds remain comparable over time, and so a shift in results can be traced to your app or to a model change, not both at once. Where your client can route between models, SQUAT decides in this order: your project's model policy (set once — for example “cheap actor, strong evaluator”), then an ad-hoc instruction in chat (for one round), then whatever model your chat is already running. Every round records which model actually ran each part, so the ledger stays accurate even when routing isn't available. The setup guide for your specific client (Claude, Codex, Antigravity, LM Studio) goes deeper, including which models are worth choosing.

Hosted content protection

Connected work requires no encryption setup. Claude, ChatGPT/Codex, LM Studio, and other MCP clients send ordinary semantic content through the authenticated connection. SQUAT protects customer content before storage and returns it only to authorized roles. Workspace content keys remain inside the managed service boundary.

Device identity and CI

Each installation identifies itself to the server with a device ID. Your personal devices (up to three per key) are registered automatically. For a team repository or CI, SQUAT can set up a project device instead — one shared slot for the whole repo, stored in a small file you commit. The device ID is an identifier, not a secret; your license key itself stays in environment variables or CI secrets, never in the repository.

Verify everything

Whatever the client, the check is the same: ask your AI to confirm the SQUAT workspace connection. If it reports the workspace identity and member list, you're connected. If not, see Troubleshooting — the fix is almost always in how the key or server address is being resolved.

System messages

Occasionally SQUAT has something to tell you at the start of a session — a maintenance announcement for everyone, or an account notice for your workspace (a first-session welcome, a billing reminder). Your AI presents each message once and offers exactly two choices: remind me later (the message comes back at the next session start) or dismiss (it does not return for the scope shown by your client). If a message keeps reappearing, that scope is still on remind-me-later; say “dismiss it” to retire it.