TUI¶

The terminal UI is the default way to use Pegg. Launch it with pegg on a terminal, or explicitly with pegg tui.

Layout¶

┌──────────────────────────────────────────────────────────┐
│                                                          │
│                    chat transcript                       │
│        (streaming markdown, tool cards, diffs)           │
│                                                          │
├──────────────────────────────────────────────────────────┤
│  attachments                                             │
├──────────────────────────────────────────────────────────┤
│  > input editor                                          │
├──────────────────────────────────────────────────────────┤
│  ● gpt-4o/openai · 12.4K (6%) · $0.0021 · Ctrl+P         │
└──────────────────────────────────────────────────────────┘

• Chat transcript — user cards, assistant markdown, thinking blocks, tool cards, and subagent cards. With an empty chat, an animated Pegg logo is shown.
• Attachment bar — appears only when files are attached.
• Input editor — up to 6 rows tall, with inline chips for skills, mentions, and long pasted text.
• Status bar — a running indicator (●), the active model as name/provider, reasoning effort when set, context usage, session cost, and a Ctrl+P hint.
• Hint line — transient errors and the Press Esc to interrupt hint.

Global keys¶

Interrupting the agent¶

While a run is active, pressing Esc once shows Press Esc to interrupt. Pressing Esc again within 2 seconds cancels the run and all subagents. Pressing it once and waiting lets the run continue.

When the chat has focus, Esc returns focus to the input. While viewing a subagent transcript, Esc goes back to the main chat.

Input editor¶

Skills (/name), mentions (@name), and long pasted text are atomic chips: cursor movement and deletion treat each chip as a single unit.

Skills and mentions¶

Type / at the start of a word to open the skill picker, or @ to open the mention picker. Both are fuzzy-filtered as you type.

• /skill inserts a skill chip that is expanded to the skill's instructions before the message reaches the model. See Skills.
• @name inserts a mention chip for an agent, file, folder, or attachment. Mentions are sent to the model as literal @name text for it to interpret. See Adding Context.

Pasting and attachments¶

There is no system-clipboard integration; pasting uses the terminal's bracketed paste. When you paste:

• A single line that is an existing file path is attached as a file.
• In a multi-line paste, every line that is an existing file path is attached.
• Text longer than 100 characters is inserted as a collapsible long text chip.

Attachments appear in the attachment bar with type icons (image, audio, file) and pagination dots. Focus the bar with Tab, navigate with Left/Right, and remove with Backspace or Del.

Image and audio attachments are rejected if the active model's metadata does not list that input modality.

Chat items¶

Specialized tool cards¶

• BASH — command header, syntax-highlighted output (30 lines collapsed), exit code footer.
• DIFF — unified diff for edit calls with added/removed highlighting and a +N -M summary.
• WRITE — syntax-highlighted file content for write calls.
• TODO — parsed todo list with status icons and an N / M completed footer.
• ASK — question/answer pairs collected from the user.

Fenced code in assistant messages is syntax-highlighted for Go, TypeScript, JavaScript, Python, Rust, Bash, C/C++, Ruby, PHP, Swift, Kotlin, Scala, Elixir, Haskell, CSS, HTML, JSON, YAML, Markdown, SQL, R, Lua, and Dart.

Tool card keys¶

Subagents¶

Running and finished subagents appear as cards in the main transcript. Select a running subagent and press Enter, or click History, to open its live transcript. Press Esc or click the back header to return. See Subagents.

Settings¶

Open with Ctrl+P. The overlay has nine tabs; switch with Left/Right when the tab bar is focused. Press Down to enter the tab content, Up to return to the tab bar.

• Provider — configure an existing provider again or add a new one by pasting an API key into a masked field.
• Model — type to filter; the active model is marked with ●. When the smart router is enabled, a Smart Router entry appears at the top of the list: it auto-selects the best model for each task and agent at run time.
• Reasoning — available only for models that advertise reasoning options.
• Session → Load — sessions from the current directory, newest first. Loading restores the last 50 messages; scrolling to the top loads older messages in batches of 50.
• Session → Delete — asks for confirmation before permanently removing the session.
• Session → Change title — edit the generated session title.
• Session → Compaction — configure context compaction (see below).

