From nothing to agents that follow your rules, in minutes.
Two complete paths on one page. The CLI only: no account, nothing leaves your machine, from install to CI and your own rules. Or your team's workspace: one rulebook across repositories, the inbox, evidence and the dashboard. Every step shows the command, what you'll see, and how you know it worked.
Install once; then every command starts with groundrule.
Three things, then one install.
Then choose a path. Path A uses only the CLI: no account, nothing leaves your machine, and it is a complete setup, not a trial. Path B adds your team's workspace: one rulebook across repositories, an inbox, evidence and the dashboard. A repository on Path A joins Path B later with one command.
Node.js 22 or later
node -v to check. If it prints v20 or older, install a current release from nodejs.org or with your version manager.
A git repository
Any language. A few source files are enough to see findings.
For Path B only
A work email, or an invitation to a workspace. The Free workspace never expires.
No terminal at hand? Sign up at app.groundrule.dev, pick one repository on GitHub, and Groundrule scans it in a sealed sandbox and shows the findings in about two minutes. Nothing is added to the repository. The steps are in Start on GitHub.
Install the CLI once.
One command puts groundrule on your path. Prefer not to install anything? Put npx @groundrule/cli in front of each command instead; it downloads the CLI on first use and runs the same thing.
$ npm install --global @groundrule/cli$ groundrule --version # without installing: npx @groundrule/cli --version
To pin one version for a whole team, add it to the project instead: npm install --save-dev --save-exact @groundrule/cli, then run it through your package manager. Updating later is npm install --global @groundrule/cli@latest.
Only the CLI. No account, nothing leaves your machine. Complete in itself.
The CLI only: a rulebook in the repository.
One command shows what the rules find and sets the repository up, in two minutes. Four more steps make it yours and put the check where it cannot be skipped. Everything lives in .groundrule/ and the files it writes; commit them and the whole team has it.
- 01
Run one command 2 min
In the repository's folder. In a repository that is not set up yet,
groundruleon its own takes a first look and writes nothing: the stack it found, how many rules apply, and what the checks find in the code today, worst first. Then it asks one question. Answer yes and it writes the configuration, the files your coding agents read, and the hooks that make the agent check its own work.$ groundrule groundrule · a first look at checkout-api Stack typescript Rules 14 rules from essentials apply here every one is checked on every change What the checks find in this repository today ✕ SEC-004 Do not disable TLS verification BLOCKER · deterministic (regex) src/payments.ts:3 TLS certificate verification is disabled → Remove the override and fix the certificate or trust store instead. ⚠ SEC-005 Commit a dependency lockfile warning · deterministic (files) 2 findings in 2 rules. This is code that already exists: it is listed, and it never blocks. Once set up, only what a change introduces is checked. Set this repository up? It writes: .groundrule/config.yaml the rules this repository follows AGENTS.md, CLAUDE.md the same rules, for your coding agents .claude/settings.json hooks: the check runs when the agent finishes a task Set it up now? [Y/n] y ✓ Set up. Commit these files so your whole team gets the same rules: .groundrule/ AGENTS.md CLAUDE.md .claude/settings.json
It starts from
essentials, a short set of rules that are all checked. Every finding names the rule, shows the evidence and says how to fix it;groundrule explain SEC-004prints why the rule exists, with Do and Don't examples. Findings in code that already exists are listed and never block: from now on,groundrule checklooks only at what a change introduces.Prefer to go step by step? The same thing is
groundrule init,groundrule sync,groundrule check --allandgroundrule hooks, in that order. To skip the question,groundrule start --yes; add--no-hooksto leave the hooks out. More packs:groundrule packslists them, and each goes underextendsin.groundrule/config.yaml.Done when the terminal says "Set up". Commit now:
git add .groundrule AGENTS.md CLAUDE.md .claude && git commit -m "Connect Groundrule". - 02
Decide the findings: fix, except, or override 10 min
The first audit is the rulebook's first real test on your code. Each finding is a decision. Fix it; or excuse specific files for a reason and a time in
.groundrule/exceptions.yaml; or change a pack rule for this repository with an override in.groundrule/config.yaml.apiVersion: groundrule.dev/v1alpha1 kind: ExceptionList spec: exceptions: - id: EX-1001 standard: TS-001 paths: ["scripts/**"] reason: Build scripts print to the console on purpose. expires: "2027-04-30"
overrides: SEC-005: severity: blocker TS-004: disabled: true reason: We use @ts-ignore in generated code only.
Every exception needs a reason and an expiry; there are no permanent ones. Excepted findings stop failing but stay visible with
check --verbose, and agents still get the rule.Done when
groundrule check --allpasses, and the exceptions it lists are the ones you meant. - 03
Write one rule that is yours 10 min
The packs are generic; the value shows with a rule only your team has. The sample left in
.groundrule/standards/is the shape. Give it a check and it is enforced; leavechecksout and it is guidance the agents read.$ mv .groundrule/standards/EXAMPLE-001.yaml.sample .groundrule/standards/ACME-001.yamlapiVersion: groundrule.dev/v1alpha1 kind: Standard metadata: id: ACME-001 title: Use the shared HTTP client type: forbidden-tech owner: team:platform spec: severity: warning intent: One HTTP client means one place for retries, timeouts, and tracing. requirement: Use our shared HTTP client for outbound calls. Do not add axios or got. remediation: Replace the dependency with the shared client. checks: - evaluator: dependencies forbid: [axios, got]
Then
groundrule sync && groundrule check --all: the rule lands inAGENTS.mdand in the check, andgroundrule explain ACME-001prints it back. Every field and every check type is in the documentation.Done when your rule appears in
AGENTS.mdand the check counts it. - 04
Check every pull request in CI 5 min · no token needed
Two steps in your pipeline, with
npxso the runner needs no install. The first fails the build if the agent files drift from.groundrule/; the second checks only what the pull request changed, fails on blockers, and writes the findings into the job summary. An offline repository uploads nothing, so there is no secret to create.- run: npx --yes @groundrule/cli sync --check - run: npx --yes @groundrule/cli check --base "origin/${{ github.base_ref }}" --summary "$GITHUB_STEP_SUMMARY"GitLab and other CI: the same two commands. Add
-f sarif -o groundrule.sarifand upload the file to put findings in GitHub code scanning.Done when a pull request's checks include Groundrule.
- 05
Give the agent the MCP server 2 min
Offline it gives Claude Code, Cursor and any MCP client three tools:
list_standards,rules_for(the rules that apply to the files the agent is about to change) andcheck. Commit a.mcp.jsonto share it with the repository.$ claude mcp add groundrule -- npx -y @groundrule/cli mcp# Cursor and VS Code: the same command in their MCP settings
Done when the agent answers "which Groundrule standards apply here?" from
list_standards.That is Path A in full. Keep it current with
npm install --global @groundrule/cli@latest, andgroundrule doctorexplains anything that looks off. What it does not give you: one rulebook across repositories, rollout stages on evidence, the inbox and imports, the dashboard's numbers, hosted and AI checks. Those are Path B, and a repository joins it later withgroundrule init --org; everything above keeps working.
One rulebook for every repository, an inbox, evidence, and the dashboard.
Your team's workspace.
Eleven steps. The first happens in the browser; most of the rest in a terminal inside the repository, with the same commands as Path A. A repository already on Path A starts at step 02.
- 01
Create the workspace 3 min · in the browser
Go to app.groundrule.dev and choose Create an account (if someone invited you, open the invitation link instead). Sign up with GitHub, or with an email you then confirm. One screen names the workspace (its URL name becomes
app.groundrule.dev/<name>); the name is filled in from your email. The next screen offers to scan a repository on GitHub straight away: do it, or choose Skip for now and carry on here. The workspace starts with the security baseline; add packs under Rules → Packs.Done when Home shows "N standards in effect". Nothing can block anyone yet: each rule starts where its author recommends, and nothing is checked in a repository until it is connected.
- 02
Sign the CLI in 1 min
Anywhere in a terminal. It prints a one-time code and opens the approval page; check the code matches, pick the workspace, approve.
$ groundrule login groundrule login · https://app.groundrule.dev Your one-time code: MGKC-TMFX Approve it at: https://app.groundrule.dev/cli/activate?code=MGKC-TMFX Waiting for approval… ✓ Signed in to Acme Payments (acme-payments) as maya@acme.example
Done when the terminal says "Signed in to …". The token is saved only for your user and lasts 90 days.
- 03
Connect the repository and write the agent files 1 min
In the repository's folder. Use your workspace's URL name.
initlinks the repository to the workspace (on a Path A repository it replaces the local packs with the workspace's rulebook);syncwrites the organization's rules into the agent files.$ groundrule init --org acme-payments ✓ Created .groundrule/config.yaml Platform acme-payments on https://app.groundrule.dev Agents AGENTS.md, CLAUDE.md, .cursor/rules/ $ groundrule sync groundrule sync · 79 standards → agents-md, claude-code, cursor + .cursor/rules/groundrule.mdc created ~ AGENTS.md updated ~ CLAUDE.md updated ✓ Done. Commit these files so every agent gets the same rules.
A warning that the repository "isn't registered" is fine: the organization's rules apply. An admin registers it under Teams → Repositories later to give it its team's settings.
Done when
AGENTS.mdcarries your organization's rules. - 04
Add the hooks and commit 1 min
The same hooks as Path A: the agent checks its own work and hears the rules for a file before editing it. In a connected repository the hook also reports the counts per rule to the workspace after each check (never a path or code), which is what the dashboard shows as flagged in the agent loop. Commit everything so every developer's agent gets the same.
$ groundrule hooks$ git add .groundrule AGENTS.md CLAUDE.md .cursor .claude$ git commit -m "Connect Groundrule"
Done when the commit is on your branch.
- 05
Scan the repository and open the inbox 2 min
The scan runs every catalog rule against the repository without enforcing anything, and finds what the repository already says: agent-file instructions, lint settings, CODEOWNERS, and the architecture the code already keeps. It uploads results and one-line snippets, never your source.
$ groundrule scan --upload groundrule scan · acme/checkout-api · 14 files · 0.1s Rules 183 in the catalog · 90 apply here ✓ 35 already pass ! 6 with findings ◇ 49 guidance only Imports 4 instructions from agent files · 3 tool settings · 2 CODEOWNERS entries Layering 2 boundaries and 1 package gates this code already keeps src/domain must not import src/infra · 9 files depend the other way · clean today ✓ Uploaded to Acme Payments: app.groundrule.dev/acme-payments/scans/…
Open the link, then Inbox. Everything found waits there as proposals: accept, edit or reject each one. Accepting an instruction creates a standard; accepting a boundary creates an architecture rule with its check already written.
Done when you have accepted your first proposal and it appears under Rules.
- 06
Write one rule of your own 2 min · in the browser
Under Rules, choose Describe a rule and say it the way you would tell a new teammate: "We never call Stripe directly; everything goes through src/payments/gateway.ts." AI drafts the full standard with examples and a check it has tested against them (this needs AI on, under Settings → AI). Review it and save. Or write one yourself with New rule.
Done when the rule shows Checked · Deterministic on its page.
- 07
Check every pull request in CI 3 min
The same two steps as Path A, plus
--uploadand a token, so every result appears on the Pull requests page and, with the GitHub App installed, on the pull request as the Groundrule check. Create the token under Settings → API tokens (tick Upload scans and check results) and set it as theGROUNDRULE_TOKENsecret.- run: npx --yes @groundrule/cli sync --check - run: npx --yes @groundrule/cli check --base "origin/${{ github.base_ref }}" --upload env: GROUNDRULE_TOKEN: ${{ secrets.GROUNDRULE_TOKEN }}Done when a pull request shows the Groundrule check.
- 08
Invite the team 1 min · in the browser
Settings → Members → Invite. Standard owners write and accept rules; developers read the rulebook and connect the CLI. Each developer then runs
groundrule loginonce; the repository is already connected.Done when the people who own rules have an owner's role, and the setup card on Home reads 5 of 5.
- 09
Give the agent the MCP server 2 min
Connected, the server adds
propose_rule: when a developer corrects the agent and says the rule should apply to everyone, the agent proposes it to the inbox. Or use the hosted server atmcp.groundrule.devfor cloud agents and web IDEs, with nothing installed.$ claude mcp add groundrule -- npx -y @groundrule/cli mcpDone when the agent answers "which Groundrule standards apply here?" from
list_standards. - 10
Scan nightly, promote on evidence, read the effect ongoing
A nightly
scan --uploadin CI keeps evidence fresh: each rule's page shows what it finds across repositories, and the inbox suggests Ready to move forward when a rule has been clean long enough. Promote what has been clean to Enforce; keep the rest at Advise. The Dashboard then shows where violations are stopped: in the agent loop before a commit existed, on pull requests, and what is still on main. The Compliance page exports the period as CSV with SOC 2 and ISO 27001 mappings.Done when the first rule you promoted to Enforce fails a pull request that breaks it, and nothing else does.
- 11
Optional: hosted checks and AI checks 5 min · in the browser
Hosted checks, for repositories without a CI step: an admin turns on Check pull requests on GitHub under Settings → Connections, and Groundrule checks each pull request in a sealed sandbox, deleting the code when done. AI checks, for the rules no pattern can express: add an
llmcheck with a question; it is answered only on hosted pull requests, advisory, within the AI budget, once an admin turns on AI checks under Settings → AI.Done when a hosted run appears on the Pull requests page.
The things that trip people up, and what each means.
If something looks off.
groundrule doctor explains most of these on its own.
| You see | What it means | Do this |
|---|---|---|
groundrule: command not found | The CLI isn't installed, or your shell hasn't picked up the global install yet. | npm install --global @groundrule/cli and open a new terminal, or run the command as npx @groundrule/cli …. |
An old Node, or npx: command not found | Node.js 22 or later is needed. | node -v; install from nodejs.org or with your version manager, then retry. |
| "This repository has no Groundrule configuration" | You are outside the repository, or init has not run there. | cd into the repository and run groundrule. |
| "acme/checkout-api isn't registered in acme-payments" | Only a warning: the organization's rules apply. | Keep going. An admin registers the repository under Teams → Repositories to apply its team's settings. |
| The check passes but you expected a finding | Only blockers fail by default; rules set to Tell agents (Path B) are taught, not checked; and check without --all looks only at changed lines. | Run check --all; raise the rule's severity with an override (Path A) or set its dial to Warn or Block on its page (Path B). |
| The hook says nothing when the agent finishes | The check passed, or found only warnings. The hook speaks only when a blocker is found. | Working as designed. To see it act once, ask the agent to add a key-shaped literal; it refuses, or is stopped with SEC-003. |
Standards in the age of coding agents, in your inbox.
A short explainer every week or two: who taught the agent your rules, what a code review should catch now, when a rule should block a merge. No product announcements unless they change the answer.
One sitting, then it runs itself.
On its own, the CLI gives a repository a rulebook, agents that read it, a check, and an agent that checks itself. The workspace adds one rulebook for every repository, an inbox, evidence, and the numbers that show what it stopped. Start with whichever fits today; the other is one command away.