DocsSign inSign up

Review your first intent

Last reviewed 26 October 2026.

More

An agent declared an intent and now waits for you. This guide reviews it twice, in the web app and in the terminal: you read the plan, approve it or ask for a change, and later approve the merge. It takes about five minutes.

You need a gitring project with an agent connected (Connect Claude Code or Codex to gitring). The examples use the project storefront, an intent #48 waiting for plan review, and #41 waiting for merge approval.

Tests are off on gitring.tech for now. Where this page shows "Checks passed", gitring.tech shows "No tests ran" and asks you to approve every merge yourself; read the diff before you approve. A project's test command is kept and runs once tests are back.

Every gitring command on this page is run by a test against a fake gitring server, so it works as written.

What you are deciding

An intent is what an agent will change, declared before the code exists: the goal, the plan, and the scope (what it changes and what it uses). You make two kinds of decision on it:

  • Approve plan, for a risky intent, before any code is written. A plan is cheap to change; code is not.
  • Approve merge, after the checks pass on main plus the work.

Each decision names exactly what it judged: the plan version (plan v2), and for a merge the commit. If the agent sends a newer plan or pushes newer code while you read, your approval is refused and you read again. An agent never approves.

In the web app

  1. Open Inbox (keys G then I). The first line says how much waits for you: "3 things wait for you in storefront. The oldest has waited 3 hours." Plan reviews come first: an agent is waiting to write code.
  2. Select #48. The page reads top to bottom in the order you decide in: Goal and plan, Drift, Conflicts settled, Checks, Decisions, and last the Changes, folded, because the diff is evidence for the plan.
  3. Read "Why this plan waits for you". For #48: "High risk: changes the exported signature of createOrder in src/api/routes/orders.ts."
  4. Decide:
    • Approve plan (⌘↵). The toast says "Plan v1 approved. claude-code can start."
    • Request a change (R) to ask for a better plan. Say what to change and why; the agent reads it as a change request.
    • Reject plan to end the intent. It becomes Withdrawn.
  5. Later, #41 arrives as a merge approval: "Checks passed. 1 change outside the plan." Read Drift: a minor drift does not block the merge. Open Changes (D) if you want the diff. Then Approve merge (⌘↵), or Send back (S) with a note on what must change.

In the terminal

Install the command line and sign in. gitring login shows a link and a code: type the code in the web app where you are signed in, check that the page names your machine, and approve. That is the only way to get a person token; Settings, then Tokens, lists and revokes it. It can approve, so sign in on a computer where no agent works with a shell as you:

npm install -g @gitring/cli
gitring login --server https://gitring.example.com

See what waits for you:

gitring inbox
3 things wait for you in storefront. The oldest has waited 3 hours.

Plan review  storefront#48  Change the createOrder signature
  High risk: changes the exported signature of createOrder in src/api/routes/orders.ts.
  Waiting 3 hours. Read it: gitring show storefront#48
…

Read the intent. show prints the page in the same order as the web app:

gitring show storefront#48
#48 Change the createOrder signature
Plan review. A person must approve the plan before any code is written.
Author claude-code (agent) · Risk high · plan v1 · head none · int_01JC…

Waits for you
  Approve plan v1: gitring approve storefront#48
  Send back: gitring send-back storefront#48 "what must change"

Goal and plan
  …

Approve the plan:

gitring approve storefront#48
Plan v1 approved for storefront#48. claude-code can start.

Or, instead of approving, send the plan back with what must change. The intent stays in plan review until the agent sends plan v2:

gitring send-back storefront#48 "Keep createOrder(input) working; add the options object as a second argument."

Approve a merge

Read #41 and unfold its changes:

gitring show storefront#41 --diff

Under Drift it says "1 change outside the plan … Merge is not blocked." Ask for a change on specific lines without stopping the intent:

gitring request storefront#41 "Name the test after the rounding rule." --at src/cart/cart.test.ts:1-2

When you are satisfied, approve the merge. Pass the plan version and the commit you read, so the approval is refused if either changed since:

gitring approve storefront#41 --plan-version 2 --head 7d2e9b1
Merge approved for storefront#41: plan v2, commit 7d2e9b1. It is Queued.

A queued intent can still be sent back if you change your mind:

gitring send-back storefront#41 "Hold this until the currency work lands."

Settle a conflict

When the rules leave a pair of intents open, gitring's judge settles it if it is sure enough; the pair then says "Settled by gitring's judge" with its reason, and you can settle it again while it is open. When the judge is not sure, the conflict waits for you. To settle every such pair yourself, an owner sets Who settles overlaps to A person on the project's Rules tab. gitring show prints the command with both intents filled in; name the one that yields:

gitring show storefront#47
gitring settle cnf_01JC0000000000000000000002 --yields storefront#47
Settled: #47 yields to #41.

Scripts and CI

Every command takes --json and prints the protocol shapes from @gitring/protocol. Exit codes are stable (0 done, 3 sign-in, 4 not found, 5 refused, 6 server unreachable; the full table is in Command line reference). In CI, set GITRING_SERVER and GITRING_TOKEN instead of signing in:

gitring inbox --json

For more control, gitring's TypeScript client is @gitring/sdk, which is not published yet; when it is, this waits until an intent merges, following the event stream instead of polling:

import { createClient } from "@gitring/sdk";

const gitring = createClient({ server: "https://gitring.example.com", token: process.env.GITRING_TOKEN });
const done = await gitring.waitFor("int_01JBQ8M4ZK7V3XW9N2D5HT6RYE", { until: ["merged", "withdrawn"], timeoutMs: 30 * 60_000 });
console.log(`#${done.intent.number} is ${done.intent.state}`);

Next

All guides