tui

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 14, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package tui implements Codog's Bubble Tea terminal interface.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ConfirmWorkspaceTrust

func ConfirmWorkspaceTrust(ctx context.Context, workspace string) (bool, error)

ConfirmWorkspaceTrust asks whether project files may participate in the interactive agent runtime. Escape, explicit rejection, and a confirmed Ctrl-C exit deny access.

func ConfirmWorkspaceTrustWithTheme

func ConfirmWorkspaceTrustWithTheme(ctx context.Context, workspace string, theme string) (bool, error)

ConfirmWorkspaceTrustWithTheme asks for workspace trust using the configured terminal theme.

func NormalizeThemeName

func NormalizeThemeName(name string) (string, bool)

NormalizeThemeName canonicalizes supported theme names and legacy aliases. The second return value is false for unknown names.

func SelectSession

func SelectSession(ctx context.Context, choices []SessionChoice) (string, error)

SelectSession opens an inline, searchable saved-session picker. An empty result means the user canceled the picker.

func SelectSessionWithTheme

func SelectSessionWithTheme(ctx context.Context, choices []SessionChoice, theme string) (string, error)

SelectSessionWithTheme opens the saved-session picker with the configured terminal theme. An empty result means the user canceled the picker.

func SelectTheme

func SelectTheme(ctx context.Context, current string, intro bool) (string, bool, error)

SelectTheme opens an inline theme picker. Moving the selection previews the palette; Enter accepts it and Escape cancels without selecting a theme.

func Shell

func Shell(ctx context.Context, options ShellOptions) error

Shell starts the interactive TUI loop.

func ThemeNames

func ThemeNames() []string

ThemeNames returns the themes offered by the interactive theme picker.

Types

type BackgroundFunc

type BackgroundFunc func(context.Context, string) (string, error)

BackgroundFunc starts the current composer prompt in a detached background task and returns a user-facing status line.

type CommandView

type CommandView struct {
	Title        string
	Tabs         []CommandViewTab
	SelectedTab  int
	SelectedItem int
}

CommandView is a tabbed local-command panel with optional actions.

type CommandViewItem

type CommandViewItem struct {
	Label            string
	Value            string
	Description      string
	Action           string
	Command          string
	SecondaryLabel   string
	SecondaryAction  string
	SecondaryCommand string
	SecondaryKey     string
}

CommandViewItem is one selectable action in a CommandView tab.

type CommandViewTab

type CommandViewTab struct {
	Title          string
	Lines          []string
	Items          []CommandViewItem
	RefreshCommand string
}

CommandViewTab is one tab in a CommandView.

type ConversationExportFunc

type ConversationExportFunc func(context.Context, string) (RuntimeControlResult, error)

ConversationExportFunc saves the active conversation to a user-selected path.

type ConversationForkFunc

type ConversationForkFunc func(context.Context, int) (RuntimeControlResult, error)

type ConversationRestoreFunc

type ConversationRestoreFunc func(context.Context, int) (RuntimeControlResult, error)

type ConversationSummarizeFunc

type ConversationSummarizeFunc func(context.Context, int) (RuntimeControlResult, error)

type DiffFile

type DiffFile struct {
	Path    string
	Status  string
	Summary string
	Diff    string
}

DiffFile describes one changed file rendered by the TUI diff dialog.

type DiffSource

type DiffSource struct {
	Name     string
	Subtitle string
	Files    []DiffFile
}

DiffSource describes one diff source rendered by the TUI diff dialog.

type DiffView

type DiffView struct {
	Sources []DiffSource
}

DiffView is a file-oriented diff browser opened by a slash command.

type Entry

type Entry struct {
	Role       string
	Text       string
	Permission *PermissionRequest
	Question   *QuestionRequest
	Tool       *ToolActivity
}

Entry is one transcript item rendered by the interactive TUI shell.

type ExportDialog

type ExportDialog struct {
	DefaultFilename string
}

ExportDialog describes the initial state of the conversation export dialog.

type ExternalEditorFunc

type ExternalEditorFunc func(context.Context, string) (string, error)

ExternalEditorFunc edits the current composer value outside the TUI and returns the replacement composer text.

type InformationView

type InformationView struct {
	Title            string
	Lines            []string
	DismissOnConfirm bool
}

