Collect agent friction

Agents run into the same papercuts again and again: a doc that misses a step, an error that points the wrong way, an install that needs a token nobody mentioned. Friction reports collect them. Every report of the same problem adds to one item, so the count shows what to fix first.

Friction reports are in early access: ask us to turn on friction for your workspace.

What a report contains

Never put secrets or customer data in a report.

What gets recorded

The server checks every report before recording it, whichever way it was filed. A report is skipped, with a hint for improving it, when:

• the reproduction is missing or shorter than 20 characters,
• it only describes the reporting session (“I forgot”, “my context”) and names no tool, file or cause,
• wanted restates whatHappened, or no cost is given,
• a repo report names nothing in the repository, or a trevize report names no tool or step.

A skip is guidance, not an error: the agent improves the report and files it again.

Reports are matched by scope, repository and title. Titles are compared after removing case, punctuation, numbers, commit SHAs, paths and filler words, so “Typecheck fails at 3f9a2c1” and “typecheck fails at 9b8e7d6” are the same item. A matching report adds one to the item’s count and keeps its details. Each item keeps its 50 most recent reports; the count keeps going up after that.

An item is open until someone resolves or dismisses it. A new report of a resolved or dismissed problem opens a new item, so a regression shows up.

Filing reports

In cloud runs and sessions, agents get a file_friction tool and are asked to use it before they finish a step. Each call stays visible in the run’s timeline.

Locally, use the CLI or its MCP server:

trevize friction file \
  --scope environment \
  --title "bun install needs the registry token" \
  --what "bun install exits with 401 from npm.pkg.github.com" \
  --wanted "The token documented in the README" \
  --repro "Run bun install in a fresh clone without NPM_TOKEN" \
  --minutes 15

--json <file|-> reads the whole report as JSON, and --dry-run runs the check locally without sending anything. The repository defaults to the origin remote. trevize mcp exposes the same as the file_friction tool.

To teach local agents when and how to file, install the file-friction skill into the repository:

trevize skills add file-friction

It writes .agents/skills/file-friction/SKILL.md, the shared skills folder that works across agents. For an agent that only reads its own folder, pick it with --dir, for example --dir .claude/skills. trevize skills add with no name installs every Trevize skill. An existing skill is kept unless you confirm overwriting it; pass --yes to overwrite without asking.

Reviewing items

The Friction page in the web app lists the workspace’s items, most reported first, with a two-week trend for each. Switch between active, resolved and dismissed items, and filter by status, scope or repository. An item shows its latest report, the average time and retries it costs per report, and its recent reports with the runs they came from and the harness, model and effort of the agent that filed each one.

From an item you can:

• Fix with agent: start a background task on the item’s repository with the workspace’s bug fix blueprint and the report as its prompt. The item moves to fixing and links to the task.
• Create Linear issue, when an issue tracker is set up. The item moves to routed and links to the issue by its key.
• Resolve or Dismiss it. Dismissing needs a reason.
• Reopen a resolved or dismissed item. If a newer active item already collects the same reports, reopening is refused.

From the command line:

trevize friction list --status open --scope repo
trevize friction get <id>
trevize friction dismiss <id> --reason "Works as intended"
trevize friction issue <id>

The /api/v1/friction routes do the same: POST /friction files a report, GET /friction lists items most reported first, GET /friction/{id} returns an item with its recent reports, and POST /friction/{id}/status resolves, dismisses or reopens one.

Fixing automatically

An automation with the Friction reports trigger fixes items on its own: when an open or routed item in one of its repositories reaches the number of reports you set, it starts a run on that repository with the item’s report and moves the item to Fixing.

Issue tracker

Workspace owners and admins can send friction items to Linear under Settings → Friction. Issue creation is off until a tracker is picked, and Linear is offered once the workspace has connected it under Settings → Integrations.

• Default team gets every issue, unless Teams per repository maps the item’s repository to another team. A Project is optional.
• Every issue gets the friction label, created on the team if it doesn’t exist. The issue carries the report, its scope, repository and report count.
• Create issues automatically creates an issue when an open item reaches the set number of reports, for the scopes you pick. Trevize-scope items are never sent automatically.
• When an item with an issue is reported again, the issue gets a “seen again” comment, at most once a day.
• When the issue is completed in Linear the item is resolved, when it is canceled the item is dismissed, and when it is reopened the item goes back to routed. This needs Issues events enabled on the Linear app’s webhook.

GET /friction/settings and PUT /friction/settings read and change these settings (PUT is for owners and admins), and POST /friction/{id}/issue creates one item’s issue.