Quickstart

This page takes you through one full loop: check a project, understand a problem, fix it, keep the check and run it from the command line. The first check spends most of its time on downloads.

Before you start

Install Geometer. If Docker is not ready, Geometer offers to set it up where you are: the installer and the terminal commands (geo doctor --fix) 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 and does not change it. It writes into your project only when you keep a check, and then only under .geometer/.

Try the practice agent first

To see the whole loop without touching your own code, run:

geo practice --check

Geometer writes a copy of a sample refund agent with a known mistake into its own records folder, not into your projects, and checks it straight away. If Docker is not ready, it offers to set it up first. See Docker and Colima.

Check your own project

Go to the project folder and run:

geo check

Geometer reads the folder. It 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. 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.
Geometer builds containers and runs your agent normally, then runs it again with things going wrong on purpose. --budget SECONDS sets how long agent runs may take. 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. The first check downloads container images and installs dependencies, which can take several minutes. Later checks start much faster. Press Ctrl-C to end a check early.
Read the result. The first line is the verdict: “Found 1 problem: …” (or “Found 3 problems.”), “No problems found in what was tried.”, “Not enough evidence to say.”, “Couldn’t run: …” or “Geometer could not finish the check.” After it come the agent the problem is in and its Problem id, any suggestions (they do not fail the check), anything missing, and the next command to run. The last lines say how many fault runs were Tried and how many approved rules no run reached (Not tried).

Read a problem

The verdict names the problem by what happened, for example that a customer was refunded twice. The line Problem id is the identifier you give to the other commands. For the whole story of one problem, use:

geo ci --json: the JSON report lists every problem, with its rule and the steps.
geo replay <finding>: runs the problem again from a clean start, so you see it happen.
Your coding assistant, through geo mcp serve: its explain_problem tool gives a brief of what happened, the rule that must hold and the conditions Geometer created.

Replay it

Run geo replay <finding>. 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. 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, geo verify, geo regression keep works. In the sample, for example, make the agent ask the payment provider whether the first call happened before it tries again. Then run:

geo verify <finding>

Geometer replays the problem on your code as it is now and tries a few nearby cases. It prints one line with the verdict and how many runs were made, how many exercised the risky path and how many broke the rule, then any reasons:

reproduced: the problem still happens. Exit code 1.
no_longer_reproduced: the recorded run and the nearby cases no longer break the rule. The counts say how many were tried. It is not a claim about every situation. Exit code 0.
inconclusive: something needed was missing, so Geometer does not call it fixed. Exit code 2.
incompatible: the recorded run cannot be repeated on this version of the code. Exit code 2.

Keep the check

Run geo regression keep <finding>. 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 again, and in CI

geo check runs your kept checks after the automatic checks. In scripts and CI use geo ci, which does the same work with output made for machines. 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.

About the practice project

The sample refund agent has a known mistake. 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. There is a second practice world for game teams: an item restoration desk that double-credits a player after a lost reply. Run geo practice --world games --check. Both use the same agents, and the games world tells its stories in game words. Finishing the loop says nothing about your own agent.

What next

Concepts (What a rule, a situation, a problem and a kept check are.)
Watch with Guard (Record what Guard would stop before it stops anything.)
Issue a certificate (Share what was checked with a reviewer.)