InformationView is a scrollable read-only panel opened by a slash command.

type MessageCopyFunc

type MessageCopyFunc func(context.Context, string) (RuntimeControlResult, error)

type ModelSelectFunc

type ModelSelectFunc func(context.Context, string) (RuntimeControlResult, error)

type PasteContent

type PasteContent struct {
	Text           string
	AttachmentPath string
	MediaType      string
}

PasteContent is clipboard content ready for the TUI composer. Text is inserted into the composer; AttachmentPath is staged for the next prompt.

type PasteFunc

type PasteFunc func(context.Context) (PasteContent, error)

PasteFunc returns the current system clipboard content for insertion into the composer or staging as an attachment.

type PermissionModeOption

type PermissionModeOption struct {
	Name        string
	Label       string
	Description string
	Current     bool
}

PermissionModeOption is one session permission mode shown in the interactive permissions panel.

type PermissionModeSelectFunc

type PermissionModeSelectFunc func(context.Context, string) (RuntimeControlResult, error)

PermissionModeSelectFunc applies one permission mode to the current shell.

type PermissionRequest

type PermissionRequest struct {
	Tool          string
	Required      string
	Input         string
	Message       string
	SuggestedRule string
	AllowAlways   bool
}

PermissionRequest describes a tool confirmation shown by the interactive shell. Text remains available on Entry as a transcript fallback.

type PermissionResponse

type PermissionResponse struct {
	Decision string
	Feedback string
	Rule     string
}

PermissionResponse is the user's structured answer to a permission request.

type PermissionSettings

type PermissionSettings struct {
	Modes []PermissionModeOption
	Allow []string
	Ask   []string
	Deny  []string
}

PermissionSettings describes the current session modes and configured tool rules shown by the interactive permissions panel.

type Preview

type Preview struct {
	View            string
	Value           string
	Matches         []string
	Submitted       bool
	Prompt          string
	Attachments     []string
	Mode            string
	HelpOpen        bool
	HasStash        bool
	Transcript      bool
	QuickOpen       bool
	GlobalSearch    bool
	TodosOpen       bool
	ModelPicker     bool
	ThemePicker     bool
	MessageMenu     bool
	AttachmentsOpen bool
	DiffDialog      bool
	InformationView bool
	CommandView     bool
	ExportDialog    bool
	TextInputDialog bool
	CommandHint     string
	InlineHint      string
	Quit            bool
}

Preview captures a deterministic TUI model state for tests and parity harnesses without taking over the terminal.

func PreviewInlineWithCandidates

func PreviewInlineWithCandidates(input string, candidates []string, width int, height int, complete bool, submit bool) Preview

PreviewInlineWithCandidates renders the default inline shell presentation without starting a terminal program.

func PreviewWithAttachmentNavigation

func PreviewWithAttachmentNavigation(input string, attachments []string, keys []string, width int, height int) Preview

PreviewWithAttachmentNavigation renders the TUI attachment selector after opening it and applying the provided navigation keys.

func PreviewWithAttachmentRemoval

func PreviewWithAttachmentRemoval(input string, attachments []string, width int, height int) Preview

PreviewWithAttachmentRemoval renders the TUI after removing the most recent pending attachment through the keyboard chord.

func PreviewWithAttachments

func PreviewWithAttachments(input string, attachments []string, width int, height int) Preview

PreviewWithAttachments renders a deterministic TUI state with pending attachments staged for the next user prompt.

func PreviewWithBashHistory

func PreviewWithBashHistory(input string, history []string, files []string, width int, height int, complete bool) Preview

PreviewWithBashHistory renders bash history ghost completion for tests and parity harnesses.

func PreviewWithBashMode

func PreviewWithBashMode(input string, width int, height int) Preview

PreviewWithBashMode renders the TUI after submitting a leading ! command. The command is routed through the same slash dispatcher used by /run.

func PreviewWithCandidates

func PreviewWithCandidates(input string, candidates []string, width int, height int, complete bool, submit bool) Preview

PreviewWithCandidates renders the Bubble Tea prompt model after applying optional input, window sizing, tab completion, and submission.

func PreviewWithCommandView

func PreviewWithCommandView(view CommandView, keys []string, width int, height int) Preview

PreviewWithCommandView renders a deterministic tabbed command panel after applying the provided navigation keys.

