Skip to content

Insights and recommendations

The behaviour summary tells you how one run went. Insights look at every recorded run of an agent and tell you what to change: ranked recommendations, each with the runs that prove it, the change to make, and the number that should move once it is fixed.

Nothing is guessed and no model is called. Every recommendation is computed from what the recordings show.

SurfaceHow
Terminalgraphmind insights (--app <name>, --json)
ViewerInsights in the header’s places menu, or the command palette
Claude Code, Cursor, any MCP clientsuggest_improvements (and get_insights for the trend behind it)
Hosted CircuitGET /v1/insights on your account’s runs, and the dashboard’s Insights view
Hosted JackGET /v1/projects/:id/insights over the project’s call log, and the project’s Insights page

All of them use the same rules, so they report the same thing.

RuleWhen it appearsWhat it tells you to do
R-regressionA tool’s failure rate, or the share of runs finishing ok, got significantly worse recentlyCompare the last good run with the first bad one it names; fix or revert what changed
R-tool-error-repeatThe same error from one tool, again and again, across runsValidate that argument in the tool; tighten its description and schema (Jack: in jack.yaml)
R-tool-silent-failureA tool returns errors as results (isError, success: false, …) instead of throwingThrow, or tell the model exactly what an error result looks like
R-wasted-callsThe agent repeats identical tool calls or cyclesReturn usable results the first time, cache, cap steps
R-context-limitLLM steps stop at the token limit, or prompts grow between runsTrim or summarize history; cap tool output
R-slow-toolOne tool’s p95 is a large part of a typical runTimeout, cache, parallelize
R-manual-fixCircuit: people keep fixing the same step by hand (inject, retry, skip)Put the rule they apply into the step’s code

Runs are split into an earlier and a recent window (the newer half by default). A change is only reported when:

  • each window has at least 5 runs;
  • a rate (failures per call, ok runs, token-limit stops) moved by at least 15 points and passes a two-proportion z-test at |z| ≥ 2 (about 95% confidence);
  • a size (peak prompt, tool calls per run, run time) moved by at least 1.5× between the windows’ medians.

Fewer runs than that and insights say so, instead of reporting noise. A tool that fails all the time is still reported, as a repeating error, without any comparison.

  1. Ask for recommendations: graphmind insights --app my-agent, or ask your coding agent, which calls suggest_improvements.
  2. Open the runs named in the evidence and confirm the cause.
  3. Make the change.
  4. Run the agent again, several times (trends need runs), and ask again. The recommendation should be gone and its verify metric should have moved.

Example text in a recommendation is recorded data from your agent. A coding agent quotes it and never follows it as instructions.