xenia_report
Analyze coding agent performance across tasks, failures, repeats, and tool usage. Identify recurring failures and inefficiencies to improve environment and instructions.
Instructions
How coding agents have been getting on with their work on this machine. One record, six views of it — choose what a row should be with 'view':
tasks one unit of work an agent named for itself, and whether it got there: achieved, partial, failed, abandoned or no_action. The outcome is read off the calls made under the task, never off the agent's claim about it; where the two disagree 'overstated' is 1 and 'declared' is what the agent said. Start here. instructions the same question one level up: one thing the user asked for, and how it turned out. The only view that carries whole prompts, which is why the rest carry a 'goal_id' — pass one back as 'goal_id' for the full text of that instruction. failures one kind of work that keeps failing, worst first, grouped across sessions. 'repos' names the checkouts it failed in, because that is where a fix goes; 'previously' is the same count over the window before this one, so a row failing 8 times against 0 is new and one against 12 is already getting better. 'recovered' is how often a later call put it right; many failures and few recoveries is a gap in the environment or the instructions, and the most actionable row here. Refusals split by who did the refusing: 'refused_by_rule' is a hook or a permission rule, and the reason is in 'example_error' — a config or code fix; 'declined_by_user' is a person saying no at the prompt, which is not yours to change. Pass 'example_action_id' to xenia_trace. repeats one piece of work a session did again minutes after it had already succeeded. This is the waste 'failures' cannot show, since none of it failed. Cost it in 'repeated_bytes' rather than 'repeated_ms': redoing work is rarely slow, but every repeat puts its whole reply back into a context. tools one tool, broker, host, repo or signature, with calls, failure rate, latency and reply bytes. Ask this rather than totalling rows yourself; order by 'total_bytes' for what floods a context rather than what takes time. disk one file (or repo, tool, session) with what was written to it, how often it was rewritten, and how much of that hashed to what was already there — 'unchanged' is bytes that reached the drive and changed nothing.
Rows come back under 'rows'. The tasks view also returns 'instructions', the text of each instruction its rows sat under, keyed by 'goal_id' — one entry per instruction rather than the same sentence repeated down every row. 'since', 'repo' and 'limit' apply to every view; each other parameter names the views that read it, and passing one to a view that does not is an error rather than a filter that quietly does nothing. For the individual calls behind any row, take its 'signature' to xenia_calls.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| via | No | [repeats tools] Which broker carried the call: an MCP server name, or 'direct' for the shell. Globs, so 'acme-*' covers every server at one site. | |
| kind | No | [repeats tools] Restrict to one kind of action. | |
| path | No | [disk] One absolute path, exactly or as a glob: '/home/*/.cache/*'. | |
| repo | No | Limit to one repository by name. Agent work outside any checkout is filed under 'general'. | |
| tool | No | [repeats tools disk] Tool name, exactly or as a glob: 'Bash', 'mcp__acme-ssh__shell', 'mcp__acme*'. | |
| view | Yes | Which of the six above. | |
| agent | No | [tasks repeats tools disk] Which runtime: claude or codex. | |
| limit | No | Maximum rows (default 200, capped at 500). | |
| order | No | [repeats tools disk] Sort by. For tools: calls, failure_rate, p95_bytes, p95_ms, total_bytes, total_ms (default 'total_ms', the time the group actually cost). For disk: bytes_written, rewrites, unchanged, wasted_bytes, writes (default 'wasted_bytes'; use 'writes' when sizes are unknown). For repeats: repeated_bytes, repeated_ms, repeats (default 'repeats'; order by 'repeated_bytes' for what the redoing cost a context, which is where the cost of this view lands — redone work is rarely slow). | |
| since | No | Window to look back over: '24h', '7d', '30m', or a date like '2026-07-01'. Omit for all time. | |
| search | No | [tasks] Substring match over the task label and the instruction it sat under. | |
| source | No | [tasks] How the task was identified: the agent's plan, the description on a call, or the shape of the work. | |
| status | No | [tasks instructions tools] Restrict to one outcome. For tasks and instructions: open, achieved, partial, failed, no_action, abandoned. For tools: started, ok, error, blocked, unanswered — where 'blocked' is a call something refused and 'unanswered' is one nobody answered before the session ended, which is counted as a failure nowhere. | |
| channel | No | [repeats tools] What kind of far side it reached: http, ssh, git, mcp, db, package, cloud, raw. | |
| goal_id | No | [instructions] One instruction, in full, by the id the other views return. | |
| session | No | [repeats tools disk] One agent run, by session id. Worth using on a machine running several agents at once, where a timeline is otherwise several agents interleaved. | |
| group_by | No | [tools disk] What one row covers. For tools: agent, channel, environment, host, intent, kind, repo, signature, status, tool, via (default 'tool'; a call with no such property — a file edit has no host — groups under null). For disk: agent, path, repo, session, tool (default 'path'). | |
| min_count | No | [failures repeats tools disk] Drop rows below this many failures, repeats, calls or writes. Defaults to 2 for failures — one failure is an incident rather than a pattern — and to 1 elsewhere, so nothing is hidden unless you ask. | |
| signature | No | [tools] The normalised identity of the work, as returned by the failures, repeats and tools views. This is how you drill from one of those rows into the calls behind it. | |
| environment | No | [tools] Target environment of a remote call, e.g. production. | |
| within_minutes | No | [repeats] How close together two calls have to be to count as a repeat (default 10). Widen it for a slow-moving session; a large window starts counting honest re-runs. | |
| overstated_only | No | [tasks] Only tasks the agent called finished that the calls under them say were not. |