Quickstart for agents

There are two ways to put an agent under your team’s rules.

	What it does	Status
MCP server	The agent reads the rule set and calls `check_action` before it saves	Available in the preview, with a key we issue
Guard	Every write is checked whether or not the agent asks	`npx getclaros`

Read the rules (MCP server)

You need an agent-scope key (clr_…). Create one on Account → Agent keys (/account/keys) or ask us for one (Agent keys).

export CLAROS_AGENT_KEY=clr_...
claude mcp add --transport http claros https://claros.sh/mcp \
  --header "Authorization: Bearer $CLAROS_AGENT_KEY"

Ask the agent to call get_workflow and list the rules. Then tell it: before any save or submit, call check_action and obey allowed: false. Other clients: MCP server. The catch: the agent decides whether to ask. An agent that forgets is never stopped. That’s what the guard is for.

Guard every write

One command, under a minute, every agent on your machine:

npx getclaros

Finds Claros. From the web app’s address (--web, or a link to your Claros: npx getclaros https://your-claros.example).
Signs you in. It opens a page in your browser with a code; approve it and pick the workspace. Any member can.
Finds your agents. Claude Code, Cursor, Codex, Claude Desktop and VS Code (their MCP configs, yours and this project’s), Playwright and browser-use in this project, Pomerado servers. It shows one short list of what it found.
Guards all of it. Press Enter (or pass --yes). Every MCP server it can guard is wrapped, so each write goes through Claros first and reads pass straight through; Claude Code, Codex and Cursor get a hook so shell commands and file edits are checked too, in every project on this machine. --servers a,b narrows the MCP servers, --project-hooks keeps the hooks to this project.
Proves it. For each agent it sends a made-up action that breaks one of your rules: through the hook it installed, run the way the agent runs it, or a dry check for MCP-only apps. Nothing is run and nothing is logged.

  Proving it works  a made-up action that breaks one of your rules: checked, never run
    Claude Code — guarded ✓ (hook + MCP)  · stopped in 182 ms
    Cursor — guarded ✓ (hook + MCP)  · stopped in 175 ms
    Claude Desktop — guarded ✓ (MCP)  · stopped in 41 ms

  Next  restart Claude Code, Cursor, Claude Desktop so they pick up the change
  See your agents  https://claros.sh/app

Your agents then show on Home → Your agents, as soon as they run, before they write anything. Run it again anytime: it shows the same list and fixes what changed, for example a config an app update rewrote.

npx getclaros status   # per agent: guarded, not guarded, or changed since setup, and its last check; exit 1 if any isn't guarded
npx getclaros test     # a made-up action that breaks one of your rules → the stop, nothing sent to the app
npx getclaros undo     # puts back every file setup changed

What setup changes:

Agent	Found by	What it does
MCP agents (Claude Code, Claude Desktop, Cursor, VS Code, Codex)	their MCP configs	wraps each server so every write tool call goes through Claros first (MCP guard). Remote servers that sign in with OAuth can’t be guarded yet; the list names them.
Coding agents (Claude Code, Codex, Cursor)	their home or project directory	adds a native hook so every shell command and file edit is checked first: `~/.claude/settings.json`, `~/.codex/hooks.json`, `~/.cursor/hooks.json` (Coding agents)
Playwright	`@playwright/test` or `playwright` in package.json	installs the hook with your package manager; for Playwright Test writes `claros.fixture.ts` and prints the one import to change in your specs (Playwright)
browser-use	`browser-use` in pyproject.toml, requirements, uv.lock or poetry.lock	installs it with uv, poetry, or pip into your virtualenv; prints the two lines to add where you build the agent (browser-use)

Browser hooks read CLAROS_KEY from the environment. Setup writes it to your .env only if git ignores that file and doesn’t track it; otherwise it prints an export line that never shows the key. It never installs globally, never edits your source files, and backs up every file before it changes it. When an agent waits on an ask, its terminal says who it waits for and what: Waiting for Dana to approve: claude-code · runs vercel deploy --prod in shop — they've been notified. When the question is yours to decide, it shows the link.

Scripted setup (Claros for Mac, CI)

Without a browser: the key from CLAROS_KEY or on stdin, the server named, no questions, the result as JSON on stdout (what people read goes to stderr). Pin the version:

printf %s "$KEY" | npx -y getclaros@0.5.0 setup --yes --json --key-stdin --server https://claros-server.example
npx -y getclaros@0.5.0 status --json

{
  "ok": true,
  "server": "https://claros-server.example",
  "workspace": { "id": "ws_…", "name": "Acme" },
  "agents": [
    { "agent": "Claude Code", "found": true, "state": "guarded", "guarded": true, "how": ["hook", "mcp"], "proof": "ok", "detail": "stopped in 182 ms" },
    { "agent": "VS Code", "found": false, "state": "not found", "guarded": false, "how": [], "proof": "skipped", "detail": "not on this machine" }
  ],
  "restart": ["Claude Code"]
}

state is guarded, not guarded, drifted (changed since setup), nothing to guard or not found; how lists hook, mcp, browser; proof is ok, failed or skipped. status --json has the same rows (proof skipped) plus last_seen. The key never appears in any output (clr_ab12cd34_…).

Exit	setup	status
0	every agent found is guarded and its proof passed	every agent found is guarded
1	something isn’t guarded or a proof failed	an agent isn’t guarded, changed since setup, or a browser agent isn’t set up
2	bad usage, or no key	no key
3	no Claros server, or the key was rejected	Claros unreachable, or the key was rejected

A person’s agents and their recent stops and asks, with the same key: GET /v1/me/agents?since=<unix time> returns

{person, agents: [{agent, status: guarded|quiet|unknown, last_seen, last_check, machines, checks, stop, ask, nudge, coverage}], events: [{id, ts, agent, app, tool, result: stop|ask, summary, rule, question}], cursor}

. Events come oldest first, at most 100; pass cursor back as since to get only new ones.

Get started

Rules

Checking

Evidence

Guard

Accounts

Security

Changelog

Quickstart for agents

Read the rules (MCP server)

Guard every write

Scripted setup (Claros for Mac, CI)

​Read the rules (MCP server)

​Guard every write

​Scripted setup (Claros for Mac, CI)

Read the rules (MCP server)

Guard every write

Scripted setup (Claros for Mac, CI)