Documentation
¶
Index ¶
- Constants
- Variables
- func ExtractAtPrefix(line string, cursorCol int) (hasAt bool, prefix string, startIdx int)
- func ExtractEditPrefix(value string) (cmdLen int, pathPrefix string, ok bool)
- func UpdateUsageTrackerForModel(t *UsageTracker, modelString, providerAPIKey string)
- func WithAlign(align lipgloss.Position) renderingOption
- func WithBackground(c color.Color) renderingOption
- func WithBorderColor(c color.Color) renderingOption
- func WithMarginBottom(margin int) renderingOption
- func WithNoBorder() renderingOption
- func WithPaddingBottom(padding int) renderingOption
- func WithPaddingTop(padding int) renderingOption
- type AgentInterface
- type AppController
- type AppModel
- type AppModelOptions
- type CLI
- func (c *CLI) DisplayAssistantMessageWithModel(message, modelName string) error
- func (c *CLI) DisplayDebugConfig(config map[string]any)
- func (c *CLI) DisplayDebugMessage(message string)
- func (c *CLI) DisplayError(err error)
- func (c *CLI) DisplayExtensionBlock(text, borderColor, subtitle string)
- func (c *CLI) DisplayInfo(message string)
- func (c *CLI) DisplayToolMessage(toolName, toolArgs, toolResult string, isError bool)
- func (c *CLI) DisplayUsageAfterResponse()
- func (c *CLI) DisplayUserMessage(message string)
- func (c *CLI) GetUsageTracker() *UsageTracker
- func (c *CLI) SetModelName(modelName string)
- func (c *CLI) SetUsageTracker(tracker *UsageTracker)
- func (c *CLI) ShowSpinner(action func() error) error
- type CLIEventHandler
- type CLISetupOptions
- type CancelTimerExpiredMsg
- type EditorInterceptor
- type EditorKeyAction
- type EditorKeyActionType
- type ExtensionCommand
- type ExtensionItem
- type FileAttachmentResult
- type FilePart
- type FileSuggestion
- type FlatNode
- type FuzzyMatch
- type ImageAttachment
- type InputComponent
- func (s *InputComponent) Clear() bool
- func (s *InputComponent) ClearPendingImages() []core.ImageAttachment
- func (s *InputComponent) Init() tea.Cmd
- func (s *InputComponent) PendingImageCount() int
- func (s *InputComponent) RenderPopupBox(termWidth, termHeight int) string
- func (s *InputComponent) SetCwd(cwd string)
- func (s *InputComponent) SetMCPResourceProvider(fn func() []FileSuggestion)
- func (s *InputComponent) Update(msg tea.Msg) (tea.Model, tea.Cmd)
- func (s *InputComponent) UpdateTheme()
- func (s *InputComponent) View() tea.View
- type InspectableItem
- type MCPPromptArgInfo
- type MCPPromptExpandResult
- type MCPPromptInfo
- type MCPPromptMessageInfo
- type MCPResourceReader
- type MarkdownThemeColors
- type MessageItem
- type MessageRenderer
- func (r *MessageRenderer) RenderAssistantMessage(content string, timestamp time.Time, modelName string) UIMessage
- func (r *MessageRenderer) RenderCustomMessage(content, label string, timestamp time.Time) UIMessage
- func (r *MessageRenderer) RenderDebugConfigMessage(config map[string]any, timestamp time.Time) UIMessage
- func (r *MessageRenderer) RenderDebugMessage(message string, timestamp time.Time) UIMessage
- func (r *MessageRenderer) RenderErrorMessage(errorMsg string, timestamp time.Time) UIMessage
- func (r *MessageRenderer) RenderExtensionBlock(text, borderColor, subtitle string) UIMessage
- func (r *MessageRenderer) RenderReasoningBlock(content string, timestamp time.Time) UIMessage
- func (r *MessageRenderer) RenderSystemMessage(content string, timestamp time.Time) UIMessage
- func (r *MessageRenderer) RenderToolMessage(toolName, toolArgs, toolResult string, isError bool) UIMessage
- func (r *MessageRenderer) RenderUserMessage(content string, timestamp time.Time) UIMessage
- func (r *MessageRenderer) SetWidth(width int)
- func (r *MessageRenderer) UpdateTheme()
- type MessageType
- type ModelEntry
- type ModelSelectedMsg
- type ModelSelectorCancelledMsg
- type ModelSelectorComponent
- type PopupItem
- type PopupList
- func (p *PopupList) Cursor() int
- func (p *PopupList) HandleKey(keyName, keyText string) PopupResult
- func (p *PopupList) IsSearching() bool
- func (p *PopupList) Items() []PopupItem
- func (p *PopupList) Render() string
- func (p *PopupList) RenderCentered(termWidth, termHeight int) string
- func (p *PopupList) Search() string
- func (p *PopupList) SelectedItem() *PopupItem
- func (p *PopupList) SetCursor(i int)
- func (p *PopupList) SetItems(items []PopupItem)
- func (p *PopupList) SetSearch(s string)
- func (p *PopupList) SetSize(width, height int)
- type PopupResult
- type Renderer
- type ScrollList
- func (s *ScrollList) AtBottom() bool
- func (s *ScrollList) AtTop() bool
- func (s *ScrollList) ClearSelection()
- func (s *ScrollList) EnsureVisible(idx int)
- func (s *ScrollList) ExtractSelectedText() string
- func (s *ScrollList) GotoBottom()
- func (s *ScrollList) GotoTop()
- func (s *ScrollList) HandleMouseDown(x, y int) bool
- func (s *ScrollList) HandleMouseDrag(x, y int) bool
- func (s *ScrollList) HandleMouseUp() bool
- func (s *ScrollList) HasSelection() bool
- func (s *ScrollList) InvalidateHeights()
- func (s *ScrollList) InvalidateItemHeight(id string)
- func (s *ScrollList) IsMouseDown() bool
- func (s *ScrollList) ItemAt(idx int) MessageItem
- func (s *ScrollList) ItemGap() int
- func (s *ScrollList) Len() int
- func (s *ScrollList) ScrollBy(lines int)
- func (s *ScrollList) ScrollPercent() float64
- func (s *ScrollList) SelectedIndex() int
- func (s *ScrollList) SetHeight(height int)
- func (s *ScrollList) SetItemGap(gap int)
- func (s *ScrollList) SetItems(items []MessageItem)
- func (s *ScrollList) SetSelectedIndex(idx int)
- func (s *ScrollList) SetSelectionFrame(label, hint string)
- func (s *ScrollList) SetWidth(width int)
- func (s *ScrollList) View() string
- type SessionDeletedMsg
- type SessionFilterMode
- type SessionScopeMode
- type SessionSelectedMsg
- type SessionSelectorCancelledMsg
- type SessionSelectorComponent
- func (ss *SessionSelectorComponent) Init() tea.Cmd
- func (ss *SessionSelectorComponent) IsActive() bool
- func (ss *SessionSelectorComponent) RenderOverlay() string
- func (ss *SessionSelectorComponent) SetCurrentPath(path string)
- func (ss *SessionSelectorComponent) Update(msg tea.Msg) (tea.Model, tea.Cmd)
- func (ss *SessionSelectorComponent) View() tea.View
- type SessionStats
- type SessionStore
- type ShellCommandMsg
- type ShellCommandResultMsg
- type ShortcutInfo
- type SkillItem
- type SlashCommand
- type Spinner
- type StatusBarEntryData
- type StreamComponent
- func (s *StreamComponent) ActivityDot() string
- func (s *StreamComponent) ActivityPhrase() string
- func (s *StreamComponent) ConsumeOverflow() string
- func (s *StreamComponent) GetRenderedContent() string
- func (s *StreamComponent) HasReasoning() bool
- func (s *StreamComponent) Init() tea.Cmd
- func (s *StreamComponent) IsSpinning() bool
- func (s *StreamComponent) Reset()
- func (s *StreamComponent) SetHeight(h int)
- func (s *StreamComponent) SetThinkingVisible(visible bool)
- func (s *StreamComponent) Update(msg tea.Msg) (tea.Model, tea.Cmd)
- func (s *StreamComponent) UpdateTheme()
- func (s *StreamComponent) View() tea.View
- type StreamingBashOutputItem
- func (m *StreamingBashOutputItem) AppendStderr(line string)
- func (m *StreamingBashOutputItem) AppendStdout(line string)
- func (m *StreamingBashOutputItem) Height() int
- func (m *StreamingBashOutputItem) ID() string
- func (m *StreamingBashOutputItem) MarkComplete()
- func (m *StreamingBashOutputItem) RawContent() string
- func (m *StreamingBashOutputItem) Render(width int) string
- func (m *StreamingBashOutputItem) Role() string
- type StreamingMessageItem
- func (s *StreamingMessageItem) AppendChunk(chunk string)
- func (s *StreamingMessageItem) Height() int
- func (s *StreamingMessageItem) ID() string
- func (s *StreamingMessageItem) MarkComplete()
- func (s *StreamingMessageItem) RawContent() string
- func (s *StreamingMessageItem) Render(width int) string
- func (s *StreamingMessageItem) Role() string
- type SubmitMsg
- type TextMessageItem
- func (m *TextMessageItem) Height() int
- func (m *TextMessageItem) ID() string
- func (m *TextMessageItem) Invalidate()
- func (m *TextMessageItem) RawContent() string
- func (m *TextMessageItem) Render(width int) string
- func (m *TextMessageItem) Role() string
- func (m *TextMessageItem) ToolCall() (ToolCallInfo, bool)
- func (m *TextMessageItem) WithToolCall(info ToolCallInfo) *TextMessageItem
- type Theme
- type ToolCallInfo
- type ToolInspectable
- type ToolRendererData
- type TreeCancelledMsg
- type TreeFilterMode
- type TreeNodeSelectedMsg
- type TreeSelectorComponent
- type UIMessage
- type UIVisibility
- type UsageStats
- type UsageTracker
- func (ut *UsageTracker) EstimateAndUpdateUsage(inputText, outputText string)
- func (ut *UsageTracker) GetSessionStats() SessionStats
- func (ut *UsageTracker) GetTurnStats() *UsageStats
- func (ut *UsageTracker) IsOAuth() bool
- func (ut *UsageTracker) RenderUsageInfo() string
- func (ut *UsageTracker) Reset()
- func (ut *UsageTracker) SetContextTokens(tokens int)
- func (ut *UsageTracker) SetUsageUnreported(unreported bool)
- func (ut *UsageTracker) SetWidth(width int)
- func (ut *UsageTracker) StartTurn()
- func (ut *UsageTracker) UpdateModelInfo(modelInfo *models.ModelInfo, provider string, isOAuth bool)
- func (ut *UsageTracker) UpdateUsage(inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens int)
- type WidgetData
Constants ¶
const FrameClockFPS = 30
FrameClockFPS is the rate the shared animation clock ticks at.
30 is the ceiling worth paying for: it is the rate at which a colour gradient sweeping across a cell reads as motion rather than as a sequence of steps, and it is already the rate the logo animation was tuned against. Animations that want to run slower subdivide it rather than asking for a second clock — see frameTickMsg.due.
Variables ¶
var ( LoadThemePreference = prefs.LoadThemePreference SaveThemePreference = prefs.SaveThemePreference LoadModelPreference = prefs.LoadModelPreference SaveModelPreference = prefs.SaveModelPreference LoadThinkingLevelPreference = prefs.LoadThinkingLevelPreference SaveThinkingLevelPreference = prefs.SaveThinkingLevelPreference )
Re-export from prefs package
var ( GetTheme = style.GetTheme SetTheme = style.SetTheme DefaultTheme = style.DefaultTheme ApplyTheme = style.ApplyTheme ApplyThemeWithoutSave = style.ApplyThemeWithoutSave ListThemes = style.ListThemes RegisterThemeFromConfig = style.RegisterThemeFromConfig KitBanner = style.KitBanner AdaptiveColor = style.AdaptiveColor IsDarkBackground = style.IsDarkBackground SyntaxStyle = style.SyntaxStyle // SetTerminalCapabilities and ResolveTerminalCapabilities let a frontend // control per-terminal styling inputs instead of relying on a process-global // probe. See internal/ui/style. SetTerminalCapabilities = style.SetTerminalCapabilities ResolveTerminalCapabilities = style.ResolveTerminalCapabilities )
var ProcessFileAttachments = fileutil.ProcessFileAttachments
Re-export functions and types from fileutil package
Functions ¶
func ExtractAtPrefix ¶ added in v0.4.0
ExtractAtPrefix checks the current line for an @-file trigger at cursorCol. It returns:
- hasAt: true if a valid @ trigger was found
- prefix: the text after @ (possibly empty) that the user has typed so far
- startIdx: byte offset of the @ character in the line
The @ must appear at the start of the line or after whitespace. Quoted paths are supported: @"path with spaces" — the returned prefix strips quotes.
func ExtractEditPrefix ¶ added in v0.74.0
ExtractEditPrefix detects when the input value is a single-line /edit (or alias) invocation and returns the path-portion the user has typed so far.
Returns:
- cmdLen: byte offset where the path argument begins (i.e. length of the matched command token, including its trailing space)
- pathPrefix: text the user has typed after the command token
- ok: true when the value matches one of the /edit triggers
Multi-line values never match — /edit only makes sense as a single line.
func UpdateUsageTrackerForModel ¶ added in v0.75.1
func UpdateUsageTrackerForModel(t *UsageTracker, modelString, providerAPIKey string)
UpdateUsageTrackerForModel refreshes an existing tracker after a model switch so token counting and cost reporting use the new model's metadata. No-op for a nil tracker or untrackable models (unknown/ollama).
func WithAlign ¶
WithAlign returns a renderingOption that sets the horizontal alignment of the block content within its container. The align parameter accepts lipgloss.Left, lipgloss.Center, or lipgloss.Right positions.
func WithBackground ¶
WithBackground returns a renderingOption that sets a background color for the entire block, including the padded region.
func WithBorderColor ¶
WithBorderColor returns a renderingOption that sets the border color for the block. The color parameter uses lipgloss.AdaptiveColor to support both light and dark terminal themes automatically.
func WithMarginBottom ¶
func WithMarginBottom(margin int) renderingOption
WithMarginBottom returns a renderingOption that sets the bottom margin for the block. The margin is specified in number of lines and adds vertical space below the block.
func WithNoBorder ¶
func WithNoBorder() renderingOption
WithNoBorder returns a renderingOption that disables all borders on the block, rendering content with only padding.
func WithPaddingBottom ¶
func WithPaddingBottom(padding int) renderingOption
WithPaddingBottom returns a renderingOption that sets the bottom padding for the block content. The padding is specified in number of lines and adds vertical space between the content and the bottom border.
func WithPaddingTop ¶
func WithPaddingTop(padding int) renderingOption
WithPaddingTop returns a renderingOption that sets the top padding for the block content. The padding is specified in number of lines and adds vertical space between the top border and the content.
Types ¶
type AgentInterface ¶
type AgentInterface interface {
GetLoadingMessage() string
GetTools() []any // Using any to avoid importing tool types
GetLoadedServerNames() []string // Add this method for debug config
GetMCPToolCount() int // Tools loaded from external MCP servers
GetExtensionToolCount() int // Tools registered by extensions
}
AgentInterface defines the minimal interface required from the agent package to avoid circular dependencies while still accessing necessary agent functionality.
type AppController ¶
type AppController interface {
// Run queues or immediately starts a new agent step with the given prompt.
// Returns the current queue depth: 0 means the prompt started immediately
// (or the app is closed), >0 means it was queued. The caller must update
// UI state (e.g. queueCount) based on the return value — Run does NOT
// send events to the program to avoid deadlocking when called from
// within Update().
Run(prompt string) int
// CancelCurrentStep cancels any in-progress agent step.
CancelCurrentStep()
// QueueLength returns the number of prompts currently waiting in the queue.
QueueLength() int
// ClearQueue discards all queued prompts. The caller must update UI state
// (e.g. queueCount) — ClearQueue does NOT send events to the program to
// avoid deadlocking when called from within Update().
ClearQueue()
// ClearMessages clears the conversation history.
ClearMessages()
// ReloadMessagesFromTree clears the in-memory message store and reloads
// it from the tree session's current branch. Unlike ClearMessages, this
// does NOT reset the tree session's leaf pointer. Used after Branch() to
// sync the store with the new branch position.
ReloadMessagesFromTree()
// CompactConversation summarises older messages to free context space.
// Runs asynchronously; results are delivered via CompactCompleteEvent or
// CompactErrorEvent sent through the registered tea.Program. Returns an
// error synchronously if compaction cannot be started (e.g. agent is busy).
// customInstructions is optional text appended to the summary prompt.
CompactConversation(customInstructions string) error
// SessionSnapshot returns a value snapshot of the active tree session's
// metadata (id, name, file path, counts, current leaf). ok is false when
// no tree session is active. Callers re-read it whenever they need
// current values rather than caching it.
SessionSnapshot() (app.SessionSnapshot, bool)
// SessionTree returns the session's entry tree projected into value
// nodes, or nil when no tree session is active. Used by /tree and /fork.
SessionTree() []app.TreeNodeView
// SessionHistory returns the conversation messages on the session's
// current branch, oldest first. Used to replay the transcript after
// resuming or forking a session.
SessionHistory() []message.Message
// SetSessionName sets the session's display name. Used by /name.
SetSessionName(name string) error
// NewSession replaces the active session with a brand new one created in
// cwd, closing the old one. Used by /new.
NewSession(cwd string) error
// ForkSession creates a new session in cwd holding the history up to
// targetID and switches to it. Used by /fork and tree-node selection.
ForkSession(cwd, targetID string) error
// ListSessions returns summaries of the sessions recorded for cwd,
// newest first. Used by the session picker.
ListSessions(cwd string) ([]app.SessionSummary, error)
// ListAllSessions returns summaries of every session across all working
// directories, newest first. Used by the session picker's "All" scope.
ListAllSessions() ([]app.SessionSummary, error)
// DeleteSession removes a session file from disk. Used by the session
// picker's delete flow.
DeleteSession(path string) error
// ExportSession copies the active session's file to dstPath, deriving a
// name when dstPath is empty, and reports the path written and byte
// count. Used by /export.
ExportSession(dstPath string) (string, int, error)
// (with a system-prompt entry spliced in) to a temporary file and returns
// its path. The caller must remove the file. Used by /share.
WriteShareableSession(systemPrompt, fallbackModelID string) (string, error)
// SendUIMessage re-injects a UI-internal message into the program's Update
// loop asynchronously. Safe to call from any goroutine. Used by extension
// command goroutines (and other async UI work) to deliver results back to
// the TUI without going through tea.Cmd (which can stall when the goroutine
// blocks on interactive prompts). The message is opaque to the app layer;
// it is not an app Event and is only understood by the UI's own Update.
SendUIMessage(tea.Msg)
// AddContextMessage adds a user-role message to the conversation history
// without triggering an LLM response. Used by the ! shell command prefix
// to inject command output into context so the LLM can reference it in
// subsequent turns.
AddContextMessage(text string)
// RunWithFiles queues a multimodal prompt (text + images) for execution.
// Behaves like Run but includes file parts (e.g. clipboard images)
// alongside the text. Returns the current queue depth (0 = started
// immediately, >0 = queued).
RunWithFiles(prompt string, files []kit.LLMFilePart) int
// Steer injects a steering message into the currently running agent
// turn. If the agent is busy, the message is delivered between steps
// (after current tool finishes, before next LLM call). If idle, the
// message starts executing immediately. Returns 0 if started
// immediately, >0 if injected/pending.
Steer(prompt string) int
// SteerWithFiles injects a steering message with optional file
// attachments (e.g. pasted images) into the currently running agent
// turn. Behaves like Steer but includes file parts alongside the text.
SteerWithFiles(prompt string, files []kit.LLMFilePart) int
// PopLastUserMessage truncates the tree session at the parent of the
// most recent user message on the current branch, syncs the in-memory
// message store, and returns that user prompt (plus any image file
// parts) so the caller can resubmit it. Used by /retry to recover from
// provider errors (overloaded, timeout) without duplicating the user
// message in context. Returns an error if the agent is busy, no tree
// session is active, or no user message exists on the current branch.
PopLastUserMessage() (string, []kit.LLMFilePart, error)
}
AppController is the interface the parent TUI model uses to interact with the app layer. It is satisfied by *app.App once that is created (TAS-4). Using an interface here keeps model.go compilable before app.App exists, and makes the parent model easily testable with a mock.
type AppModel ¶
type AppModel struct {
// contains filtered or unexported fields
}
AppModel is the root Bubble Tea model for the interactive TUI. It owns the state machine, routes events to child components, and manages the overall layout. It holds a reference to the app layer (AppController) for triggering agent work and queue operations.
Layout (alt screen):
┌─ [custom header] (optional, from extension) ──────┐ ├─ scroll region (variable height, ScrollList) ─────┤ │ (completed messages + live streaming text) │ ├─ separator line (with optional queue count) ───────┤ │ [above widgets] │ │ queued How do I fix the build? │ │ queued Also check the tests │ ├─ input region (fixed height from textarea) ────────┤ │ [below widgets] │ │ Tokens: 23.4K (12%) | Cost: $0.00 provider·model │ ├─ [custom footer] (optional, from extension) ──────┤ └────────────────────────────────────────────────────┘
The status bar is always present (1 line) to avoid layout shifts that occurred when usage info appeared/disappeared conditionally.
All messages (completed and streaming) are rendered via the ScrollList viewport. The alt screen owns the full terminal.
func NewAppModel ¶
func NewAppModel(appCtrl AppController, opts AppModelOptions) *AppModel
NewAppModel creates a new AppModel. The appCtrl parameter must not be nil. opts provides display configuration; zero values are valid (uses defaults).
To use with the concrete *app.App type, pass it directly — *app.App satisfies AppController once the app layer is implemented (TAS-4).
NewAppModel constructs all child components (InputComponent, StreamComponent) using the provided options.
func (*AppModel) AddStartupMessageToScrollList ¶ added in v0.33.0
func (m *AppModel) AddStartupMessageToScrollList()
AddStartupMessageToScrollList adds the logo and startup info as the first messages in the ScrollList. This is the only place startup information is rendered — nothing is printed to stdout.
func (*AppModel) Update ¶
Update implements tea.Model. It routes incoming messages to children and handles state transitions, then keeps the shared animation clock in step.
The clock is woken here rather than at each site that starts an animation. update has many early returns, and an animation can begin down any of them — a spinner starting on a tool event, the logo starting on a resize — so a wake call per site would be a standing invitation to miss one, and a missed one is a permanently frozen animation. Doing it once, after update has run and whatever it did has settled, makes the invariant total: if anything wants frames, the clock is running. start is idempotent, so this costs nothing on the overwhelming majority of messages, when the clock is either already running or not wanted.
func (*AppModel) View ¶
View implements tea.Model. It renders the stacked layout: stream region + separator + [queued messages] + [activity row] + input region + status bar. The status bar is always present (1 line) to avoid layout shifts; the activity row appears only while the agent is working. When the tree selector is active, it replaces the stream region.
type AppModelOptions ¶
type AppModelOptions struct {
// ModelName is the display name of the model (e.g. "claude-sonnet-4-5").
ModelName string
// ProviderName is the LLM provider (e.g. "anthropic", "openai").
// Used for the startup "Model loaded" message.
ProviderName string
// LoadingMessage is an optional informational message from the agent
// (e.g. GPU fallback info). Displayed at startup when non-empty.
LoadingMessage string
// Cwd is the working directory for @file autocomplete and path resolution.
// If empty, @file features are disabled.
Cwd string
// Width is the initial terminal width in columns.
Width int
// Height is the initial terminal height in rows.
Height int
// ServerNames holds loaded MCP server names for the /servers command.
ServerNames []string
// ToolNames holds available tool names for the /tools command.
ToolNames []string
// GetToolNames, if non-nil, returns the current tool names. Called on
// MCPToolsReadyEvent to refresh the tool list after background MCP tool
// loading completes. May be nil if dynamic tool refresh is not needed.
GetToolNames func() []string
// GetMCPToolCount, if non-nil, returns the current MCP tool count.
// Called on MCPToolsReadyEvent to refresh the startup info bar.
// May be nil if dynamic tool refresh is not needed.
GetMCPToolCount func() int
// UsageTracker provides token usage statistics for /usage and /reset-usage.
// May be nil if usage tracking is unavailable for the current model.
UsageTracker *UsageTracker
// ExtensionCommands are slash commands registered by extensions. They
// appear in autocomplete, /help, and are dispatched when submitted.
ExtensionCommands []commands.ExtensionCommand
// PromptTemplates are user-defined prompt templates loaded from ~/.kit/prompts/,
// .kit/prompts/, or explicit --prompt-template paths. They appear in autocomplete
// and are expanded when submitted (e.g., /review → full prompt text).
PromptTemplates []*prompts.PromptTemplate
// GetPromptTemplates, if non-nil, returns the current prompt templates.
// Called on ContentReloadEvent to refresh the template list after a file
// watcher detects changes. May be nil if prompt hot-reload is not needed.
GetPromptTemplates func() []*prompts.PromptTemplate
// MCPPrompts are prompts discovered from MCP servers at startup.
// They appear in autocomplete as /<server>:<prompt> commands.
MCPPrompts []MCPPromptInfo
// GetMCPPrompts, if non-nil, returns the current MCP prompts.
// Called on MCPToolsReadyEvent to refresh after background loading.
GetMCPPrompts func() []MCPPromptInfo
// ExpandMCPPrompt, if non-nil, lazily expands an MCP prompt by
// calling the MCP server's GetPrompt. Called asynchronously when the
// user invokes an MCP prompt slash command.
ExpandMCPPrompt func(serverName, promptName string, args map[string]string) (*MCPPromptExpandResult, error)
// ContextPaths lists absolute paths of loaded context files (e.g.
// AGENTS.md). Displayed in the [Context] startup section.
ContextPaths []string
// SkillItems lists loaded skills for the [Skills] startup section.
SkillItems []SkillItem
// GetSkillItems, if non-nil, returns the current skill items.
// Called on ContentReloadEvent to refresh the skill list after a file
// watcher detects changes. May be nil if skill hot-reload is not needed.
GetSkillItems func() []SkillItem
// ExtensionItems lists loaded extensions for the [Extensions] startup
// section. Each entry shows the filename of an extension that was
// discovered and loaded (global, project-local, or explicit).
ExtensionItems []ExtensionItem
// GetExtensionItems, if non-nil, returns the current extension items.
// Called on extension hot-reload to refresh the list. May be nil if no
// extensions are loaded.
GetExtensionItems func() []ExtensionItem
// MCPToolCount is the number of tools loaded from external MCP servers.
MCPToolCount int
// ExtensionToolCount is the number of tools registered by extensions.
ExtensionToolCount int
// GetWidgets returns current extension widgets for a given placement
// ("above" or "below"). Called during View() to render persistent
// extension widgets. May be nil if no extensions are loaded.
GetWidgets func(placement string) []WidgetData
// GetHeader returns the current custom header set by an extension, or
// nil if no header is active. Called during View() to render a
// persistent header above the stream region. May be nil.
GetHeader func() *WidgetData
// nil if no footer is active. Called during View() to render a
// persistent footer below the status bar. May be nil.
GetFooter func() *WidgetData
// GetToolRenderer returns the extension-provided tool renderer for a
// specific tool name, or nil if no custom renderer is registered.
// Called during tool result rendering to check for custom formatting.
// May be nil if no extensions are loaded.
GetToolRenderer func(toolName string) *ToolRendererData
// GetEditorInterceptor returns the current editor interceptor set by
// an extension, or nil if none is active. Called during Update() to
// intercept key events and during View() to wrap input rendering.
// May be nil if no extensions are loaded.
GetEditorInterceptor func() *EditorInterceptor
// GetUIVisibility returns the current UI visibility overrides set by
// an extension, or nil if none have been set (show everything).
// Called during View() to conditionally hide
// built-in chrome elements. May be nil if no extensions are loaded.
GetUIVisibility func() *UIVisibility
// GetStatusBarEntries returns extension-provided status bar entries,
// sorted by priority. Called during renderStatusBar() to inject
// extension entries alongside the built-in model/usage display.
// May be nil if no extensions are loaded.
GetStatusBarEntries func() []StatusBarEntryData
// EmitBeforeFork, if non-nil, is called before branching to a
// different session tree entry. Returns (cancelled, reason) where
// cancelled=true means the fork should be aborted. May be nil if
// no extensions are loaded.
EmitBeforeFork func(targetID string, isUserMsg bool, userText string) (bool, string)
// EmitBeforeSessionSwitch, if non-nil, is called before switching
// to a new session branch (e.g. /new, /clear). reason is the trigger
// ("new", "clear", "extension"); initialPrompt is the user prompt
// that will run as the first turn of the new session (empty when
// /new is called without arguments). Returns (cancelled, reason).
// May be nil if no extensions are loaded.
EmitBeforeSessionSwitch func(reason, initialPrompt string) (bool, string)
// GetGlobalShortcuts, if non-nil, returns extension-registered global
// keyboard shortcuts. Keys are binding strings (e.g., "ctrl+p").
// Handlers are called in a goroutine to avoid blocking the TUI event
// loop. May be nil if no extensions are loaded.
GetGlobalShortcuts func() map[string]func()
// GetShortcutList, if non-nil, returns the registered extension shortcuts
// for the /shortcuts listing, sorted for display. May be nil if no
// extensions are loaded.
GetShortcutList func() []ShortcutInfo
// GetExtensionCommands, if non-nil, returns the current extension
// commands. Called on WidgetUpdateEvent to refresh the command list
// after an extension hot-reload. May be nil if no extensions loaded.
GetExtensionCommands func() []commands.ExtensionCommand
// SetModel changes the active model at runtime. The model string uses
// "provider/model" format (e.g. "anthropic/claude-sonnet-4-5-20250929").
// Returns an error if the model string is invalid or the provider cannot
// be created. May be nil if model switching is not supported.
SetModel func(modelString string) error
// EmitModelChange fires the OnModelChange extension event after a
// successful model switch. Parameters are (newModel, previousModel, source).
// May be nil if extensions are not loaded.
EmitModelChange func(newModel, previousModel, source string)
// EmitThinkingLevelChange fires the OnThinkingLevelChange extension
// event. May be nil when no extensions are loaded.
EmitThinkingLevelChange func(newLevel, previousLevel, source string)
// EmitTerminalResize fires the OnTerminalResize extension event and
// refreshes the terminal size on the extension context. May be nil.
EmitTerminalResize func(width, height int)
// EmitTurnStateChange fires the OnTurnStateChange extension event when
// the UI enters or leaves the working state. May be nil.
EmitTurnStateChange func(state, previous string)
// SwitchSession opens a session by JSONL file path, replacing the
// active tree session and reloading messages. Called when the user
// picks a session from /resume. May be nil if session switching is
// not supported.
SwitchSession func(path string) error
// ShowSessionPicker, when true, opens the session picker immediately
// on startup (used by --resume flag).
ShowSessionPicker bool
// StartupExtensionMessages are messages captured during extension
// initialization. They are displayed in the ScrollList at startup.
StartupExtensionMessages []string
// ReloadExtensions hot-reloads all extensions from disk. Called by
// the /reload-ext command and the automatic file watcher. May be nil
// if no extensions are loaded.
ReloadExtensions func() error
// ThinkingLevel is the initial thinking level (e.g. "off", "medium").
ThinkingLevel string
// IsReasoningModel is true when the current model supports reasoning.
IsReasoningModel bool
// SetThinkingLevel changes the thinking level on the agent/provider.
SetThinkingLevel func(level string) error
// GetMCPResources, if non-nil, returns FileSuggestion entries for all
// MCP resources available from connected servers. Used by the @
// autocomplete popup to merge resource suggestions with local files.
GetMCPResources func() []FileSuggestion
// MCPResourceReader, if non-nil, reads an MCP resource by server name
// and URI. Used at submit time to resolve @mcp:server:uri tokens.
MCPResourceReader fileutil.MCPResourceReader
}
AppModelOptions holds configuration passed to NewAppModel.
type CLI ¶
type CLI struct {
// contains filtered or unexported fields
}
CLI manages the command-line interface for KIT, providing message rendering, user input handling, and display management. It handles streaming responses, tracks token usage, and manages the overall conversation flow between the user and AI assistants.
func NewCLI ¶
NewCLI creates and initializes a new CLI instance. The debug parameter enables debug message rendering. Returns an initialized CLI ready for interaction or an error if initialization fails.
func SetupCLI ¶
func SetupCLI(opts *CLISetupOptions) (*CLI, error)
SetupCLI creates, configures, and initializes a CLI instance with the provided options. It sets up model display, usage tracking for supported providers, and shows initial loading information. Returns nil in quiet mode or an initialized CLI instance ready for user interaction.
func (*CLI) DisplayAssistantMessageWithModel ¶
DisplayAssistantMessageWithModel renders and displays an AI assistant's response with the specified model name shown in the message header. The message is formatted according to the current display mode and includes timestamp information.
func (*CLI) DisplayDebugConfig ¶
DisplayDebugConfig renders and displays configuration settings in a formatted debug message. The config parameter should contain key-value pairs representing configuration options that will be displayed for debugging purposes.
func (*CLI) DisplayDebugMessage ¶
DisplayDebugMessage renders and displays a debug message if debug mode is enabled. Debug messages are formatted distinctively and only shown when the CLI is initialized with debug=true.
func (*CLI) DisplayError ¶
DisplayError renders and displays an error message with distinctive formatting to ensure visibility. The error is timestamped and styled according to the current display mode's error theme.
func (*CLI) DisplayExtensionBlock ¶
DisplayExtensionBlock renders a custom styled block with the given border color and optional subtitle. Used by extensions via ctx.PrintBlock.
func (*CLI) DisplayInfo ¶
DisplayInfo renders and displays an informational system message. These messages are typically used for status updates, notifications, or other non-error system communications to the user.
func (*CLI) DisplayToolMessage ¶
DisplayToolMessage renders and displays the complete result of a tool execution, including the tool name, arguments, and result. The isError parameter determines whether the result should be displayed as an error or success message.
func (*CLI) DisplayUsageAfterResponse ¶
func (c *CLI) DisplayUsageAfterResponse()
DisplayUsageAfterResponse renders and displays token usage information immediately following an AI response. This provides real-time feedback about the cost and token consumption of each interaction.
func (*CLI) DisplayUserMessage ¶
DisplayUserMessage renders and displays a user's message with appropriate formatting based on the current display mode (standard or compact). The message is timestamped and styled according to the active theme.
func (*CLI) GetUsageTracker ¶
func (c *CLI) GetUsageTracker() *UsageTracker
GetUsageTracker returns the usage tracker attached to this CLI, or nil if no tracker has been configured. Callers that need a usage-tracker-agnostic handle can assign the returned *UsageTracker wherever an app.UsageUpdater is expected — *UsageTracker satisfies that interface.
func (*CLI) SetModelName ¶
SetModelName updates the current AI model name being used in the conversation. This name is displayed in message headers to indicate which model is responding.
func (*CLI) SetUsageTracker ¶
func (c *CLI) SetUsageTracker(tracker *UsageTracker)
SetUsageTracker attaches a usage tracker to the CLI for monitoring token consumption and costs. The tracker will be automatically updated with the current display width for proper rendering.
func (*CLI) ShowSpinner ¶
ShowSpinner displays an animated spinner while executing the provided action function. The spinner automatically stops when the action completes. Returns any error returned by the action function.
type CLIEventHandler ¶
type CLIEventHandler struct {
// contains filtered or unexported fields
}
CLIEventHandler routes app-layer events to CLI display methods for non-interactive modes (--prompt and script). It supports two display strategies depending on whether streaming is active:
Streaming mode (StreamChunkEvents arrive):
- Chunks are printed directly to stdout as they arrive, giving the user real-time feedback identical to the interactive TUI.
- At flush boundaries (tool calls, step completion) a trailing newline is printed and the streamed flag prevents double-rendering.
Non-streaming mode (no StreamChunkEvents):
- The complete response arrives via ResponseCompleteEvent or StepCompleteEvent and is rendered through the formatted CLI display.
func NewCLIEventHandler ¶
func NewCLIEventHandler(cli *CLI, modelName string) *CLIEventHandler
NewCLIEventHandler creates a handler that routes app events to the given CLI. modelName is shown in assistant message headers.
func (*CLIEventHandler) Cleanup ¶
func (h *CLIEventHandler) Cleanup()
Cleanup ensures any active spinner is stopped. Must be called after the agent step finishes (whether successfully or not).
func (*CLIEventHandler) Handle ¶
func (h *CLIEventHandler) Handle(msg app.Event)
Handle processes a single app event and renders it via the CLI. This is the callback passed to app.RunOnceWithDisplay.
type CLISetupOptions ¶
type CLISetupOptions struct {
Agent AgentInterface
ModelString string
Debug bool
Quiet bool
ShowDebug bool // Whether to show debug config
ProviderAPIKey string // For OAuth detection
}
CLISetupOptions encapsulates all configuration parameters needed to initialize and set up a CLI instance, including display preferences, model information, and debugging settings.
type CancelTimerExpiredMsg ¶ added in v0.34.0
type CancelTimerExpiredMsg = core.CancelTimerExpiredMsg
Re-export from core package
type EditorInterceptor ¶ added in v0.2.0
type EditorInterceptor struct {
// HandleKey intercepts key presses before the built-in editor.
HandleKey func(key string, currentText string) EditorKeyAction
// Render wraps the built-in editor's rendered output.
Render func(width int, defaultContent string) string
}
EditorInterceptor is the UI-layer representation of an extension editor interceptor. It decouples the UI package from the extensions package. The CLI layer converts the extension EditorConfig to this type.
type EditorKeyAction ¶ added in v0.2.0
type EditorKeyAction struct {
// Type determines the action taken.
Type EditorKeyActionType
// RemappedKey is the target key name for EditorKeyRemap.
RemappedKey string
// SubmitText is the text to submit for EditorKeySubmit.
SubmitText string
}
EditorKeyAction is the UI-layer equivalent of extensions.EditorKeyAction.
type EditorKeyActionType ¶ added in v0.2.0
type EditorKeyActionType string
EditorKeyActionType defines the outcome of an editor key interception. Mirrors extensions.EditorKeyActionType for package decoupling.
const ( // EditorKeyPassthrough lets the built-in editor handle the key normally. EditorKeyPassthrough EditorKeyActionType = "passthrough" // EditorKeyConsumed means the extension handled the key. EditorKeyConsumed EditorKeyActionType = "consumed" // EditorKeyRemap transforms the key into a different key. EditorKeyRemap EditorKeyActionType = "remap" // EditorKeySubmit forces immediate text submission. EditorKeySubmit EditorKeyActionType = "submit" )
type ExtensionCommand ¶
type ExtensionCommand = commands.ExtensionCommand
Re-export from commands package
type ExtensionItem ¶ added in v0.69.0
type ExtensionItem struct {
Name string // Extension display name (filename without .go extension).
Path string // Absolute path to the extension's .go file.
Source string // "project" or "user" (global).
}
ExtensionItem holds display metadata about a loaded extension for the startup [Extensions] section. Built by the CLI layer from the SDK's []kit.ExtensionInfo.
type FileAttachmentResult ¶ added in v0.51.0
type FileAttachmentResult = fileutil.FileAttachmentResult
Re-export types from fileutil
type FileSuggestion ¶ added in v0.4.0
type FileSuggestion struct {
// RelPath is the path relative to the search base (e.g. "cmd/kit/main.go")
// or a display name for MCP resources (e.g. "mcp:server/resource-name").
RelPath string
// IsDir is true when the entry is a directory.
IsDir bool
// Score is the fuzzy match score (higher is better).
Score int
// IsMCPResource is true for MCP resource entries.
IsMCPResource bool
// MCPServerName is the MCP server name (set when IsMCPResource is true).
MCPServerName string
// MCPResourceURI is the MCP resource URI (set when IsMCPResource is true).
MCPResourceURI string
// MCPMIMEType is the MIME type hint from the MCP server.
MCPMIMEType string
}
FileSuggestion represents a single file, directory, or MCP resource suggestion for the @ autocomplete popup.
func GetFileSuggestions ¶ added in v0.4.0
func GetFileSuggestions(prefix string, cwd string) []FileSuggestion
GetFileSuggestions returns file/directory suggestions matching the given prefix. It tries `git ls-files` first (fast, respects .gitignore), then falls back to a simple directory walk.
If prefix contains a path separator the search is scoped to that subdirectory. For example, prefix "cmd/k" searches inside "cmd/" for entries matching "k".
type FlatNode ¶
type FlatNode struct {
Node app.TreeNodeView // value projection of the entry
ID string // entry ID
ParentID string
Depth int // indentation level
IsLast bool // last child at this depth
Prefix string // computed prefix string (├─, └─, etc.)
Label string // user-defined label, if any
}
FlatNode is a tree entry flattened for list rendering with indentation info.
type FuzzyMatch ¶
type FuzzyMatch struct {
Command *commands.SlashCommand
Score int
}
FuzzyMatch represents the result of a fuzzy string matching operation, containing the matched command and its relevance score. Higher scores indicate better matches.
func FuzzyMatchCommands ¶
func FuzzyMatchCommands(query string, commands []commands.SlashCommand) []FuzzyMatch
FuzzyMatchCommands performs fuzzy string matching on the provided slash commands based on the query string. Returns a slice of matches sorted by relevance score in descending order. An empty query returns all commands with zero scores.
type ImageAttachment ¶ added in v0.7.0
type ImageAttachment = core.ImageAttachment
Re-export from core package
type InputComponent ¶
type InputComponent struct {
// contains filtered or unexported fields
}
InputComponent is the interactive text input field for the parent AppModel. It wraps the slash command autocomplete popup and delegates slash command execution to the AppController. On submit it returns a submitMsg tea.Cmd instead of tea.Quit — lifecycle is entirely managed by the parent.
Slash commands handled locally (not forwarded to app layer):
- /quit, /q, /exit → tea.Quit
- /clear, /cls, /c → appCtrl.ClearMessages() then clear the textarea
/clear-queue is forwarded to the parent via submitMsg so the parent can update queueCount directly (calling ClearQueue from within Update would require prog.Send which deadlocks).
All other input is returned via submitMsg for the parent to forward to app.Run().
func NewInputComponent ¶
func NewInputComponent(width int, appCtrl AppController) *InputComponent
NewInputComponent creates a new InputComponent with the given width and optional AppController. If appCtrl is nil the component still works but /clear and /clear-queue are no-ops.
func (*InputComponent) Clear ¶ added in v0.57.0
func (s *InputComponent) Clear() bool
Clear clears the textarea content and resets related state. Returns true if there was content to clear, false if the input was already empty.
func (*InputComponent) ClearPendingImages ¶ added in v0.7.0
func (s *InputComponent) ClearPendingImages() []core.ImageAttachment
ClearPendingImages removes all pending image attachments and returns them. Used by the parent model when consuming images for submission.
func (*InputComponent) Init ¶
func (s *InputComponent) Init() tea.Cmd
Init implements tea.Model. Starts the cursor blink animation.
func (*InputComponent) PendingImageCount ¶ added in v0.7.0
func (s *InputComponent) PendingImageCount() int
PendingImageCount returns the number of images currently attached.
func (*InputComponent) RenderPopupBox ¶ added in v0.90.0
func (s *InputComponent) RenderPopupBox(termWidth, termHeight int) string
RenderPopupBox renders the autocomplete popup for / or @ as a bare box. Returns "" when the popup is not currently shown. The caller composites it over the main view so the transcript stays visible around it.
The actual filtering / selection state lives on InputComponent — this method merely converts the filtered FuzzyMatch list into PopupItems and asks the shared PopupList to draw it. As a result the / popup, the @ popup, the model picker, the tree selector and the session selector all share identical chrome.
func (*InputComponent) SetCwd ¶ added in v0.4.0
func (s *InputComponent) SetCwd(cwd string)
SetCwd sets the working directory used for @file autocomplete suggestions and path resolution. Should be called by the parent after construction.
func (*InputComponent) SetMCPResourceProvider ¶ added in v0.51.0
func (s *InputComponent) SetMCPResourceProvider(fn func() []FileSuggestion)
SetMCPResourceProvider sets a callback that returns MCP resource suggestions for the @ autocomplete popup. Called by the parent after construction.
func (*InputComponent) Update ¶
Update implements tea.Model. Handles keyboard input, popup navigation, and slash command execution. Returns submitMsg via a tea.Cmd when the user submits text — it does NOT return tea.Quit (parent owns lifecycle).
func (*InputComponent) UpdateTheme ¶ added in v0.89.0
func (s *InputComponent) UpdateTheme()
UpdateTheme repaints the composer with colors from the current theme. Called after /theme switches the active palette.
func (*InputComponent) View ¶
func (s *InputComponent) View() tea.View
View implements tea.Model. Renders the composer bar and any pending image attachments. The autocomplete popup is drawn separately as a centered overlay by AppModel.View().
type InspectableItem ¶ added in v0.90.0
type InspectableItem interface {
// RawContent returns the untruncated source text for the message.
RawContent() string
// Role returns the message role, used to pick a title and decide
// whether the inspector should render the body as markdown.
Role() string
}
InspectableItem is implemented by MessageItems that can expose their original source text. The scrollback stores a display-oriented rendering (styled, width-wrapped, and frequently truncated); the message inspector needs the underlying text so the user can read what was elided.
MessageItems that do not implement this interface are still selectable — the inspector falls back to their rendered content.
type MCPPromptArgInfo ¶ added in v0.51.0
MCPPromptArgInfo describes an argument for an MCP prompt.
type MCPPromptExpandResult ¶ added in v0.51.0
type MCPPromptExpandResult struct {
Messages []MCPPromptMessageInfo
}
MCPPromptExpandResult is the result of lazily expanding an MCP prompt.
type MCPPromptInfo ¶ added in v0.51.0
type MCPPromptInfo struct {
Name string // Prompt name on the MCP server.
Description string // Human-readable description.
Arguments []MCPPromptArgInfo // Expected arguments.
ServerName string // Owning MCP server name.
}
MCPPromptInfo describes an MCP prompt for display in the TUI (autocomplete, help). This is a pure UI type — it carries no MCP client dependencies.
type MCPPromptMessageInfo ¶ added in v0.51.0
type MCPPromptMessageInfo struct {
Role string // "user" or "assistant"
Content string
FileParts []kit.LLMFilePart
}
MCPPromptMessageInfo is a single message from an expanded MCP prompt.
type MCPResourceReader ¶ added in v0.51.0
type MCPResourceReader = fileutil.MCPResourceReader
Re-export types from fileutil
type MarkdownThemeColors ¶ added in v0.15.0
type MarkdownThemeColors = style.MarkdownThemeColors
Re-export from style package
type MessageItem ¶ added in v0.33.0
type MessageItem interface {
// Render returns the styled content for this message at the given width.
// Implementations should cache the result to avoid re-rendering.
Render(width int) string
// Height returns the number of lines this message occupies when rendered.
Height() int
// ID returns a unique identifier for this message (for tracking).
ID() string
}
MessageItem is the interface all scrollback messages must implement. This allows lazy rendering - messages are only rendered when visible.
type MessageRenderer ¶
type MessageRenderer struct {
// contains filtered or unexported fields
}
MessageRenderer handles the formatting and rendering of different message types
func (*MessageRenderer) RenderAssistantMessage ¶
func (r *MessageRenderer) RenderAssistantMessage(content string, timestamp time.Time, modelName string) UIMessage
RenderAssistantMessage renders an AI assistant's response
func (*MessageRenderer) RenderCustomMessage ¶ added in v0.58.1
func (r *MessageRenderer) RenderCustomMessage(content, label string, timestamp time.Time) UIMessage
RenderCustomMessage renders a message with a custom alert label (e.g. "Help"). Content is rendered as markdown.
func (*MessageRenderer) RenderDebugConfigMessage ¶
func (r *MessageRenderer) RenderDebugConfigMessage(config map[string]any, timestamp time.Time) UIMessage
RenderDebugConfigMessage renders configuration settings
func (*MessageRenderer) RenderDebugMessage ¶
func (r *MessageRenderer) RenderDebugMessage(message string, timestamp time.Time) UIMessage
RenderDebugMessage renders diagnostic and debugging information
func (*MessageRenderer) RenderErrorMessage ¶
func (r *MessageRenderer) RenderErrorMessage(errorMsg string, timestamp time.Time) UIMessage
RenderErrorMessage renders error notifications
func (*MessageRenderer) RenderExtensionBlock ¶ added in v0.91.0
func (r *MessageRenderer) RenderExtensionBlock(text, borderColor, subtitle string) UIMessage
RenderExtensionBlock renders a custom styled block from an extension with a caller-chosen border color and optional subtitle.
Extensions get the same geometry as every other attributed block — gutter glyph in column 0, text at ContentOffset, one trailing gap — and choose only the stripe color. Letting them choose more would let a single extension make the transcript look inconsistent.
func (*MessageRenderer) RenderReasoningBlock ¶ added in v0.32.0
func (r *MessageRenderer) RenderReasoningBlock(content string, timestamp time.Time) UIMessage
RenderReasoningBlock renders a reasoning/thinking block with the same styling as live streaming: muted italic text with margin. This is used when resuming sessions to display saved reasoning content.
func (*MessageRenderer) RenderSystemMessage ¶
func (r *MessageRenderer) RenderSystemMessage(content string, timestamp time.Time) UIMessage
RenderSystemMessage renders KIT system messages using herald Note alert
func (*MessageRenderer) RenderToolMessage ¶
func (r *MessageRenderer) RenderToolMessage(toolName, toolArgs, toolResult string, isError bool) UIMessage
RenderToolMessage renders a unified tool block
func (*MessageRenderer) RenderUserMessage ¶
func (r *MessageRenderer) RenderUserMessage(content string, timestamp time.Time) UIMessage
RenderUserMessage renders a user's input message with a colored left border.
func (*MessageRenderer) SetWidth ¶
func (r *MessageRenderer) SetWidth(width int)
SetWidth updates the terminal width for the renderer
func (*MessageRenderer) UpdateTheme ¶ added in v0.31.0
func (r *MessageRenderer) UpdateTheme()
UpdateTheme refreshes the renderer's typography instance with colors from the current theme. This is called when the user changes themes via /theme.
type MessageType ¶
type MessageType int
MessageType represents different categories of messages displayed in the UI, each with distinct visual styling and formatting rules.
const ( UserMessage MessageType = iota AssistantMessage ToolMessage ToolCallMessage SystemMessage ErrorMessage )
type ModelEntry ¶ added in v0.6.0
type ModelEntry struct {
Provider string
ModelID string
Name string // human-friendly name (e.g. "Claude Haiku 4.5")
ContextLimit int
Reasoning bool
}
ModelEntry holds display metadata for a single model in the selector.
type ModelSelectedMsg ¶ added in v0.6.0
type ModelSelectedMsg struct {
ModelString string // "provider/model-id"
}
ModelSelectedMsg is sent when the user selects a model from the selector.
type ModelSelectorCancelledMsg ¶ added in v0.6.0
type ModelSelectorCancelledMsg struct{}
ModelSelectorCancelledMsg is sent when the user cancels the selector.
type ModelSelectorComponent ¶ added in v0.6.0
type ModelSelectorComponent struct {
// contains filtered or unexported fields
}
ModelSelectorComponent is a Bubble Tea component that displays a filterable list of available models as a centered overlay popup. It delegates rendering and keyboard navigation to PopupList and converts results into the ModelSelectedMsg / ModelSelectorCancelledMsg messages expected by AppModel.
func NewModelSelector ¶ added in v0.6.0
func NewModelSelector(currentModel string, width, height int) *ModelSelectorComponent
NewModelSelector creates a model selector populated from the global registry, filtered to only providers with configured API keys.
func (*ModelSelectorComponent) Init ¶ added in v0.6.0
func (ms *ModelSelectorComponent) Init() tea.Cmd
Init implements tea.Model.
func (*ModelSelectorComponent) IsActive ¶ added in v0.6.0
func (ms *ModelSelectorComponent) IsActive() bool
IsActive returns whether the selector is still accepting input.
func (*ModelSelectorComponent) RenderOverlay ¶ added in v0.35.0
func (ms *ModelSelectorComponent) RenderOverlay() string
RenderOverlay returns the popup as a bare box, ready to be composited on top of the main content so the conversation stays visible behind it.
func (*ModelSelectorComponent) View ¶ added in v0.6.0
func (ms *ModelSelectorComponent) View() tea.View
View implements tea.Model — not used for overlay rendering. Use RenderOverlay for the centered overlay approach.
type PopupItem ¶ added in v0.35.0
type PopupItem struct {
Label string // primary display text
Description string // secondary text (shown right of label)
Active bool // true → render checkmark indicator
Meta any // opaque data returned on selection
}
PopupItem represents a single entry in a PopupList. The component renders Label as the primary text and Description as secondary text to its right. The Active flag renders a checkmark to indicate the currently-active item (e.g. the current model). Meta is opaque caller data returned on selection.
type PopupList ¶ added in v0.35.0
type PopupList struct {
// Title shown at the top of the popup.
Title string
// Subtitle shown below the title (dimmed).
Subtitle string
FooterHint string
// Used by selectors to surface mode info like the active filter.
ExtraFooter string
// FullScreen renders the popup at almost the full terminal size instead
// of a centered ~80-col box. Used by tree/session/fork selectors.
FullScreen bool
// ShowSearch toggles the "> <query>" search input line. Default true.
ShowSearch bool
// HideCount suppresses the "(i/N)" count in the footer.
HideCount bool
// MaxVisible caps the number of items visible at once. 0 = derive from
// available height.
MaxVisible int
// RenderItem optionally renders a single item row. When nil, the
// built-in label + description + active-checkmark renderer is used.
// innerWidth is the usable line width inside the popup (after border
// and padding). The returned string must already be styled — the
// shared selection-row background is applied by the popup only when
// RenderItem is nil.
RenderItem func(item PopupItem, innerWidth int, isCursor bool) string
// FilterFunc is called with (query, allItems) and should return the
// filtered+scored subset. When nil, a default substring + fuzzy match
// is used. Only consulted in internal-state mode (via HandleKey).
FilterFunc func(query string, items []PopupItem) []PopupItem
// contains filtered or unexported fields
}
PopupList is a generic, themed, scrollable popup list used by every list-style popup in the TUI (slash commands, @file autocomplete, model picker, session picker, tree navigation, etc.).
Two layout modes:
- Centered (default): bordered ~80-col box centered on the screen. Used for the input-bar popups (/ and @) and the model picker.
- FullScreen: bordered panel filling almost the entire terminal. Used by /tree, /fork, /sessions and other browse-many-items popups.
Two usage modes:
- Internal state: caller creates the list with items, calls HandleKey for navigation/search, and PopupList owns the cursor and search string. Used by selectors like ModelSelector, TreeSelector, SessionSelector.
- External state: caller drives the items / cursor / search themselves (e.g. InputComponent, where typing in the textarea filters the list). Caller uses SetItems / SetCursor / SetSearch and only calls Render.
func NewPopupList ¶ added in v0.35.0
NewPopupList creates a new popup list with the given items and dimensions.
func (*PopupList) HandleKey ¶ added in v0.35.0
func (p *PopupList) HandleKey(keyName, keyText string) PopupResult
HandleKey processes a single key event and returns the result. The caller should inspect PopupResult to decide whether to re-render, close the popup, or act on a selection. Internal-state mode only — external-state callers drive cursor/search themselves and never call this.
keyName is the Bubble Tea key string (e.g. "up", "down", "enter", "esc"). keyText is the printable text for character keys (e.g. "a", "1").
func (*PopupList) IsSearching ¶ added in v0.35.0
IsSearching returns true when the search input is non-empty.
func (*PopupList) Render ¶ added in v0.35.0
Render returns the styled popup content (bordered box) ready to be placed as a centered overlay via lipgloss.Place + overlayContent.
func (*PopupList) RenderCentered ¶ added in v0.35.0
RenderCentered returns the popup placed at the center of a termWidth×termHeight canvas. Prefer Render() plus the compositor for modals — this full-screen form is opaque and erases whatever sits behind it.
func (*PopupList) SelectedItem ¶ added in v0.35.0
SelectedItem returns the item under the cursor, or nil if the list is empty.
func (*PopupList) SetCursor ¶ added in v0.74.0
SetCursor moves the selection to the given index (clamped to range).
func (*PopupList) SetItems ¶ added in v0.74.0
SetItems replaces the displayed item list and clamps the cursor. Used by external-state callers (e.g. InputComponent) that filter items themselves. In internal-state mode, this also replaces the unfiltered backing list.
type PopupResult ¶ added in v0.35.0
type PopupResult struct {
// Selected is non-nil when the user pressed Enter on an item.
Selected *PopupItem
// Cancelled is true when the user pressed Esc with no search text.
Cancelled bool
// Changed is true when the search or cursor moved (caller should re-render).
Changed bool
}
PopupResult is returned by HandleKey to tell the caller what happened.
type Renderer ¶ added in v0.2.0
type Renderer interface {
RenderUserMessage(content string, timestamp time.Time) UIMessage
RenderAssistantMessage(content string, timestamp time.Time, modelName string) UIMessage
RenderReasoningBlock(content string, timestamp time.Time) UIMessage
RenderToolMessage(toolName, toolArgs, toolResult string, isError bool) UIMessage
RenderSystemMessage(content string, timestamp time.Time) UIMessage
RenderCustomMessage(content, label string, timestamp time.Time) UIMessage
RenderErrorMessage(errorMsg string, timestamp time.Time) UIMessage
RenderExtensionBlock(text, borderColor, subtitle string) UIMessage
RenderDebugMessage(message string, timestamp time.Time) UIMessage
RenderDebugConfigMessage(config map[string]any, timestamp time.Time) UIMessage
SetWidth(width int)
UpdateTheme()
}
Renderer is the interface satisfied by MessageRenderer. It allows model.go and cli.go to call rendering methods uniformly.
type ScrollList ¶ added in v0.33.0
type ScrollList struct {
// contains filtered or unexported fields
}
ScrollList manages a viewport over a list of MessageItems. It handles offset-based scrolling, lazy rendering, and character-level text selection (crush-style). Only visible items are rendered on each View() call.
func NewScrollList ¶ added in v0.33.0
func NewScrollList(width, height int) *ScrollList
NewScrollList creates a new ScrollList with the given dimensions.
func (*ScrollList) AtBottom ¶ added in v0.33.0
func (s *ScrollList) AtBottom() bool
AtBottom returns true if the viewport is at the bottom of the list.
func (*ScrollList) AtTop ¶ added in v0.33.0
func (s *ScrollList) AtTop() bool
AtTop returns true if the viewport is at the top of the list.
func (*ScrollList) ClearSelection ¶ added in v0.33.0
func (s *ScrollList) ClearSelection()
ClearSelection clears the current text selection.
func (*ScrollList) EnsureVisible ¶ added in v0.90.0
func (s *ScrollList) EnsureVisible(idx int)
EnsureVisible scrolls the minimum amount needed to bring the item at idx fully into the viewport.
If the item sits above the viewport it is aligned to the top; if it extends past the bottom it is scrolled up just far enough to fit. An item taller than the viewport is aligned to its first line so navigation always lands on the start of a long message rather than its middle.
func (*ScrollList) ExtractSelectedText ¶ added in v0.34.0
func (s *ScrollList) ExtractSelectedText() string
ExtractSelectedText returns the plain text content of the current selection by walking through selected items and extracting text at the character level using the ultraviolet cell buffer (ANSI-aware).
func (*ScrollList) GotoBottom ¶ added in v0.33.0
func (s *ScrollList) GotoBottom()
GotoBottom scrolls to the end of the list. Uses cached heights and walks backwards from the end to avoid rendering every item in the list.
func (*ScrollList) GotoTop ¶ added in v0.33.0
func (s *ScrollList) GotoTop()
GotoTop scrolls to the beginning of the list.
func (*ScrollList) HandleMouseDown ¶ added in v0.33.0
func (s *ScrollList) HandleMouseDown(x, y int) bool
HandleMouseDown handles mouse button press. Detects single, double, and triple clicks for character, word, and line selection respectively. Returns true if the click was handled.
func (*ScrollList) HandleMouseDrag ¶ added in v0.33.0
func (s *ScrollList) HandleMouseDrag(x, y int) bool
HandleMouseDrag handles mouse motion while button is held. Updates the selection endpoint for character-level precision. Returns true if selection was updated.
Defensively disables auto-scroll on every drag update — even if the MouseDown handler missed (e.g. click landed in viewport padding), any active drag means the user is selecting and the viewport must not jump.
func (*ScrollList) HandleMouseUp ¶ added in v0.33.0
func (s *ScrollList) HandleMouseUp() bool
HandleMouseUp handles mouse button release. Returns true if there was an active selection.
func (*ScrollList) HasSelection ¶ added in v0.33.0
func (s *ScrollList) HasSelection() bool
HasSelection returns true if there is a non-empty active selection.
func (*ScrollList) InvalidateHeights ¶ added in v0.93.0
func (s *ScrollList) InvalidateHeights()
InvalidateHeights drops every cached height, forcing each item to be re-measured on the next query. Call this when something outside the list changes how items render — a theme switch, for instance, where a repainted block can occupy a different number of lines than the one it replaces.
func (*ScrollList) InvalidateItemHeight ¶ added in v0.62.0
func (s *ScrollList) InvalidateItemHeight(id string)
InvalidateItemHeight removes the cached height for the given item ID, forcing a re-render on the next height query. Call this after mutating an item's content (e.g. AppendChunk on a streaming message).
func (*ScrollList) IsMouseDown ¶ added in v0.68.0
func (s *ScrollList) IsMouseDown() bool
IsMouseDown reports whether the user currently has the mouse button held (i.e. a selection drag is in progress). Used by the parent model to avoid re-enabling auto-scroll during streaming while the user is selecting.
func (*ScrollList) ItemAt ¶ added in v0.90.0
func (s *ScrollList) ItemAt(idx int) MessageItem
ItemAt returns the item at idx, or nil when idx is out of range.
func (*ScrollList) ItemGap ¶ added in v0.33.0
func (s *ScrollList) ItemGap() int
ItemGap returns the current gap between items.
func (*ScrollList) Len ¶ added in v0.90.0
func (s *ScrollList) Len() int
Len returns the number of items in the list.
func (*ScrollList) ScrollBy ¶ added in v0.33.0
func (s *ScrollList) ScrollBy(lines int)
ScrollBy scrolls the viewport by the given number of lines. Positive = scroll down, negative = scroll up.
func (*ScrollList) ScrollPercent ¶ added in v0.33.0
func (s *ScrollList) ScrollPercent() float64
ScrollPercent returns the current scroll position as a percentage (0.0-1.0). 0.0 = at top, 1.0 = at bottom. Useful for scroll indicators.
func (*ScrollList) SelectedIndex ¶ added in v0.90.0
func (s *ScrollList) SelectedIndex() int
SelectedIndex returns the index of the selected message, or -1 if none.
func (*ScrollList) SetHeight ¶ added in v0.33.0
func (s *ScrollList) SetHeight(height int)
SetHeight updates the viewport height. Called when the terminal is resized.
func (*ScrollList) SetItemGap ¶ added in v0.33.0
func (s *ScrollList) SetItemGap(gap int)
SetItemGap sets the number of blank lines between items (0 = no gap).
func (*ScrollList) SetItems ¶ added in v0.33.0
func (s *ScrollList) SetItems(items []MessageItem)
SetItems replaces the items in the scroll list. If auto-scroll is enabled, the viewport will scroll to the bottom to show the latest content — EXCEPT when the user is actively selecting text (mouse button held), in which case the scroll position is locked so the highlighted content stays under the cursor. The pending bottom-scroll is deferred to MouseUp.
func (*ScrollList) SetSelectedIndex ¶ added in v0.90.0
func (s *ScrollList) SetSelectedIndex(idx int)
SetSelectedIndex sets the message framed by the selection border, or -1 to clear the selection. The border adds two lines to the item's rendered height, so the cached heights of both the previously and newly selected items are invalidated to keep scroll math and mouse hit-testing accurate.
func (*ScrollList) SetSelectionFrame ¶ added in v0.94.0
func (s *ScrollList) SetSelectionFrame(label, hint string)
SetSelectionFrame sets the text spliced into the selected item's frame: label into the top edge, hint into the bottom.
The labels are pushed in on selection change rather than derived here per frame. Working out which message the selection is on, and what its role is, means walking the item list; doing that inside the render path would repeat the walk on every frame for an answer that only changes on a keypress.
func (*ScrollList) SetWidth ¶ added in v0.33.0
func (s *ScrollList) SetWidth(width int)
SetWidth updates the viewport width. Called when the terminal is resized. This invalidates the height cache since rendered heights are width-dependent. A no-op when the width is unchanged — distributeHeight() calls this every layout pass, and wiping the cache on every pass would force full re-renders of all visible items purely to recompute known heights.
func (*ScrollList) View ¶ added in v0.33.0
func (s *ScrollList) View() string
View renders the visible portion of the scrollback. Only items that fit within the viewport height are rendered. ALWAYS returns exactly s.height lines (padded with empty lines if needed) to ensure the input/footer stay fixed at the bottom.
When an active selection exists, character-level highlighting is applied using ultraviolet ScreenBuffer for ANSI-aware cell manipulation.
type SessionDeletedMsg ¶ added in v0.16.0
type SessionDeletedMsg struct {
Name string
}
SessionDeletedMsg is sent after a session is deleted so the parent can react (e.g. print a message).
type SessionFilterMode ¶ added in v0.16.0
type SessionFilterMode int
SessionFilterMode controls filtering of the session list.
const ( SessionFilterAll SessionFilterMode = iota // show all sessions SessionFilterNamed // only named sessions )
func (SessionFilterMode) String ¶ added in v0.16.0
func (m SessionFilterMode) String() string
type SessionScopeMode ¶ added in v0.16.0
type SessionScopeMode int
SessionScopeMode controls which sessions are shown.
const ( SessionScopeCwd SessionScopeMode = iota // current folder only SessionScopeAll // all sessions across projects )
func (SessionScopeMode) String ¶ added in v0.16.0
func (m SessionScopeMode) String() string
type SessionSelectedMsg ¶ added in v0.16.0
type SessionSelectedMsg struct {
Path string // absolute path to the JSONL session file
}
SessionSelectedMsg is sent when the user selects a session from the picker.
type SessionSelectorCancelledMsg ¶ added in v0.16.0
type SessionSelectorCancelledMsg struct{}
SessionSelectorCancelledMsg is sent when the user cancels the picker.
type SessionSelectorComponent ¶ added in v0.16.0
type SessionSelectorComponent struct {
// contains filtered or unexported fields
}
SessionSelectorComponent is a Bubble Tea component that lets the user browse and select from available sessions. It wraps PopupList in FullScreen mode: PopupList owns the cursor/search/scroll math/chrome; this component owns the session list, scope/filter toggles, and delete-confirmation flow.
func NewSessionSelector ¶ added in v0.16.0
func NewSessionSelector(store SessionStore, cwd string, width, height int) *SessionSelectorComponent
NewSessionSelector creates a session selector. It loads sessions for the current working directory and all sessions across projects from store. If cwd is empty, only "All" scope is available.
func (*SessionSelectorComponent) Init ¶ added in v0.16.0
func (ss *SessionSelectorComponent) Init() tea.Cmd
Init implements tea.Model.
func (*SessionSelectorComponent) IsActive ¶ added in v0.16.0
func (ss *SessionSelectorComponent) IsActive() bool
IsActive returns whether the selector is still accepting input.
func (*SessionSelectorComponent) RenderOverlay ¶ added in v0.90.0
func (ss *SessionSelectorComponent) RenderOverlay() string
RenderOverlay returns the selector as a bare box, ready to be composited over the main view so the conversation stays visible behind it.
func (*SessionSelectorComponent) SetCurrentPath ¶ added in v0.16.0
func (ss *SessionSelectorComponent) SetCurrentPath(path string)
SetCurrentPath sets the currently active session path so the picker can highlight it in the list.
func (*SessionSelectorComponent) View ¶ added in v0.16.0
func (ss *SessionSelectorComponent) View() tea.View
View implements tea.Model.
type SessionStats ¶
type SessionStats struct {
TotalInputTokens int
TotalOutputTokens int
TotalCacheReadTokens int
TotalCacheWriteTokens int
TotalCost float64
RequestCount int
}
SessionStats aggregates token usage and cost information across all requests in a session, providing totals and request counts for usage analysis and cost tracking.
type SessionStore ¶ added in v0.94.0
type SessionStore interface {
// ListSessions returns summaries of the sessions recorded for cwd,
// newest first.
ListSessions(cwd string) ([]app.SessionSummary, error)
// ListAllSessions returns summaries of every session across all working
// directories, newest first.
ListAllSessions() ([]app.SessionSummary, error)
// DeleteSession removes a session file from disk.
DeleteSession(path string) error
}
SessionStore is the slice of the app layer the session picker needs: it lists the sessions on disk and deletes them. The picker owns the loading itself (rather than being handed a list) because it reloads across scope toggles and mutates the list in place after a delete.
type ShellCommandMsg ¶ added in v0.34.0
type ShellCommandMsg = core.ShellCommandMsg
Re-export from core package
type ShellCommandResultMsg ¶ added in v0.34.0
type ShellCommandResultMsg = core.ShellCommandResultMsg
Re-export from core package
type ShortcutInfo ¶ added in v0.95.0
type ShortcutInfo struct {
// Key is the normalized binding, e.g. "ctrl+p".
Key string
// Description explains what the shortcut does.
Description string
// Source is the file name of the extension that registered it.
Source string
}
ShortcutInfo describes one extension-registered keyboard shortcut for the /shortcuts listing. Mirrors extensions.ShortcutEntry for package decoupling.
type SkillItem ¶
type SkillItem struct {
Name string // Skill name (e.g. "btca-cli").
Path string // Absolute path to the skill file.
Source string // "project" or "user" (global).
Description string // Short summary used in autocomplete and help.
}
SkillItem holds display metadata about a loaded skill for the startup [Skills] section. Built by the CLI layer from the SDK's []*kit.Skill.
type Spinner ¶
type Spinner struct {
// contains filtered or unexported fields
}
Spinner provides an animated loading indicator that displays while long-running operations are in progress. It writes directly to stderr using a goroutine-based animation loop, avoiding Bubble Tea's terminal capability queries that can leak escape sequences (mode 2026 DECRPM).
The KITT-style frames are generated by knightRiderFrames() in stream.go (same package) and use the active theme colors.
func NewSpinner ¶
func NewSpinner() *Spinner
NewSpinner creates a new animated KITT-style spinner using theme colors.
type StatusBarEntryData ¶ added in v0.3.0
type StatusBarEntryData struct {
Key string // unique identifier (e.g. "myext:git-branch")
Text string // rendered content shown in the status bar
Priority int // lower = further left; built-in entries use 100-110
}
StatusBarEntryData represents a keyed extension entry in the TUI status bar. Multiple entries from different extensions coexist, ordered by Priority (lower values render further left).
type StreamComponent ¶
type StreamComponent struct {
// contains filtered or unexported fields
}
StreamComponent is the Bubble Tea child model responsible for the stream region: it renders a KITT-style spinner when the agent is working, and displays live text as StreamChunkEvents arrive. The spinner remains visible alongside streaming text until the step completes and Reset() is called.
Tool calls, tool results, user messages, and other non-streaming content are added to the ScrollList by the parent AppModel. The StreamComponent only handles the live streaming text and spinner display.
Lifecycle is managed entirely by the parent AppModel:
- Parent calls Reset() between agent steps to clear state.
- Content is displayed via StreamingMessageItem in the ScrollList.
- StreamComponent never calls tea.Quit.
- The spinner schedules nothing: it advances when the parent's shared frame clock hands it a beat, and keeps that clock alive by reporting IsSpinning.
Events handled:
- app.SpinnerEvent{Show:true} → raise the spinner
- app.StreamChunkEvent → append text
- app.ToolExecutionEvent → show execution label on spinner
- frameTickMsg → advance the spinner animation
func NewStreamComponent ¶
func NewStreamComponent(width int, modelName string) *StreamComponent
NewStreamComponent creates a new StreamComponent ready to be embedded in AppModel.
func (*StreamComponent) ActivityDot ¶ added in v0.89.0
func (s *StreamComponent) ActivityDot() string
ActivityDot returns just the animated indicator glyph, without any label. Returns "" when the spinner is not running.
func (*StreamComponent) ActivityPhrase ¶ added in v0.89.0
func (s *StreamComponent) ActivityPhrase() string
ActivityPhrase returns a present-tense description of what the agent is currently doing, for the activity row. Concurrent tool calls collapse to a count so the row stays a single line; a turn with no tool in flight reports that the model is thinking.
func (*StreamComponent) ConsumeOverflow ¶ added in v0.31.0
func (s *StreamComponent) ConsumeOverflow() string
ConsumeOverflow is a no-op in alt screen mode. Overflow is handled by the ScrollList viewport. Retained to satisfy streamComponentIface.
func (*StreamComponent) GetRenderedContent ¶
func (s *StreamComponent) GetRenderedContent() string
GetRenderedContent returns the rendered assistant message from the accumulated streaming text. Returns empty string if no text has been accumulated. Used by the parent AppModel to flush stream content before resetting.
This commits any pending chunks first so the output includes all received content, not just what has been flushed by the tick.
func (*StreamComponent) HasReasoning ¶ added in v0.7.0
func (s *StreamComponent) HasReasoning() bool
HasReasoning returns true if any reasoning content has been accumulated (committed or pending).
func (*StreamComponent) Init ¶
func (s *StreamComponent) Init() tea.Cmd
Init implements tea.Model. No startup command needed; SpinnerEvent drives the ticker.
func (*StreamComponent) IsSpinning ¶ added in v0.89.0
func (s *StreamComponent) IsSpinning() bool
IsSpinning reports whether the stream is currently animating, i.e. whether there is live activity worth showing.
func (*StreamComponent) Reset ¶
func (s *StreamComponent) Reset()
Reset clears all accumulated state so the component is ready for the next agent step. Called by AppModel after a step completes or errors.
func (*StreamComponent) SetHeight ¶
func (s *StreamComponent) SetHeight(h int)
SetHeight constrains the stream region render height. When height > 0, the render output is clamped to that many lines (trailing lines are discarded). A value of 0 means unconstrained.
func (*StreamComponent) SetThinkingVisible ¶ added in v0.7.0
func (s *StreamComponent) SetThinkingVisible(visible bool)
SetThinkingVisible sets whether reasoning blocks are shown or collapsed.
func (*StreamComponent) Update ¶
Update implements tea.Model. Routes app-layer events and internal tick msgs.
func (*StreamComponent) UpdateTheme ¶ added in v0.31.0
func (s *StreamComponent) UpdateTheme()
UpdateTheme refreshes the component's typography instance and spinner animation frames with colors from the current theme. This is called when the user changes themes via /theme.
func (*StreamComponent) View ¶
func (s *StreamComponent) View() tea.View
View implements tea.Model. Returns an empty view since rendering is handled by StreamingMessageItem in the ScrollList. Retained to satisfy tea.Model.
type StreamingBashOutputItem ¶ added in v0.33.0
type StreamingBashOutputItem struct {
// contains filtered or unexported fields
}
StreamingBashOutputItem represents live bash command output.
func NewStreamingBashOutputItem ¶ added in v0.33.0
func NewStreamingBashOutputItem(id string, command string) *StreamingBashOutputItem
NewStreamingBashOutputItem creates a new streaming bash output item.
func (*StreamingBashOutputItem) AppendStderr ¶ added in v0.33.0
func (m *StreamingBashOutputItem) AppendStderr(line string)
AppendStderr adds a stderr line to the output.
func (*StreamingBashOutputItem) AppendStdout ¶ added in v0.33.0
func (m *StreamingBashOutputItem) AppendStdout(line string)
AppendStdout adds a stdout line to the output.
func (*StreamingBashOutputItem) Height ¶ added in v0.33.0
func (m *StreamingBashOutputItem) Height() int
func (*StreamingBashOutputItem) ID ¶ added in v0.33.0
func (m *StreamingBashOutputItem) ID() string
func (*StreamingBashOutputItem) MarkComplete ¶ added in v0.33.0
func (m *StreamingBashOutputItem) MarkComplete()
MarkComplete marks the bash output as complete.
func (*StreamingBashOutputItem) RawContent ¶ added in v0.90.0
func (m *StreamingBashOutputItem) RawContent() string
RawContent returns the captured command output as plain text, prefixed with the command itself. Streaming bash output is capped to maxLines for display, so this returns whatever the item still retains.
func (*StreamingBashOutputItem) Render ¶ added in v0.33.0
func (m *StreamingBashOutputItem) Render(width int) string
func (*StreamingBashOutputItem) Role ¶ added in v0.90.0
func (m *StreamingBashOutputItem) Role() string
Role returns the message role.
type StreamingMessageItem ¶ added in v0.33.0
type StreamingMessageItem struct {
// contains filtered or unexported fields
}
StreamingMessageItem represents actively streaming assistant or reasoning text. It accumulates content chunks and re-renders on each update for live display.
func NewStreamingMessageItem ¶ added in v0.33.0
func NewStreamingMessageItem(id, role string, modelName string) *StreamingMessageItem
NewStreamingMessageItem creates a new streaming message item.
func (*StreamingMessageItem) AppendChunk ¶ added in v0.33.0
func (s *StreamingMessageItem) AppendChunk(chunk string)
AppendChunk adds a content chunk and invalidates the render cache.
func (*StreamingMessageItem) Height ¶ added in v0.33.0
func (s *StreamingMessageItem) Height() int
Height returns the number of lines.
func (*StreamingMessageItem) ID ¶ added in v0.33.0
func (s *StreamingMessageItem) ID() string
ID returns the unique identifier.
func (*StreamingMessageItem) MarkComplete ¶ added in v0.33.0
func (s *StreamingMessageItem) MarkComplete()
MarkComplete marks the streaming message as complete and freezes the duration.
func (*StreamingMessageItem) RawContent ¶ added in v0.90.0
func (s *StreamingMessageItem) RawContent() string
RawContent returns the accumulated streaming text without styling.
func (*StreamingMessageItem) Render ¶ added in v0.33.0
func (s *StreamingMessageItem) Render(width int) string
Render renders the streaming message with live content.
func (*StreamingMessageItem) Role ¶ added in v0.90.0
func (s *StreamingMessageItem) Role() string
Role returns the message role ("assistant" or "reasoning").
type TextMessageItem ¶ added in v0.33.0
type TextMessageItem struct {
// contains filtered or unexported fields
}
TextMessageItem represents a completed text message (user or assistant) in the scrollback.
Items are created in one of two modes:
- Themed (NewThemedMessageItem): the item keeps the closure that produced its styled content and re-runs it after a theme change, so historical messages recolor along with the rest of the UI.
- Static (NewStyledMessageItem): the item holds a fixed string. This is for content that is either theme-independent or already composed by a caller that owns its own colors.
func NewStyledMessageItem ¶ added in v0.33.0
func NewStyledMessageItem(id string, role string, rawContent string, preRendered string) *TextMessageItem
NewStyledMessageItem creates a message item from fixed, pre-rendered content.
The content will not follow subsequent theme changes. Use this only for output that is theme-independent or whose colors the caller owns deliberately; prefer NewThemedMessageItem for anything drawn from the theme palette.
func NewThemedMessageItem ¶ added in v0.93.0
func NewThemedMessageItem(id string, role string, rawContent string, render func() string) *TextMessageItem
NewThemedMessageItem creates a message item that re-renders itself after a theme change. render must be a pure function of the raw content and the active theme — it is called lazily, once per theme generation, whenever the item is next drawn.
func (*TextMessageItem) Height ¶ added in v0.33.0
func (m *TextMessageItem) Height() int
func (*TextMessageItem) ID ¶ added in v0.33.0
func (m *TextMessageItem) ID() string
func (*TextMessageItem) Invalidate ¶ added in v0.93.0
func (m *TextMessageItem) Invalidate()
Invalidate discards the memoized render so the next draw re-runs the render closure. Use it when the closure's inputs changed rather than the theme — an animation frame, for instance. No-op for static items.
func (*TextMessageItem) RawContent ¶ added in v0.90.0
func (m *TextMessageItem) RawContent() string
RawContent returns the original, untruncated source text for this message. The scrollback stores a display-oriented (styled and possibly truncated) rendering; RawContent is what the message inspector shows so the user can read content that was elided for display.
func (*TextMessageItem) Render ¶ added in v0.33.0
func (m *TextMessageItem) Render(width int) string
func (*TextMessageItem) Role ¶ added in v0.90.0
func (m *TextMessageItem) Role() string
Role returns the message role ("user", "assistant", "tool", ...).
func (*TextMessageItem) ToolCall ¶ added in v0.94.0
func (m *TextMessageItem) ToolCall() (ToolCallInfo, bool)
ToolCall implements ToolInspectable.
func (*TextMessageItem) WithToolCall ¶ added in v0.94.0
func (m *TextMessageItem) WithToolCall(info ToolCallInfo) *TextMessageItem
WithToolCall attaches the structured parts of the tool call this item displays, so the inspector can re-render its body uncapped. Returns the item for chaining at the construction site.
type ToolCallInfo ¶ added in v0.94.0
ToolCallInfo holds the structured parts of a tool call, as handed to the tool-body renderers.
type ToolInspectable ¶ added in v0.94.0
type ToolInspectable interface {
// ToolCall returns the call's parts, and false for items that do not
// display a tool call.
ToolCall() (ToolCallInfo, bool)
}
ToolInspectable is implemented by scrollback items that retain the structured parts of the tool call they display.
The scrollback caps each tool body at a per-tool line limit so one large result cannot bury the rest of the transcript. The inspector opens precisely because something was capped, so it re-renders the body with the caps lifted rather than falling back to plain text and discarding the diff colouring, line gutters and panel fills. Reconstructing the call from the item's flattened raw content is not possible, so it is kept alongside.
type ToolRendererData ¶ added in v0.2.0
type ToolRendererData struct {
// DisplayName, if non-empty, replaces the auto-capitalized tool name
// in the header line.
DisplayName string
// BorderColor, if non-empty, overrides the default success/error border
// color. Hex string (e.g. "#89b4fa").
BorderColor string
// Background, if non-empty, sets a background color for the tool block.
// Hex string (e.g. "#1e1e2e").
Background string
// BodyMarkdown, when true, renders the RenderBody output as markdown
// via glamour. Ignored when RenderBody is nil or returns empty.
BodyMarkdown bool
// RenderHeader, if non-nil, replaces the default parameter formatting
// in the tool header line. Receives the JSON-encoded arguments and max
// width. Return a short summary string, or empty to fall back to default.
RenderHeader func(toolArgs string, width int) string
// RenderBody, if non-nil, replaces the default tool result body. Receives
// the result text, error flag, and available width. Return the full styled
// body content, or empty to fall back to builtin/default renderer.
RenderBody func(toolResult string, isError bool, width int) string
}
ToolRendererData holds extension-provided rendering functions for a specific tool. The UI layer uses this to override the default tool header/body rendering without depending on the extensions package directly.
type TreeFilterMode ¶
type TreeFilterMode int
TreeFilterMode controls which entries are visible in the tree selector.
const ( TreeFilterDefault TreeFilterMode = iota // hide settings entries TreeFilterNoTools // hide tool results TreeFilterUserOnly // show only user messages TreeFilterLabelOnly // show only labeled entries TreeFilterAll // show everything )
func (TreeFilterMode) String ¶
func (m TreeFilterMode) String() string
type TreeNodeSelectedMsg ¶
type TreeNodeSelectedMsg = core.TreeNodeSelectedMsg
Re-export from core package
type TreeSelectorComponent ¶
type TreeSelectorComponent struct {
// contains filtered or unexported fields
}
TreeSelectorComponent is a Bubble Tea component that renders the session tree as an ASCII art list with navigation and selection. It is a thin wrapper around PopupList (in FullScreen mode) — PopupList owns the cursor, search, scroll math, and chrome; TreeSelectorComponent supplies the filtered node list and a custom RenderItem that draws each tree node with its indentation prefix and role colors.
func NewTreeSelector ¶
func NewTreeSelector(roots []app.TreeNodeView, leafID string, width, height int) *TreeSelectorComponent
NewTreeSelector creates a tree selector over a session tree snapshot. roots is the projected entry tree and leafID marks the active branch tip.
func NewTreeSelectorForFork ¶ added in v0.34.0
func NewTreeSelectorForFork(roots []app.TreeNodeView, leafID string, width, height int) *TreeSelectorComponent
NewTreeSelectorForFork creates a tree selector for the /fork command. It shows only user messages (flat list) matching Pi's fork behavior.
func (*TreeSelectorComponent) Init ¶
func (ts *TreeSelectorComponent) Init() tea.Cmd
Init implements tea.Model.
func (*TreeSelectorComponent) IsActive ¶
func (ts *TreeSelectorComponent) IsActive() bool
IsActive returns whether the tree selector is still accepting input.
func (*TreeSelectorComponent) RenderOverlay ¶ added in v0.90.0
func (ts *TreeSelectorComponent) RenderOverlay() string
RenderOverlay returns the selector as a bare box, ready to be composited over the main view so the conversation stays visible behind it.
func (*TreeSelectorComponent) View ¶
func (ts *TreeSelectorComponent) View() tea.View
View implements tea.Model.
type UIMessage ¶
type UIMessage struct {
ID string
Type MessageType
Position int
Height int
Content string
Timestamp time.Time
Streaming bool
}
UIMessage encapsulates a fully rendered message ready for display in the UI, including its formatted content, display metrics, and metadata. Messages can be static or streaming (progressively updated).
type UIVisibility ¶ added in v0.3.0
type UIVisibility struct {
HideStartupMessage bool // Hide the "Model loaded..." startup block
HideStatusBar bool // Hide the "~/path (branch) ... provider · model" line
HideSeparator bool // Hide the queued/steering count above the composer
// HideInputHint is retained for compatibility and has no effect. The
// submit hint is no longer a separate line below the composer; it lives
// in the placeholder and disappears as soon as the user types.
HideInputHint bool
}
UIVisibility controls which built-in TUI chrome elements are visible. The zero value shows everything (backward compatible).
type UsageStats ¶
type UsageStats struct {
InputTokens int
OutputTokens int
CacheReadTokens int
CacheWriteTokens int
InputCost float64
OutputCost float64
CacheReadCost float64
CacheWriteCost float64
TotalCost float64
}
UsageStats encapsulates detailed token usage and cost breakdown for a set of LLM request/response cycles, including input, output, and cache token counts along with their associated costs. Used both for per-turn accumulation and as a generic usage container.
type UsageTracker ¶
type UsageTracker struct {
// contains filtered or unexported fields
}
UsageTracker monitors and accumulates token usage statistics and associated costs for LLM interactions throughout a session. It provides real-time usage information and supports both estimated and actual token counts. OAuth users see $0 costs.
func CreateUsageTracker ¶
func CreateUsageTracker(modelString, providerAPIKey string) *UsageTracker
CreateUsageTracker creates a UsageTracker for the given model string and provider API key. It returns nil when usage tracking is unavailable (e.g. ollama or unrecognised models). This is used by the interactive TUI path which doesn't go through SetupCLI.
func NewUsageTracker ¶
func NewUsageTracker(modelInfo *models.ModelInfo, provider string, width int, isOAuth bool) *UsageTracker
NewUsageTracker creates and initializes a new UsageTracker for the specified model. The tracker uses model-specific pricing information to calculate costs, unless OAuth credentials are being used (in which case costs are shown as $0). Width determines the display formatting.
func (*UsageTracker) EstimateAndUpdateUsage ¶
func (ut *UsageTracker) EstimateAndUpdateUsage(inputText, outputText string)
EstimateAndUpdateUsage estimates token counts from raw text strings and updates the usage statistics. This method is used when actual token counts are not available from the API response. The estimated values also serve as the context utilization approximation since they represent a single API call.
func (*UsageTracker) GetSessionStats ¶
func (ut *UsageTracker) GetSessionStats() SessionStats
GetSessionStats returns a copy of the cumulative session statistics including total token counts, costs, and request count. The returned copy is safe to use without additional synchronization.
func (*UsageTracker) GetTurnStats ¶ added in v0.91.0
func (ut *UsageTracker) GetTurnStats() *UsageStats
GetTurnStats returns a copy of the usage statistics accumulated during the current (or most recently completed) turn, or nil if no usage has been recorded. A turn spans every LLM request in one tool-calling loop, so the returned totals cover all steps. The copy is safe to use without additional synchronization.
func (*UsageTracker) IsOAuth ¶ added in v0.91.0
func (ut *UsageTracker) IsOAuth() bool
IsOAuth reports whether the tracker is running against an OAuth credential (e.g. a Claude subscription) rather than a per-token billed API key. Under OAuth all recorded costs are 0 by design, so callers rendering cost need this flag to distinguish "not billed" from "nothing spent yet".
func (*UsageTracker) RenderUsageInfo ¶
func (ut *UsageTracker) RenderUsageInfo() string
RenderUsageInfo generates a formatted string displaying current usage statistics including token counts, context utilization percentage, and costs. The display adapts colors based on usage levels and formats large numbers with K/M suffixes for readability.
func (*UsageTracker) Reset ¶
func (ut *UsageTracker) Reset()
Reset clears all accumulated usage statistics, resetting both session totals and current-turn information to their initial empty state. This is typically used when starting a new conversation or clearing usage history.
func (*UsageTracker) SetContextTokens ¶
func (ut *UsageTracker) SetContextTokens(tokens int)
SetContextTokens records the approximate current context window utilization.
The value should include ALL token categories from the last API call:
InputTokens + CacheReadTokens + CacheCreationTokens + OutputTokens
With Anthropic prompt caching, InputTokens can be near-zero while CacheReadTokens holds the bulk of the context. All four must be summed to get the true context window fill level.
OutputTokens is included because the assistant's output becomes part of the context on the next turn.
Use FinalResponse.Usage (last step only) rather than aggregate TotalUsage, because TotalUsage sums across all tool-calling steps and overstates the actual window fill level.
The value is set unconditionally (not max-only) so that context shrinks correctly after compaction.
func (*UsageTracker) SetUsageUnreported ¶ added in v0.84.0
func (ut *UsageTracker) SetUsageUnreported(unreported bool)
SetUsageUnreported records whether the active provider failed to report token usage on the most recent turn. When set to true, RenderUsageInfo displays a muted "⚠ usage not reported by provider" notice instead of a bare zero. The app layer calls this once per turn from updateUsageFromTurnResult, passing false when any real usage was observed (via StepUsageEvent callbacks or TurnResult.TotalUsage) and true otherwise.
func (*UsageTracker) SetWidth ¶
func (ut *UsageTracker) SetWidth(width int)
SetWidth updates the terminal width used for formatting usage information display. This should be called when the terminal is resized to ensure proper text wrapping and alignment.
func (*UsageTracker) StartTurn ¶ added in v0.91.0
func (ut *UsageTracker) StartTurn()
StartTurn marks the beginning of a new turn, clearing usage accumulated for the previous one while preserving session totals. Called by the app layer before dispatching a prompt to the SDK.
func (*UsageTracker) UpdateModelInfo ¶ added in v0.23.0
func (ut *UsageTracker) UpdateModelInfo(modelInfo *models.ModelInfo, provider string, isOAuth bool)
UpdateModelInfo updates the model information and OAuth status when the model is switched mid-session. This ensures token costs and context limits are calculated correctly for the new model.
func (*UsageTracker) UpdateUsage ¶
func (ut *UsageTracker) UpdateUsage(inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens int)
UpdateUsage records new token usage data and calculates associated costs based on the model's pricing. Updates both the current turn's statistics and cumulative session totals. For OAuth users, costs are recorded as $0 while still tracking token counts.
Turn statistics accumulate across calls; callers signal a turn boundary with StartTurn.
type WidgetData ¶ added in v0.2.0
type WidgetData struct {
// ID uniquely identifies the widget. Used to key the animation render
// cache; empty for header/footer, which get synthetic keys.
ID string
// Text is the content to display. Ignored when Render is non-nil.
Text string
// Markdown, when true, renders Text as styled markdown.
Markdown bool
// Render, if non-nil, produces the widget body per frame from the
// content width. Its output is used verbatim.
Render func(width int) string
// RefreshHz, when > 0, asks the shared animation clock to keep running
// so the widget repaints continuously. It also bounds how often Render
// is actually invoked. Zero means a static widget.
RefreshHz int
// BorderColor is a hex color (e.g. "#a6e3a1") for the left border.
// Empty uses the theme's default accent color.
BorderColor string
// NoBorder disables the left border entirely.
NoBorder bool
}
WidgetData is the UI-layer representation of an extension widget. It decouples the UI package from the extensions package. The CLI layer converts extension WidgetConfig values to WidgetData for rendering.
Source Files
¶
- activity.go
- block_renderer.go
- cli.go
- composite.go
- event_handler.go
- exports.go
- ext_event_dispatcher.go
- factory.go
- file_suggestions.go
- format.go
- frameclock.go
- fuzzy.go
- input.go
- message_items.go
- message_nav.go
- messages.go
- model.go
- model_selector.go
- overlay.go
- popup_list.go
- prompt.go
- scrolllist.go
- session_selector.go
- spinner.go
- stream.go
- tool_renderers.go
- tree_selector.go
- usage_tracker.go
Directories
¶
| Path | Synopsis |
|---|---|
|
Package imagepreview renders low-resolution, in-terminal thumbnails of images using Unicode upper half-block characters (U+2580, "▀") combined with SGR foreground/background color codes.
|
Package imagepreview renders low-resolution, in-terminal thumbnails of images using Unicode upper half-block characters (U+2580, "▀") combined with SGR foreground/background color codes. |
|
Package render provides pure rendering functions for message blocks.
|
Package render provides pure rendering functions for message blocks. |
|
Package selection provides character-level text selection for terminal UIs.
|
Package selection provides character-level text selection for terminal UIs. |