Compaction settings¶

Below the session management rows, the Session tab includes compaction configuration. Navigate to a row with Up/Down. Toggle switches (Enabled and the strategy checkboxes) with Enter or Left/Right; adjust numeric values with Left/Right:

Strategies are independent checkboxes: any combination is allowed, including none (compaction then does nothing until a strategy is re-enabled).

Changes save immediately to ~/.peggco/pegg.json.

Compaction persistence¶

Compaction does not destroy your history. When the context is compacted, the compacted messages are saved to a new session linked to the current one, forming a chain. The original session keeps every message it had; the newest session in the chain holds the compacted view plus everything said afterwards.

• Loading a session always opens the newest session in its chain — you see the latest compacted conversation first.
• Scrolling to the top of the transcript loads the earlier (pre-compaction) conversation, marked with an ─ context compacted ─ divider, and keeps walking back through the chain as you continue scrolling.
• Resuming a session re-applies compaction to the loaded history (sliding-window and tool-clearing), so resumed conversations stay within the context budget.
• While chatting, a compacted run shows a ↻ Context compacted (...) item in the transcript.

Permissions tab¶

The Permissions tab has its own internal navigation. When focused on the tab bar, Left/Right switches tabs. Press Down to enter the presets, Down again to reach the Judge model row, Down again for the Threshold row, and Down a fourth time to reach the tool list. In the tool list, Left/Right cycles the permission mode for the selected tool. Up from presets returns to the tab bar.

Press Enter on the Judge model row to pick which model judges tool calls. The picker lists decision models first (JEV via OpenRouter, marked with the provider and a decision suffix), then every available LLM model across your configured providers. Selecting one writes judge_provider / judge_model to ~/.peggco/pegg.json; choosing a decision model also enables the decision judge by default. See Permissions.

The Threshold row adjusts the decision judge's minimum yes-probability (judge_threshold): Left/Right step it by 0.05, clamped between 0.05 and 1.0, and the value is saved immediately. The row is disabled (and labeled decision only) when the judge provider is not decision-capable.

Memory tab¶

The Memory tab configures the markdown-based memory system. Press Down to enter the rows, Up/Down to navigate, and Enter or Left/Right to toggle switches and adjust values:

All changes save immediately to ~/.peggco/pegg.json and apply live.

System tab¶

The System tab displays application information (name, version, OS, architecture) and a Check for updates button. Navigate to the button with Down and press Enter to check for a newer version. Status messages appear below the button: "Checking...", "Already up to date", or an error. If an update is available, the update modal opens automatically.

Themes¶

Pegg ships 26 themes: dark (default), light, dracula, catppuccin-mocha, catppuccin-latte, catppuccin-frappe, catppuccin-macchiato, tokyonight-storm, tokyonight-night, tokyonight-day, gruvbox-dark, gruvbox-light, nord, onedark, solarized-dark, solarized-light, rosepine, rosepine-moon, rosepine-dawn, monokai, monokai-night, monokai-spectrum, kanagawa, kanagawa-dragon, everforest-dark, and everforest-light.

Press Ctrl+T to cycle themes alphabetically, or pick one in Settings → General → Theme. The choice is saved to the theme key in ~/.peggco/pegg.json.

Notifications¶

• Update modal — shown at startup when a newer release exists, with Update / Later buttons (Left/Right to choose, Enter to confirm, Esc to skip).
• Errors — appended to the transcript or shown on the hint line.
• Transient messages — retry progress (Request failed ... retrying in Xs) and the Esc interrupt hint appear above the status bar.
• Desktop notifications — permission prompts, agent completions, and agent errors raise an OS notification while the window is in the background. See Notifications.

Session behavior¶

Each submitted message resumes the active session; if none is active, one is created automatically and titled by a background model call. See Sessions.

Limitations¶

• No system clipboard copy/paste — use the terminal's own selection.
• No session fork or revert from the UI (available programmatically via the SDK).
• No command palette; Settings (Ctrl+P) and the inline / and @ pickers cover the same ground.