Generative UI
Ask the agent for a report, a dashboard, or an interactive summary of structured results — “show revenue for the last 12 months against budget”, “summarise that test run”, “list the files you changed” — and it can answer with a live view inside the chat instead of a wall of text.
How it works
Section titled “How it works”The agent decides what to show. Kanna decides how it renders and what actually happens:
- The agent writes a small JSON description in a
```kanna-uiblock. It names components from Kanna’s catalog — metric tiles, charts, statements, tables, test results, file lists — never code, colours or chart-library options. - Kanna validates that description before anything renders. A view with an unknown
component, a wrong setting, or an action Kanna does not offer is shown as Unable to
show this view and nothing from it runs. On Claude the agent checks its views with
mcp__kanna__validate_uibefore it answers; Codex is not given Kanna’s tools, so it cannot. On both providers, if a broken view slips through, Kanna asks the agent once to fix it at the end of the turn. - Views render the same on Claude and Codex, stay in the chat history, and render again when you reopen the chat.
Where the data comes from
Section titled “Where the data comes from”The agent never pastes large data into a view. Each view declares its datasets and Kanna fetches them:
| Source | Use it for | What Kanna enforces |
|---|---|---|
| Inline | the default for any data the agent already holds — a query result, numbers it computed, rows you gave it. Written as columns plus rows, or as one object per row | at most 500 rows and 64 KB |
| File | a CSV or JSON file that already exists in the chat’s working directory | the path must stay inside the working directory (symlinks included) and pass the chat’s read-path rules |
| MCP | a tool on one of your configured MCP servers, such as a BI query | the tool must declare itself read-only, or you click Allow for this chat first; the server’s own credentials decide what data you can see |
File views refresh on their own when the file changes, without asking the agent to redraw anything.
Exploring without the agent
Section titled “Exploring without the agent”Changing the period or comparison, drilling into a chart point, switching a chart to its table, and expanding statement groups all run inside Kanna — no tokens, no waiting. Every chart has a Table view with the exact numbers, and in that view each row you can drill into is a button, so the whole report works from the keyboard.
Diagrams
Section titled “Diagrams”Ask the agent to “draw how a request flows”, “map the modules this touches”, or “show the pipeline with each step’s status”, and it can answer with a FlowDiagram: steps and the connections between them, optionally grouped, each step marked as a start, end, process, decision, store or external system and carrying a status such as passed or running.
- The agent never places anything. It names the steps and connections, and Kanna lays the diagram out, picking left-to-right or top-to-bottom to fit the chat, and routes each connection around the steps rather than through them.
- A connection is either static — a relationship that simply exists, such as a dependency or a decision branch — or flow, meaning work is moving along it right now. Only flow connections animate, with beads travelling toward the next step. With your system’s reduce-motion setting on they hold still, and stay visibly different from static ones. A dashed connection means optional or conditional.
- Click a step to see its details. Open file jumps to the code it names, and Ask agent sends a question about that step that includes the steps before and after it.
- The diagram is read-only: you can pan and zoom with the controls, but the mouse wheel keeps scrolling the chat. Outline reads the same diagram as a numbered list in flow order, and is the way to use it from the keyboard.
For a picture you only need to look at, the agent still writes a mermaid diagram.
Asking the agent about what you see
Section titled “Asking the agent about what you see”Buttons such as Explain variance or Fix on a failing test hand the question back to the agent. Kanna shows you the message first and sends it only when you click Send. The message carries the view’s current numbers and the dataset it came from, so the agent starts from facts rather than from button text; in your chat it appears as your question plus a small context chip.
Shared links
Section titled “Shared links”A shared chat shows views read-only, and agent actions are hidden. When you create the link, Kanna loads each file and MCP dataset a view uses, under the chat’s own permissions, and freezes the rows into the snapshot. Period, comparison and drill-down still work on that frozen data, but it never refreshes. A dataset is left out, and its view says the data is unavailable, when:
- its MCP tool is not read-only and you have not clicked Allow for this chat;
- the file is outside the working directory or blocked by the chat’s read-path rules;
- the rows come to more than 8 MB.
Turning it off
Section titled “Turning it off”Set KANNA_GENUI=disabled to stop teaching the agent the format and to turn off the
end-of-turn check. Views already in a transcript keep rendering.