func PreviewWithContextKeybindings

func PreviewWithContextKeybindings(target string, bindings map[string]map[string][]string, keys []string, width int, height int) Preview

PreviewWithContextKeybindings renders a deterministic modal state after applying custom keybindings for TUI sub-contexts such as tui-modal, tui-attachments, and tui-diff.

func PreviewWithDiffDialog

func PreviewWithDiffDialog(sources []DiffSource, keys []string, width int, height int) Preview

PreviewWithDiffDialog renders a deterministic TUI diff dialog after applying the provided navigation keys.

func PreviewWithEscape

func PreviewWithEscape(input string, presses int, width int, height int) Preview

PreviewWithEscape renders the TUI after pressing Escape the requested number of times. It is used to verify safe clear and message-action behavior without owning a terminal.

func PreviewWithExportDialog

func PreviewWithExportDialog(dialog ExportDialog, keys []string, width int, height int) Preview

PreviewWithExportDialog renders a deterministic conversation export dialog after applying the provided navigation keys.

func PreviewWithFileCandidates

func PreviewWithFileCandidates(input string, files []string, width int, height int, complete bool) Preview

PreviewWithFileCandidates renders a deterministic TUI state with @file reference suggestions.

func PreviewWithGlobalSearch

func PreviewWithGlobalSearch(input string, files []string, query string, width int, height int, accept bool) Preview

PreviewWithGlobalSearch renders a deterministic TUI state after opening workspace search, typing a query, and optionally accepting the selected match.

func PreviewWithInformation

func PreviewWithInformation(view InformationView, keys []string, width int, height int) Preview

PreviewWithInformation renders a deterministic read-only information panel.

func PreviewWithKeybindings

func PreviewWithKeybindings(input string, bindings map[string][]string, files []string, key string, width int, height int) Preview

PreviewWithKeybindings renders a deterministic TUI state after applying a custom TUI keybinding or keybinding chord.

func PreviewWithMessageActionTarget

func PreviewWithMessageActionTarget(entries []Entry, width int, height int, action int, targetDelta int) Preview

PreviewWithMessageActionTarget renders message actions after moving the selected target message by targetDelta steps.

func PreviewWithMessageActions

func PreviewWithMessageActions(entries []Entry, width int, height int, action int) Preview

PreviewWithMessageActions renders a deterministic TUI state after opening the transcript message action menu.

func PreviewWithModelPicker

func PreviewWithModelPicker(input string, models []string, current string, width int, height int, accept bool) Preview

PreviewWithModelPicker renders a deterministic TUI state after opening the runtime model picker.

func PreviewWithPaste

func PreviewWithPaste(input string, clipboardText string, width int, height int) Preview

PreviewWithPaste renders a deterministic TUI state after inserting clipboard text into the composer.

func PreviewWithPasteAttachment

func PreviewWithPasteAttachment(input string, attachmentPath string, width int, height int) Preview

PreviewWithPasteAttachment renders a deterministic TUI state after staging a clipboard attachment for the next prompt.

func PreviewWithQueued

func PreviewWithQueued(input string, queued []string, width int, height int) Preview

PreviewWithQueued renders a deterministic busy TUI state with queued prompts for tests and parity harnesses.

func PreviewWithQuickOpen

func PreviewWithQuickOpen(input string, files []string, query string, width int, height int, accept bool) Preview

PreviewWithQuickOpen renders a deterministic TUI state after opening the file picker, typing a query, and optionally accepting the selected file.

func PreviewWithRuntimeControl

func PreviewWithRuntimeControl(input string, key string, result RuntimeControlResult, width int, height int) Preview

PreviewWithRuntimeControl renders a deterministic TUI state after invoking a runtime control shortcut.

func PreviewWithRuntimeToggle

func PreviewWithRuntimeToggle(input string, key string, result RuntimeControlResult, width int, height int) Preview

PreviewWithRuntimeToggle renders a deterministic TUI state after invoking a runtime control shortcut such as Alt-O or Alt-T.

func PreviewWithStash

func PreviewWithStash(input string, attachments []string, width int, height int) Preview

PreviewWithStash renders a deterministic TUI state after stashing the current composer draft.

func PreviewWithTextInputDialog

func PreviewWithTextInputDialog(dialog TextInputDialog, keys []string, width int, height int) Preview

