> ## Documentation Index > Fetch the complete documentation index at: https://docs.withgauge.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > For API and SDK launches, integration testing, and ongoing coding-agent checks, start with Gauge Agents: > - [Gauge Agents overview](https://docs.withgauge.com/agents/index.md) > - [Gauge Agents quickstart](https://docs.withgauge.com/agents/quickstart.md) > - [Create and inspect an eval](https://docs.withgauge.com/agents/guides/create-an-eval-and-run-an-experiment.md) > - [Agent Experience: diagnose integration failures](https://docs.withgauge.com/agents/concepts/agent-experience.md) > - [Agent Preference: measure product selection](https://docs.withgauge.com/agents/concepts/agent-preference.md) > - [GitHub PR checks](https://docs.withgauge.com/agents/guides/github-pr-checks.md) > For AI search visibility and AEO, start with [Gauge Chat](https://docs.withgauge.com/introduction/welcome.md). # Improve agent experience > Fix the friction agents hit with your CLI, Skills, and docs, and rerun their sessions to confirm the fix. [Agent Experience](https://docs.withgauge.com/agents/concepts/agent-experience.md) 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](https://docs.withgauge.com/agents/guides/improve-agent-preference.md). ## What you can change | Surface | What the optimization edits | Tree key | | - | - | - | | CLI | CLI rules that change what a command prints, add or replace options, or set environment variables. Agents see the change without a new CLI release. | `cli:` | | Skills | The files of a Skill the session staged, or a new Skill. | `skill:` | | Docs | Any page the agents fetched, or a new page. | `page:` | 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: | Effect | CLI value | Meaning | | - | - | - | | Agent was blocked | `BLOCKED` | The agent could not finish the task. | | Agent took unnecessary turns | `EXTRA_WORK` | The agent finished, but with wasted work. | | Agent was able to recover | `RECOVERED` | The agent hit a problem and worked around it. | 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 > [!NOTE] > > 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](https://docs.withgauge.com/agents/guides/cli.md#choose-a-backend). > > ```bash theme={null} > gauge config set backend hosted > ``` Find friction and its findings: ```bash theme={null} gauge issues list --type friction # most sessions first gauge issues get # the issue's findings and runs ``` Create an optimization and read its authoring guidance: ```bash theme={null} gauge optimizations create --issue gauge optimizations authoring ``` To start from one finding, pass `--finding --run `; `gauge run insight ` shows finding IDs. To start from a goal with no source sessions, pass `--goal ""`. Read the evidence behind each finding. For CLI friction, `commands` shows exactly what the agent ran and saw: ```bash theme={null} gauge run trace --seq # events around a finding's evidence seq gauge run commands --query # shell commands and their output gauge run web # every URL the agent fetched ``` ### 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: ```bash theme={null} gauge optimizations file add --cli gauge optimizations file read cli:@acme/cli gauge optimizations file write --cli @acme/cli --from rules.json ``` `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: ```bash theme={null} gauge optimizations file add --skill acme gauge optimizations file read skill:acme --path SKILL.md --out SKILL.md gauge optimizations file write --skill acme --path SKILL.md --from SKILL.md ``` Every Skill needs a `SKILL.md`. To remove a file from the Skill, pass `--path --delete`. **Docs.** Copy the page, then change part of it with find and replace: ```bash theme={null} gauge optimizations file add --page https://docs.acme.dev/sdk/auth gauge optimizations file read page:https://docs.acme.dev/sdk/auth --query "API key" gauge optimizations file edit --page https://docs.acme.dev/sdk/auth --edits edits.json ``` `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 --page --from page.md`. To drop a file from the tree, use `file rm `. Keep your diagnosis, plan, and each launch's result in the optimization's notes: ```bash theme={null} gauge optimizations notes --from notes.md ``` ### Rerun and compare ```bash theme={null} gauge optimizations launch # asks first; --run reruns a subset gauge optimizations watch ``` 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 `. Before you credit an edit, confirm the rerun used it: `gauge run commands ` for CLI rules, `gauge run web ` 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 ```bash theme={null} gauge optimizations finish --from result.json ``` `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](https://docs.withgauge.com/agents/guides/github-pr-checks.md). ## 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.