# obss frictions - Obss

CLI
obss frictions
List the frictions agents hit in your runs, filter them by where to fix and by family, and read one friction with its evidence.
A friction is a problem that agents hit, tracked across runs and experiments under one stable
frc_
ID. Use
obss frictions list
to decide what to fix first, and
obss frictions get
to read one friction with its evidence.
Frictions
explains how Insights find, group, and rank them.
obss frictions list
List and filter the project’s frictions. By default, the frictions with the most runs that the agent never got past come first.
obss
frictions
list
[flags]
Plugin (MCP) tool:
list_frictions
Flags
Flag
Type
Default
Description
--experiment-id
string
Runs of this
exp_
experiment.
--schedule-id
string
Runs of the experiments this
sch_
schedule launched.
--task-id
string
Runs of this
tsk_
task, in any version.
--task-version-id
string
Runs of this
tskver_
task version.
--treatment-id
string
Runs of this
trt_
treatment (toolset).
--tool-id
string
Runs whose treatment had this skill, MCP server, CLI, or SDK (
skl_
,
mcp_
,
cli_
,
sdk_
), in any version.
--tool-version-id
string
Runs whose treatment had this tool version (
sklver_
,
mcpver_
,
cliver_
,
sdkver_
).
--file-id
string
Runs whose task had this
fld_
file.
--machine-id
string
Runs whose task ran on this
env_
machine.
--agent-id
string
Runs of this agent key, such as
claude-code
, with any model.
--agent-model-id
string
Runs of this
agm_
agent and model.
--friction-id
string
Runs where this
frc_
friction occurred.
--fix-in
string
Comma-separated places to fix:
product
,
agent
,
setup
,
agent_behavior
. See
Where to fix
.
--family
string
Comma-separated families:
product_gap
,
docs_gap
,
environment_gap
,
agent_harness_gap
,
agent_reasoning_gap
,
task_quality_gap
. See
Family
.
--recovery
string
Comma-separated recovery values:
recovered
,
unrecovered
,
unknown
. See
Recovery
.
--query
string
Words in the title or summary, up to 200 characters.
--seen-after
string
Count only runs created at or after this ISO 8601 date-time.
--sort
impact
,
runs
,
recent
,
new
impact
See
Sort
.
--limit
integer
25
Results per page, up to 100 (default 25).
--cursor
string
The
nextCursor
from the previous page.
--experiment-id
to
--friction-id
are the
run scope flags
. Also takes the
global flags
.
Examples
List the frictions to fix in your product that agents never got past:
obss
frictions
list
--fix-in
product
--recovery
unrecovered
List one experiment’s frictions, most runs first, as JSON:
obss
frictions
list
--experiment-id
exp_8f2c41d0
--sort
runs
--output
json
List the frictions of one task version’s runs:
obss
frictions
list
--task-version-id
tskver_3a91c7e2
List the frictions of the runs that had one MCP server, on one machine:
obss
frictions
list
--tool-id
mcp_2e8b6f13
--machine-id
env_90c4d1a7
List the frictions that occur with another friction:
obss
frictions
list
--friction-id
frc_7d20e6b4
Result fields
With
--output json
, the result has
scope
(each record that your scope flags named, with its
kind
,
id
, current
name
, and
dashboardUrl
),
totalFrictions
,
hasMore
,
nextCursor
,
models
(the
Insights model
and
Experiment insights model
that found and grouped the frictions), and
coverage
. Each friction has these fields:
Field
Meaning
frictionId
The
frc_
ID. The ID and title never change.
title
,
summary
The problem
family
The cause. See
Family
.
whoActs
The family’s group:
product
(
Product
,
Docs & skills
),
agent
(
Agent software
,
Agent reasoning
), or
setup
(
Machine
,
Task quality
). For where to fix, read
fixIn
.
fixIn
Where to fix it. See
Where to fix
.
fixSurface
The place the fix names, by its current name: a tool, treatment, or custom agent, or
API or docs
,
Task
, or
Machine
.
null
when no checked place passed.
concentration
Where it happens most, by
agent
and by
treatment
, with counts and a ready
sentence
origin
insights
, or
infra
for a run that failed before the agent answered
runs
,
unrecoveredRuns
Runs in scope with the friction, and the ones the agent never got past
tasks
,
experiments
How many tasks and experiments it occurred in
firstSeenAt
,
lastSeenAt
When it was first and last seen
dashboardUrl
The friction’s page in the dashboard
coverage
tells an empty result from an incomplete one:
Field
Meaning
runs
Runs in scope
insightsOffRuns
Runs with Insights off. Only frictions from runs that failed before the agent answered can show for them.
unreviewedRuns
Runs with Insights on that Insights hasn’t reviewed yet or couldn’t review. Their frictions aren’t listed.
ungroupedRuns
Runs whose frictions Insights found but has not grouped yet
obssErrorRuns
Runs an Obss error stopped before the agent answered. They aren’t frictions:
launch again
.
Notes
A friction is listed when one of its runs matches every filter. It counts each run once, however often the agent hit it in that run.
totalFrictions
counts matches across all pages. Page with
--cursor
while
hasMore
is true.
A scope ID the project doesn’t have fails with
scope_not_found
, not an empty list.
With
--friction-id
, the list shows the frictions that occur in the same runs.
An empty or short list isn’t proof that the runs went well. Check
coverage
for runs that Insights hasn’t reviewed or grouped yet.
obss frictions get
Read one friction: what goes wrong, why it matters, the suggested fix and where to make it, where it happens most, and its most recent runs.
obss
frictions
get
<
friction-i
d
>
[flags]
Plugin (MCP) tool:
get_friction
Arguments
Argument
Description
<friction-id>
Required. The friction’s
frc_
ID.
Flags
Flag
Type
Default
Description
--experiment-id
string
Runs of this
exp_
experiment.
--schedule-id
string
Runs of the experiments this
sch_
schedule launched.
--task-id
string
Runs of this
tsk_
task, in any version.
--task-version-id
string
Runs of this
tskver_
task version.
--treatment-id
string
Runs of this
trt_
treatment (toolset).
--tool-id
string
Runs whose treatment had this skill, MCP server, CLI, or SDK (
skl_
,
mcp_
,
cli_
,
sdk_
), in any version.
--tool-version-id
string
Runs whose treatment had this tool version (
sklver_
,
mcpver_
,
cliver_
,
sdkver_
).
--file-id
string
Runs whose task had this
fld_
file.
--machine-id
string
Runs whose task ran on this
env_
machine.
--agent-id
string
Runs of this agent key, such as
claude-code
, with any model.
--agent-model-id
string
Runs of this
agm_
agent and model.
These are the
run scope flags
except
--friction-id
. Also takes the
global flags
.
Examples
Read one friction across the project:
obss
frictions
get
frc_7d20e6b4
Read the same friction, counted over one experiment’s runs:
obss
frictions
get
frc_7d20e6b4
--experiment-id
exp_8f2c41d0
--output
json
List every run where the friction occurred:
obss
runs
list
--friction-id
frc_7d20e6b4
Result fields
With
--output json
, the result has
scope
and the friction. The friction has the fields of
obss frictions list
(
frictionId
,
title
,
summary
,
family
,
whoActs
,
fixIn
,
fixSurface
,
concentration
,
origin
,
runs
,
unrecoveredRuns
,
tasks
,
experiments
,
firstSeenAt
,
lastSeenAt
, and
dashboardUrl
), plus these:
Field
Meaning
impact
Why it matters
suggestedFix
What to change at
fixSurface
.
null
for
agent_behavior
, or when no wording passed its check.
agentNote
One observed sentence on what the agent did, beside a product or setup fix. Never an instruction. Otherwise
null
.
byTreatment
,
byAgent
The rate of runs with the friction per treatment and per agent
recentOccurrences
Up to ten recent runs, each with its recovery, cited steps, and quotes
models
The
Insights model
and
Experiment insights model
that found and grouped it, each with the runs it covered
Notes
recentOccurrences
holds up to ten of the friction’s
runs
. To list them all, use
obss runs list --friction-id
with the same scope flags.
concentration
compares agents and treatments only within an experiment that ran more than one of them. It reports counts, never a cause.
Where to fix
fixIn
says where your team can fix the friction.
--fix-in
filters on these keys.
Key
Label
The suggested fix names
product
Product
A tool in the treatment (an MCP server, CLI, SDK, or skill), or the product’s API, errors, or docs
agent
Custom agent
Your organization’s
custom agent
: its instructions, tools, or code
setup
Setup
The treatment (which tools it gives the agent), the task text or its checks, or the machine
agent_behavior
Agent behavior
No change: the cause is the agent’s behavior.
suggestedFix
is
null
.
Family
Each friction has one family, which names its cause.
--family
filters on these keys.
Key
Label
What it means
product_gap
Product
The product’s API, SDK, or CLI rejected valid usage, returned wrong results, or contradicted its own schema.
docs_gap
Docs & skills
Docs or skill files were missing, wrong, incomplete, or misleading for the task.
agent_harness_gap
Agent software
The agent’s own software failed, for example a broken tool, a tool error, a failed install, or a crash.
agent_reasoning_gap
Agent reasoning
The agent made a wrong call, for example bad assumptions, a misread task, dead ends, backtracking, or sloppy output.
environment_gap
Machine
The machine failed the agent, for example with missing environment variables or keys, or broken dependencies.
task_quality_gap
Task quality
The task or its grading was at fault, for example an ambiguous task, a wrong check, or evidence that was not saved or read correctly.
Check
Machine
and
Task quality
frictions before you trust the results: they can make them unreliable.
Recovery
For each run with the friction, Insights records whether the agent got past it.
--recovery
filters on these keys.
Key
Label
Meaning
recovered
Recovered
The agent course-corrected and finished the task.
unrecovered
Unrecovered
The agent never recovered from this friction.
unknown
Unknown
Insights could not tell whether the agent recovered.
Sort
Value
Dashboard order
What comes first
impact
Unrecovered runs
(default)
The most runs the agent never got past, then the most runs, then the most recently seen
runs
Runs
The most runs
recent
Last seen
The most recently seen
new
First seen
The newest friction, by when it was first seen
Next steps
Frictions
How frictions are found, grouped, and ranked.
Find and fix frictions
Work from the top friction to a measured fix.
obss runs and results
List the runs of a friction and read their traces.
obss evals and insights
Start Insights to find frictions.
runs and results
evals and insights
Powered by
This documentation is built and hosted on Mintlify, a developer documentation platform