PreviewWithTextInputDialog renders a deterministic local text-input workflow.

func PreviewWithTodos

func PreviewWithTodos(input string, items []TodoItem, width int, height int) Preview

PreviewWithTodos renders a deterministic TUI state after toggling the todo panel with the provided items.

func PreviewWithTranscript

func PreviewWithTranscript(entries []Entry, width int, height int) Preview

PreviewWithTranscript renders a deterministic TUI state after switching the viewport into expanded transcript mode.

func PreviewWithUndo

func PreviewWithUndo(input string, inserted string, width int, height int) Preview

PreviewWithUndo renders a deterministic TUI state after editing the composer and invoking the undo shortcut.

func PreviewWithVimMode

func PreviewWithVimMode(input string, keys []string, width int, height int) Preview

PreviewWithVimMode renders a deterministic TUI state after applying vim editor-mode keys.

type Question

type Question struct {
	Question    string
	Header      string
	Options     []QuestionOption
	MultiSelect bool
}

Question is one tab in a structured user-question interaction.

type QuestionOption

type QuestionOption struct {
	Label       string
	Description string
	Preview     string
}

QuestionOption is one selectable answer and its supporting context.

type QuestionRequest

type QuestionRequest struct {
	Question  string
	Choices   []string
	Default   string
	Questions []Question
}

QuestionRequest describes a structured AskUserQuestionTool interaction.

type Result

type Result struct {
	Submitted   bool
	Prompt      string
	Attachments []string
}

func Prompt

func Prompt() (Result, error)

func PromptWithCandidates

func PromptWithCandidates(candidates []string) (Result, error)

func PromptWithCandidatesPrefill

func PromptWithCandidatesPrefill(candidates []string, prefill string) (Result, error)

type RuntimeControlFunc

type RuntimeControlFunc func(context.Context) (RuntimeControlResult, error)

type RuntimeControlResult

type RuntimeControlResult struct {
	Title      string
	Status     string
	Lines      []string
	Badges     []string
	Setting    string
	Value      string
	VimEnabled *bool
}

RuntimeControlResult describes a runtime TUI setting change.

type SessionChoice

type SessionChoice struct {
	ID           string
	Title        string
	Tag          string
	BranchName   string
	Workspace    string
	MessageCount int
	UpdatedAt    time.Time
}

SessionChoice is one saved conversation shown by the resume picker.

type SessionPickerPreview

type SessionPickerPreview struct {
	View       string
	Query      string
	MatchCount int
	SelectedID string
}

SessionPickerPreview captures deterministic resume-picker state for tests and capability reporting without owning a terminal.

func PreviewSessionPicker

func PreviewSessionPicker(choices []SessionChoice, query string, width int, height int, selectMatch bool) SessionPickerPreview

PreviewSessionPicker filters and optionally selects a saved session.

type SessionState

type SessionState struct {
	ID         string
	Entries    []Entry
	History    []string
	Candidates []string
}

SessionState is a saved conversation loaded by a slash command. Applying it replaces the visible transcript and prompt history atomically.

type ShellOptions

type ShellOptions struct {
	Candidates                []string
	FileCandidates            []string
	Prefill                   string
	InitialPrompt             string
	InitialAttachments        []string
	History                   []string
	Entries                   []Entry
	Submit                    SubmitFunc
	SubmitStream              StreamSubmitFunc
	SubmitAttachments         SubmitWithAttachmentsFunc
	SubmitStreamAttachments   StreamSubmitWithAttachmentsFunc
	Slash                     SlashFunc
	SubmitTextInput           TextInputSubmitFunc
	PermissionAnswer          func(string)
	PermissionRespond         func(PermissionResponse)
	QuestionAnswer            func(string)
	ExternalEditor            ExternalEditorFunc
	Paste                     PasteFunc
	Background                BackgroundFunc
	TaskBoard                 TaskBoardFunc
	Todos                     TodoListFunc
	ModelOptions              []string
	CurrentModel              string
	SelectModel               ModelSelectFunc
	SelectPermissionMode      PermissionModeSelectFunc
	Theme                     string
	SelectTheme               ThemeSelectFunc
	ToggleFast                RuntimeControlFunc
	ToggleThinking            RuntimeControlFunc
	ToggleVim                 RuntimeControlFunc
	StopBackground            RuntimeControlFunc
	CompactSession            RuntimeControlFunc
	UndoLast                  RuntimeControlFunc
	ExportConversation        RuntimeControlFunc
	ExportConversationTo      ConversationExportFunc
	CopyConversation          RuntimeControlFunc
	RestoreConversation       ConversationRestoreFunc
	ForkConversation          ConversationForkFunc
	SummarizeConversation     ConversationSummarizeFunc
	SummarizeUpToConversation ConversationSummarizeFunc
	CopyMessage               MessageCopyFunc
	ModeLabel                 string
	RuntimeBadges             []string
	VimMode                   bool
	Keybindings               map[string][]string
	ContextKeybindings        map[string]map[string][]string
	CycleMode                 func() string
	ReadModeLabel             func() string
	// FullScreen opts into the alternate-screen renderer. The default inline
	// renderer keeps completed conversation turns in terminal scrollback.
	FullScreen bool
}

