Skip to main content
Agent Experience shows where agents struggle to use your product. An optimization tests a fix for that friction. You edit copies of what the agents used: your CLI, Skills, and docs. Gauge reruns the same sessions with your edits in place and analyzes the reruns. Each original finding comes back resolved or returned, and new problems show as introduced. Nothing deploys. The result is a diff and a summary that you apply through your usual review process. To change why agents choose your product, see Improve agent preference.

​
What you can change

The set of files you changed is the optimization’s tree. Anything not in the tree reruns as the session had it.

​
Choose what to improve

A finding is one problem in one session. An issue is the same finding across many sessions. The web app lists issues as themes on the Findings tab of Agent Experience. Start with the friction that costs agents the most. Rank issues by how many sessions they affect and by effect: Read the findings and their evidence before you name a cause. A failed command can come from a confusing error message, a missing example in a guide, or a Skill that points to an old flag. Prefer fixes on surfaces you own.

​
Start an optimization

Click Optimize in any of these places:
  • A theme on the Findings tab of Agent Experience. The optimization reruns up to 12 of the theme’s most recent sessions.
  • A finding on a run page. The optimization reruns that session.
  • The Optimizations page, under Start a new optimization. Choose a theme on the Friction tab.
Starting an optimization launches nothing and uses no credits.

​
Work with Ask Gauge

The optimization opens in an Ask Gauge chat. Tell it what to focus on or which sessions to skip, or reply “start”. Ask Gauge works in stages and ends each turn with one question about the next step:
  1. Diagnose and edit. It reads the findings and the trace where the agent stalled. It says which surfaces caused the friction and which you own, then edits copies of them.
  2. Rerun. It asks before every launch, even in auto mode. Reruns use credits like any run.
  3. Read. Gauge wakes the chat as reruns finish. Ask Gauge compares the findings and updates its notes.
  4. Finish. It records the result.
Reply “yes” to approve the step it names, or type a reply to steer it. The panel beside the chat has three tabs:
  • Changes shows each changed file with its diff against the original.
  • Coding Sessions lists the reruns. Open one to see where it read your change.
  • Agent scratchpad holds the diagnosis, each edit and why, and what each rerun showed.

​
Run the loop from the CLI

These CLI commands use hosted Gauge. The CLI uses the local backend by default, so set hosted once after you sign in, or add --hosted to each command. See Choose a backend.
Find friction and its findings:
Create an optimization and read its authoring guidance:
To start from one finding, pass --finding <finding-id> --run <run-id>; gauge run insight <run-id> shows finding IDs. To start from a goal with no source sessions, pass --goal "<text>". Read the evidence behind each finding. For CLI friction, commands shows exactly what the agent ran and saw:

​
Edit the tree

Copy each original into the tree before you edit it, so the diff shows only your change. CLI rules. Copy the rules the session ran with, then write the changed rules:
rules.json uses the format {schemaVersion: 3, target, rules, shippingIntent}. Gauge seals it for you. gauge instructions optimization describes the rules for a coding agent. Skills. Copy a Skill the session staged, then write each changed file:
Every Skill needs a SKILL.md. To remove a file from the Skill, pass --path <path> --delete. Docs. Copy the page, then change part of it with find and replace:
edits.json is a list of {"find": "...", "replace": "..."} on the page’s exact source. Copy the find text from file read --query. Each find must match once, and all edits apply or none do. The output shows how much of the page you kept. For a new page or a full rewrite, use file write <optimization-id> --page <url> --from page.md. To drop a file from the tree, use file rm <optimization-id> <key>. Keep your diagnosis, plan, and each launch’s result in the optimization’s notes:

​
Rerun and compare

A launch reruns each source session with the same task, agent, model, and settings, plus your tree. It lists the changed files; check that every edit you meant to test is there. Rerun only the sessions your edits address. Pass --yes only for a launch that is already approved. watch waits until every rerun finishes and is analyzed. It then shows each source finding as resolved or returned, and new findings as introduced. To read a launch again, use gauge optimizations launches <optimization-id> <launch-id>. Before you credit an edit, confirm the rerun used it: gauge run commands <rerun-id> for CLI rules, gauge run web <rerun-id> for pages. If the rerun never used the change, the result does not show that the edit helped. Also check the eval’s criteria on the reruns. Edit and launch again in the same optimization until the friction resolves.

​
Finish

result.json is {summary, changed, resolved, returned, introduced}: a PR-style summary, the changed tree keys, and the findings in each group as {runId, label}. After you finish, the tree can no longer change. For a coding agent, gauge instructions issues and gauge instructions optimization describe the full workflow.

​
Ship the change

In the web app, click Copy for agent. It copies the changes and evidence as a prompt for your coding agent, which applies them where your files live. For CLI rules, the agent changes the CLI source to match. Review and publish the change through your usual process. After you publish, run the eval again against the released version. Try other relevant tasks and models too, to check that the fix helps beyond these sessions. To test a change before you merge it, use GitHub PR checks.

​
Earlier optimizations

Optimizations no longer use baselines, rounds, trials, adoption, or handoff. CLI versions before 0.26.0 use the earlier optimizations API and now get an update message. Run gauge update to upgrade.