Home

agent-kit docs

How the kit works now. The same pages are published on the GitHub wiki.

• Package layout and pinning: the workspace, what each package holds, where it came from, how consumers pin a tag and how to release.
• agent_kit_core: chat view models, the backend port, the event reducer and the scripted fake backend (pure Dart).
• Backend mapping: each kit event and command against the BubblePaw SDK (layers 1 and 2) and Scratch's agent gateway, with the gaps.
• agent_kit and the gallery: the Flutter widget package, BbTheme roles, size classes, StatusMark, the gallery app, how to add a widget with its golden and how to view the CI shots.
• Icon and README assets: how the icon, lockup and README shots are built and refreshed.

agent-kit is a dependency of BubblePaw Desktop (agent_kit, agent_kit_core, agent_kit_bubblepaw) and of Scratch (agent_kit, agent_kit_core, for its chat outline and dev pane). Both read it from their pubspec.yaml.

Component sheets

One sheet per public widget, grouped by the folder under packages/agent_kit/lib/src/. Each has light and dark screenshots of its states, taken from the gallery's golden tests (apps/gallery/test/component_shots_test.dart), its parameters, the BbTheme roles it reads, size-class behaviour, accessibility and the tests that cover it. shared/ holds internal helpers and has no sheets. To add one, see "Adding a widget" in agent_kit and the gallery.

theme

• BbTheme: The one ThemeExtension of the kit: colour roles, status styles, radii, motion, type scale and layout tokens, with BbThemeScope to install it.
• SizeClassBuilder: Measures its own width and gives its builder the SizeClass for that width, from the theme's thresholds; this sheet also covers SizeClass .

status

• StatusMark: The one widget that draws a status: a small mark and a label, in a dot form for list rows and meta lines, or a pill form for headers.

transcript

• ActivityGroupView: One summary line for a run of agent work ("Searched 1× · Read 2 files · Ran 1 command · Worked 48s") that opens into evidence rows.
• AssistantProse: The assistant's message text, drawn by a MarkdownRenderer.
• ChildQuestionRow: A question a child agent asked its parent agent, shown as a quiet inline row with the child's suggested options, its status.
• CodeBlock: A fenced code block: mono text on a surface2 well that scrolls sideways.
• DiffView: A file diff: one row per line, added lines on the constructive tint, removed lines on the danger tint with the text struck through, context on the surface-2 well.
• ExecOutput: Tool output: a mono block clamped to 12 lines with a fade, and a footer with the size, the exit status, "Show all N lines" and "Open full output".
• FileEditRow: One file change: "Edited usage/mod.rs +N −N", with "Review diff", "Open" and "Undo" actions, and the diff opening under it.
• PlanChecklist: The agent's plan as one line, "Plan 2/5", that opens into its steps.
• ReturnLine: The line that closes a child agent's work: "Map UsageState transitions returned", with a status pill and an Open action for the child's chat.
• SystemLineView: A system line: small, centred, faint text such as "Context compacted".
• TranscriptList: The scrolling column of a chat's transcript.
• UserBubble: The user's message: context chips above a right-aligned text bubble, with an optional "Rewind from here" action.

composer

• AgentComposer: The message field and send bar at the foot of a chat.
• ApprovalBar: The bar above the composer that asks the user to approve or deny a tool call, with the sibling ApprovalKeyPane (the focus marker that decides which bar answers the keys).
• QuestionAnswerLines: The resolved question as it reads in the transcript: one line per question, with the answer or "Skipped".
• QuestionPrompt: The card above the composer that asks the user one or more questions and sends the answers.
• QueuedRow: One queued message above the composer, with Send now, Edit and Remove, and an inline edit field.

chrome

• ChatHeader: The bar at the top of a chat: the session's tile and title, its status pill, the branch, the context meter, the workspace toggle and the session menu.
• ContextMeter: A bar and a percentage that show how much of the model's context window the chat uses.
• CrewLedger: A list of the child agents and background jobs, with their status and a Cancel action for running agents.
• CrewStrip: A horizontal strip of chips, one per child agent or background job, that opens them.
• RailLayout: The layout that places the session rail beside the chat: a column at medium and expanded widths, a sliding screen at compact width.
• SessionRail: The session list: the workspace header, the chats grouped under labelled headings, and a footer.
• UsageByModel: A list of the models used in a chat, with each model's share of the tokens and a total.

context

• CompactionMarker: One quiet line in the assistant turn where a compaction was applied, was running, or failed.
• ContextMeterBar: The context meter of the Context pane: the token count against the window, a stacked bar of the context's parts, and a legend.
• ContextPane: The Context pane: what the model sees now, the original history and the compactions over time, under the context meter.

history

• HistoryBoundary: The hairline where full messages begin, below the compacted history: an arrow, "Full messages from here" and the number of the first message shown in full.
• HistoryChapterCard: A closed chapter of compacted history: a card whose face is the chapter summary, which opens to its episode cards.
• HistoryCurrentChapter: The open chapter of compacted history: a plain group header over its episode cards.
• HistoryEpisodeCard: One episode of compacted history: a header line, the title and a gist.
• HistoryLegacyCard: A summary from before chapters and episodes: the title (when there is one), the summary, the start and end times and the message count.

outline

• OutlineChapterCard: A closed chapter in the outline: a folding card with the chapter's title, one line on its face (the decision, or a gist).
• OutlineChapterHeading: The heading of a chapter whose messages show in the outline: an open chapter, or a closed one the reader has unfolded.
• OutlineList: The outlined transcript as a list: the rows of an OutlineController's layout, drawn in an AnchoredList.
• OutlineSectionDivider: A section's divider in the outline: a short coloured bar, the section title, a dashed rule and an optional menu button.
• OutlineWhereStrip: The where-am-I strip over the outline: a dot in the chapter's colour, the chapter title, the section after a "›", and a "Contents ▾" label.

workspace

• AgentWorkspace: The tiling pane area beside the chat: a split tree of panes with dividers, tabs, maximise and close on each pane, collapse to edge tabs, drag to dock.

compositions

• AgentChatPane: One chat on an AgentBackend, with its header, crew strip, transcript and dock (approvals, question, queued inputs, error line, composer).
• AgentContextPane: The Context pane of one chat.
• AgentWorkbench: The whole agent app on one AgentBackend: the session rail, the chat pane, the crew ledger or strip, and an optional workspace beside the chat .

providers

• ProviderSettings: The providers section of a host's settings, with the default model, each provider's key status and models, and Make default: ProviderList draws a ProviderSetup.

---

Generated from docs/README.md. Edit the file there; changes made on the wiki are overwritten.