ShellOptions configures the interactive TUI shell.

type SlashFunc

type SlashFunc func(context.Context, string) (SlashResult, error)

SlashFunc runs one local slash command. Structured result fields let the shell open interactive views without parsing display text.

type SlashResult

type SlashResult struct {
	Output             string
	Query              string
	Handled            bool
	Session            *SessionState
	SessionChoices     []SessionChoice
	OpenModelPicker    bool
	OpenThemePicker    bool
	OpenTodos          bool
	OpenMessageActions bool
	RuntimeAction      string
	Diff               *DiffView
	PermissionSettings *PermissionSettings
	Information        *InformationView
	CommandView        *CommandView
	ExportDialog       *ExportDialog
	TextInputDialog    *TextInputDialog
}

SlashResult is the structured outcome of one local slash command.

type StreamSubmitFunc

type StreamSubmitFunc func(context.Context, string, func(Entry)) (string, error)

StreamSubmitFunc runs one user prompt and can emit assistant deltas while the turn is still running.

type StreamSubmitWithAttachmentsFunc

type StreamSubmitWithAttachmentsFunc func(context.Context, string, []string, func(Entry)) (string, error)

StreamSubmitWithAttachmentsFunc runs one user prompt with staged local attachments and can emit assistant deltas while the turn is still running.

type SubmitFunc

type SubmitFunc func(context.Context, string) (string, error)

SubmitFunc runs one user prompt and returns assistant output to append to the transcript.

type SubmitWithAttachmentsFunc

type SubmitWithAttachmentsFunc func(context.Context, string, []string) (string, error)

SubmitWithAttachmentsFunc runs one user prompt with staged local attachments.

type TaskBoardFunc

type TaskBoardFunc func(context.Context) (string, error)

TaskBoardFunc returns a user-facing snapshot of detached background tasks.

type TextInputDialog

type TextInputDialog struct {
	Title        string
	Prompt       string
	InitialValue string
	Action       string
}

TextInputDialog describes a local workflow that needs one line of user input.

type TextInputSubmitFunc

type TextInputSubmitFunc func(context.Context, string, string) (RuntimeControlResult, error)

type ThemeSelectFunc

type ThemeSelectFunc func(context.Context, string) (RuntimeControlResult, error)

ThemeSelectFunc persists a theme selected from the live TUI picker.

type TodoItem

type TodoItem struct {
	ID         string
	Content    string
	ActiveForm string
	Status     string
	Priority   string
}

TodoItem is the small display model used by the TUI todo panel.

type TodoListFunc

type TodoListFunc func(context.Context) ([]TodoItem, error)

TodoListFunc returns the current workspace todo list for the TUI task panel.

type ToolActivity

type ToolActivity struct {
	ID      string
	Name    string
	Input   string
	Output  string
	Status  string
	IsError bool
}

ToolActivity is one model-requested tool call as it moves from running to a terminal success or error state.

type WorkspaceTrustPreview

type WorkspaceTrustPreview struct {
	View           string
	SelectedChoice int
}

WorkspaceTrustPreview is a deterministic trust prompt snapshot used by capability checks without taking control of a terminal.

func PreviewWorkspaceTrust

func PreviewWorkspaceTrust(workspace string, width int) WorkspaceTrustPreview

PreviewWorkspaceTrust renders the workspace trust prompt at a fixed width.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL