Coding agent snapshot

1

Install the CLI

Full install steps (Linux, Windows, JAR, token, env): Install and configure the quemsi CLI.

Short version — download from /cli-releases/latest/ and put the binary on PATH. On Windows the file is quemsi.exe; the command is still quemsi.

Linux:

curl -fsSL -o quemsi https://quemsi.com/cli-releases/latest/quemsi && chmod +x quemsi && sudo mv quemsi /usr/local/bin/quemsi

Windows: download quemsi.exe and add it to PATH.

JAR (Java 21), either OS:

curl -fsSL -o quemsi.jar https://quemsi.com/cli-releases/latest/quemsi.jar
java -jar quemsi.jar snapshot --data … --agent …

2

Create a laptop token

Open Company Setup → API tokens. Name it something like cursor-local. Bind it to your local agent. Scopes: snapshot and read only — not restore. See Create API tokens.

Store the secret for your whole login session, not only one terminal. Create the directory, then write ~/.config/environment.d/quemsi.conf (no export, and do not commit this file):

mkdir -p ~/.config/environment.d

QUEMSI_TOKEN=qsk_...
QUEMSI_AGENT=your-local-agent-name

QUEMSI_AGENT is the agent name on your machine. The rule reads it from the environment so the rule file has no agent placeholder to copy. QUEMSI_URL is optional and defaults to https://quemsi.com. Log out and back in so every new terminal and app sees the file, then restart Cursor or start a new Claude Code session.

3

Check the snapshot command

--wait is the default. Do not start the app, tests, or a migrate command until this exits 0. While it waits, the CLI prints a console link (…/app/flows/execution/{id}) so you can open progress and logs. Sign in as a person to view that page.

A finished command names this change. Restore keeps the latest snapshot for each tag combination, so a unique change tag is what makes this snapshot its own card. Reusing only purpose=pre-schema hides the previous one.

quemsi snapshot --data job-listings --agent "$QUEMSI_AGENT" \
  --tag purpose=pre-schema --tag change=job-listing-country \
  --descript "before V2 add job_listing.country"

4

Add a Cursor rule in the app repo

This file is what makes Cursor snapshot before it changes schema. Save it in the application you are coding, not in Quemsi. Path: .cursor/rules/quemsi-snapshot.mdc. Put your real data name on the config line once. Leave the agent name to QUEMSI_AGENT. Widen the globs if your entities do not match those paths.

The rule tells Cursor to build the command for the task in front of it. It must not paste a sample from this page.

---
description: Snapshot the local database before schema changes
globs: "**/*Entity.java,**/entity/**/*.java,**/entities/**/*.java,**/db/migration/**,**/db/changelog/**"
alwaysApply: false
---

Before you change a matching file, or before you start the app when Hibernate will apply schema changes, run quemsi snapshot and wait until it exits 0.

Quemsi data name: REPLACE_WITH_DATA_NAME

Build the command for this change. Do not copy a sample and do not leave placeholders.

- --data is the Quemsi data name above. If it still says REPLACE_WITH_DATA_NAME, stop and ask for the real name.
- --agent is the QUEMSI_AGENT environment variable. If it is unset, stop. Do not invent an agent name.
- Always pass --tag purpose=pre-schema.
- Add --tag change=<slug>. Slug is kebab-case from this task (table and column, or migration id), such as job-listing-country.
- Pass --descript as one sentence that names the migration file or entity and the column, such as "before V2 add job_listing.country".
- If this data has more than one forward flow, pass --flow with the flow name.
- Do not restore unless the person asks.
- If quemsi is missing or QUEMSI_TOKEN is unset, stop.
- Do not commit the token.

Reload Cursor after saving the file. Ask Cursor to add the column or migration; it should propose a command like the example in step 3, with a change tag and description taken from that edit. In Ask mode it can only print the command. In Agent mode it can run it. Typing the change yourself does not trigger the rule.

5

Or add a Claude Code rule in the app repo

Same instruction, different file. Save it in the application you are coding. Path: .claude/rules/quemsi-snapshot.md. paths is Claude Code’s equivalent of Cursor’s globs: the rule loads when Claude opens a matching file. Put your real data name on the config line once. Reuse the same QUEMSI_TOKEN and QUEMSI_AGENT from step 2.

---
paths:
  - "**/*Entity.java"
  - "**/entity/**/*.java"
  - "**/entities/**/*.java"
  - "**/db/migration/**"
  - "**/db/changelog/**"
---

Before you change a matching file, or before you start the app when Hibernate will apply schema changes, run quemsi snapshot and wait until it exits 0.

Quemsi data name: REPLACE_WITH_DATA_NAME

Build the command for this change. Do not copy a sample and do not leave placeholders.

- --data is the Quemsi data name above. If it still says REPLACE_WITH_DATA_NAME, stop and ask for the real name.
- --agent is the QUEMSI_AGENT environment variable. If it is unset, stop. Do not invent an agent name.
- Always pass --tag purpose=pre-schema.
- Add --tag change=<slug>. Slug is kebab-case from this task (table and column, or migration id), such as job-listing-country.
- Pass --descript as one sentence that names the migration file or entity and the column, such as "before V2 add job_listing.country".
- If this data has more than one forward flow, pass --flow with the flow name.
- Do not restore unless the person asks.
- If quemsi is missing or QUEMSI_TOKEN is unset, stop.
- Do not commit the token.

Start a new Claude Code session after saving the file. Run /context and check memory files to confirm the rule loaded. Ask Claude to add the column or migration; it should build the same kind of command as step 3. Editing the file yourself does not trigger the rule.