Quickstart

Before you start#

• Install Geometer. If Docker is not ready, Geometer offers to set it up where you are: the installer, the terminal commands (geo doctor --fix), the workspace and your coding assistant all show the exact commands and ask first. See Install.
• If your agent uses MCP servers, run npx @geometer/init in its folder to wrap them with a preview first. See Put Geometer in front of your MCP servers.
• Have a project folder ready. If your project has an AI agent, it should be in a folder that holds files such as package.json, pyproject.toml, go.mod or compose.yaml.
• Geometer reads the folder when you open it and does not change it. It writes into your project only when you keep a check, and then only under .geometer/.

Open the workspace#

In the Mac app, open Geometer. (If you want the geo command in a terminal too, press Add the geo command on the welcome page; see Install.) In a terminal, on a Mac or on Linux, run:

geo open

geo open starts the workspace on your own computer (address 127.0.0.1, port 7310 unless you pass --port) and prints a one-time sign-in link. It opens your browser when you run it from a terminal. Follow the link; it works once and expires after ten minutes. If you need another, run geo open again.

The first page is called Open a project to check. Its first step, Docker, says either Docker is ready or Get Docker ready. If Docker is not ready, follow that card. See Docker and Colima.

Check your own project#

1. Choose the project folder. In the Mac app, press Choose a folder… and pick the folder, or type its path into Or type its path and press Open. In a browser, type the folder's path into Folder path and press Open. Geometer only reads the folder at this point. It does not run, install or change anything.
2. See what Geometer found. Geometer lists your agents and their tasks, the outside services they call, the project's own tests and the rules that apply, in plain words. If it cannot work something out, it asks at most one grouped question with a suggested answer. Press Use the suggestion or type your own answer and press Use my answer. If it finds no agent task, or cannot start the app, it says what was missing. In that case only your own tests can run, and a clean result says only that none of your tests failed.
3. Choose how long agent runs may take. Under Options, Time limit for agent runs offers Quick (up to 2 minutes of runs), Standard (up to 10 minutes) and Longer (up to 30 minutes). Starting services and building images comes on top of this limit. When the limit is reached, the check stops trying new runs and says so.
4. Press Check this project. Geometer builds containers, runs your agent normally, then runs it again with things going wrong on purpose. The first check downloads container images and installs dependencies, which can take several minutes. Later checks start much faster. Every step appears as it happens. You can leave the page and the check keeps going, or press Stop check to end it.
5. Read the result. The result is the board: a grid of your agent's tools against faults, each cell Held, Broke, Couldn't tell or a quiet Try it. A check ends with one of three results: Problem found, a rule you rely on broke; Possible problem, a suggested rule broke and counts only once you agree the rule is right; or No problems found within these limits, which means nothing broke in the runs that were tried. The page also lists What was found, What was not checked and How to repeat it.

Read a problem#

Press a Broke cell on the board. The problem opens beside it and reads consequence first, for example that a customer was refunded twice. Under it you find:

• Rule, with what was Expected and what was Observed.
• Step by step, each call your agent made, in order, and which one lost its reply or was cut short.
• Effects recorded by the simulated tools, with whether the tool itself confirmed each effect.
• Why, technically and the exact commands, for the engineer who wants them.

The steps run along a thin line on the problem page, and a lost reply shows dashed. "Share a clip" saves the run as a file you can send. Every picture on the page has a text form.

Replay it#

Press Replay. Geometer repeats the run from a clean start with the same recorded answers as the first time, so you can see for yourself that the problem is real. Pressing it again says Replay again. The same replay from a terminal is geo replay <finding>. See Concepts.

Check your fix#

Change your agent's code in your own editor, right where it is: Geometer saved a recording of the problem when the check found it, so the order check, edit, Check my fix, Keep this check works. In the sample, for example, make the agent ask the payment provider whether the first call happened before it tries again. Then press Check my fix. Geometer replays the problem on your code as it is now and tries a few nearby cases. It answers in words:

• Still happens: the problem is still there.
• Fixed within what was checked: the recorded run and the nearby cases no longer break the rule. The explanation says how many were tried. It is not a claim about every situation.
• Could not tell: something needed was missing, so Geometer does not call it fixed.
• Cannot check on this version: the recorded run cannot be repeated on this version of the code.

Keep the check#

Press Keep this check. Geometer records the problem again as a check that can be re-run, and writes a reviewable file under .geometer/regressions/ in your project. Commit that file with your fix. This is the one place where Geometer changes your project's files. See Fix a problem and keep the check.

Run it from the command line#

In your project folder, run:

geo check

geo check does the same as Check this project, without a window: a one-line verdict, the problems in plain words and the next command. It then re-runs your kept checks. In scripts and CI use geo ci, which does the same work with output made for machines. To try Geometer first, run geo practice. Run geo on its own for a short status and the next step.

Both commands exit with 0 when nothing failed, 1 when a confirmed problem or a reproduced kept check was found, 2 when required evidence is missing and 3 for an infrastructure failure such as Docker not running. To use it in CI, see Run kept checks in CI.

Or learn on the practice project first#

Geometer includes a sample refund agent with a known mistake, so you can learn the loop without touching your own code. On the first screen, press Try the practice agent; it opens on the first-check page like any project. Geometer writes a copy of the sample into its own records folder, not into your projects. There is a second practice world for game teams: an item restoration desk that double-credits a player after a lost reply; open it from the first screen's second link, or run geo practice --world games --check. Both use the same agents, and the games world tells its stories in game words. The practice check reaches every rule the project declares: a small refund, a refund above the limit that comes with an approval (Geometer's test approver gives it, as a person would) and an email to a customer. The one problem it finds is the double refund; once that is fixed, the agent holds on all three rules. Five short steps guide you: find the double refund, read its replay, fix it and check the fix, keep the check, then watch in shadow with Guard and draft a certificate. Each step reads its status from the practice project's own records. Finishing them says nothing about your own agent.

What next#

• ConceptsWhat a rule, a situation, a problem and a kept check are.
• Watch with GuardRecord what Guard would stop before it stops anything.
• Grant an autonomy levelGive an action more authority, with a limit and a review date.
• Issue a certificateShare what was checked with a reviewer.