Interactive TUI Guide

The TUI is the CLI's interactive face — a terminal dashboard that combines AI chat, real-time job monitoring, and result visualization for drug discovery workflows. Reach for it when you want a conversational, keyboard-driven session rather than one-off scripted commands, all without leaving your terminal. It runs against the same backend and job history as the rest of the CLI and the web platform, so your sessions and jobs stay in sync. For the full command set, see the CLI overview.

Interactive TUI Guide

The ivybloom TUI provides a conversational interface for drug discovery workflows, combining AI chat with real-time job monitoring and result visualization.

Launching the TUI

ivybloom

You'll see a splash screen with a command prompt. Type a message or use / commands to navigate.

Interface Layout

The TUI has four main areas:

+------------------+------------------------+------------------+
| Session Sidebar  |    Conversation        |  Context Panel   |
| (Ctrl+S toggle)  |                        |  (Tab toggle)    |
|                  |                        |                  |
| - Sessions list  |  [Assistant response]  |  Files           |
| - Archive/fork   |  [Your message]        |  Jobs            |
|                  |  [Tool progress]       |  Artifacts       |
|                  |                        |  Tool Calls      |
+------------------+------------------------+------------------+
| Input Area                                                   |
| > Type your message here...                    [Model: ...]  |
+--------------------------------------------------------------+
| Status: Connected | Synced | Streaming...                    |
+--------------------------------------------------------------+

Keyboard Shortcuts

Input and Navigation

Panels and Overlays

Triggers

Command Palette

Press Ctrl+P or type / to access the built-in commands organized by category. Additional tool-specific and context-aware commands appear dynamically based on your session state.

Session Commands

Navigation Commands

Job Commands

Data Commands

Settings Commands

Triggers and Mentions

File Attachment (@)

Type @ to open the file picker and attach files to your message:

> Analyze this protein structure @protein.pdb

The file picker shows:

• Project files
• Recent files
• Inbox (auto-discovered files)

Navigate with arrow keys, Enter to select, Esc to cancel.

Actions (!)

Type ! to see available tools and curated actions:

> !esmfold

The actions modal shows:

• Available computational tools
• Suggested actions based on context
• .bloom file suggestions

Inline Commands (/)

Type / for inline command suggestions:

> /jobs

As you type, suggestions filter to match. Use arrow keys to navigate, Enter to execute, Tab to complete.

Context Panel

Toggle with Tab. Shows real-time information about your session:

Files Section

• Currently attached files
• Click to preview or remove

Jobs Section

• Active jobs with live status
• Progress bars and phase indicators
• Click to view details

Artifacts Section

• Generated outputs from completed jobs
• Click to view or download

Tool Calls Section

• Currently executing tools
• Progress and status for each

Tool Approval

Approval gates are not enabled. The TUI runs every tool call as soon as the orchestrator selects it, expensive operations and long-running jobs included, and no approval dialog appears.

Real-Time Streaming

When the AI responds, you'll see:

• Streaming text with animated cursor
• Tool progress cards showing each tool's status
• Live job updates in the context panel

Press Esc to stop streaming.

Connection Status

The status bar shows:

• Connected (green) - SSE connection active
• Reconnecting (yellow) - Attempting to reconnect
• Offline (red) - No connection

The TUI automatically reconnects with exponential backoff.

Pages (Full-Screen Views)

Some commands open full-screen pages with tabbed interfaces:

Jobs Hub (/jobs)

Tabs:

• All Jobs - Every job, with status filters, search and sorting
• Sessions - Recent chat sessions to resume
• Batch - Batch job queues and their progress
• Tools - Browse the tool catalog by category
• Actions - Tool actions from the current conversation

Navigation:

• Tab / Shift+Tab - Switch tabs
• 1-5 - Jump to a tab
• j / k or arrows - Navigate list
• Enter - Select / view details
• Esc - Return to chat

Settings Hub (/settings)

Tabs:

• Account - Profile information
• Display - Theme and animations
• Execution - Execution settings
• General - Core preferences
• LLM Keys - Bring-your-own-key setup
• Service Keys - Manage API keys
• Sessions - Signed-in sessions

Data Hub (/data)

Tabs:

• Files - Uploaded data files
• Exports - Generated exports
• Reports - Analysis reports
• Artifacts - Conversation artifacts such as code and images
• Storage - Workspace storage, when available

Session Management

Session Sidebar

Press Ctrl+S to toggle the session sidebar showing:

• All chat sessions
• Session names and timestamps
• Archive status

Click a session to switch to it.

Session Actions

Conversation Flow

Example: Protein Structure Prediction

You: Predict the structure for this sequence: MKLVFFAEDVGSNKGAIIGLMVGGVVIA

[Tool call: esmfold_predict]
  Status: Running...
  Progress: 45%

[Job completed]
  Artifact: structure.pdb (ready)

Assistant: Your protein structure prediction is complete\! The structure has been saved
as structure.pdb. I found a high-confidence fold with pLDDT score of 89.2.

Would you like me to analyze the structure or run molecular docking?

Example: Multi-Step Workflow

You: I have a new drug candidate. Run ADMET prediction and check for toxicity.

[Tool call: admet_predict]
  Status: Complete
  Results: Good oral bioavailability, low toxicity risk

[Tool call: protox3_predict]
  Status: Running...
  Progress: 78%

Assistant: ADMET results look promising\! The compound shows:
- High intestinal absorption (94%)
- Low CYP inhibition risk
- Favorable LogP (2.3)

ProTox-3 analysis is still running for detailed toxicity profiling.

Theming and Appearance

Customize the TUI appearance via /appearance or config file:

Available Themes

• default - The standard theme
• dark - Dark background with light text
• earth - Earth-tone palette
• acid - High-contrast palette

Settings File

Display settings live in ~/.config/ivybloom/ui_settings.json:

{
  "theme": "dark",
  "animation_style": "spinner",
  "spinner_style": "dots",
  "progress_style": "default",
  "status_icons": "default",
  "enable_animations": true,
  "enable_sounds": false,
  "refresh_rate": 250
}

Individual colors are not configurable; pick a theme instead.

Visualization Features

The TUI includes rich visualizations for scientific data directly in your terminal.

Biological Sequence Display

Color-coded amino acid and nucleotide sequences:

• Hydrophobic (green): A, V, L, I, M, F, W, P
• Polar (cyan): S, T, N, Q, C, G
• Acidic (red): D, E
• Basic (blue): K, R, H
• Aromatic (magenta): Y

BLAST results show conservation indicators (* conserved, : similar) with E-value and identity metrics.

Molecule Property Cards

SMILES structures display with property grids:

+-- Molecule Properties ----------------------+
| SMILES: CCO                                 |
| MW: 46.07  |  LogP: -0.31  |  HBD: 1       |
| HBA: 1     |  RotB: 0      |  TPSA: 20.23  |
| Drug-like: Yes (Lipinski compliant)         |
+---------------------------------------------+

Protein Structure Preview

PDB files render as ASCII structure diagrams with atom counts and chain information.

Workflow Pipeline View

Multi-step workflows display as node graphs:

[ESMFold] ───▶ [DiffDock] ───▶ [ADMET]
    ●              ○              ○
 Complete      Running        Pending

Dashboard Charts

The Jobs Hub (/jobs) shows:

• Pie chart - Job distribution by status
• Sparklines - Quick metric visualization using: ▁▂▃▄▅▆▇█
• Score bars - Gradient color bars (red to green) for ratings

Animation Types

Built-in animations for loading states include:

• Spinner: ⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏
• Pulse: █▉▊▋▌▍▎▏
• Wave: ⠋⠙⠚⠞⠖⠦⠴⠲⠳⠓
• Progress: ▁▃▄▅▆▇█

Artifact Viewer

View results directly in the terminal:

• JSON - Pretty-printed with syntax highlighting
• CSV - Tabular display with headers
• FASTA - Colored sequence blocks
• PDB - Structure summary with chain info

Access via context panel or /artifacts command.

Agent Integration

The TUI integrates with the AI orchestration system to provide a conversational interface for tool execution.

Tool Approval

When the orchestrator selects a tool, it runs without asking: approval gates are not enabled (see Tool Approval).

Streaming Responses

During orchestration, the TUI displays:

• Streaming text with animated cursor as the AI generates its response
• Tool progress cards showing each tool call's status, phase, and progress percentage
• Live job updates in the context panel via SSE (Server-Sent Events)

Press Esc at any time to stop streaming.

Session Persistence

TUI sessions are automatically persisted and can be resumed:

# Resume last session
ivybloom -r last

# Resume a specific session
ivybloom --resume SESSION_ID

Sessions sync to the cloud when authenticated. See Sessions & Checkpoints for checkpoint and rollback capabilities.

Headless Mode

For single messages without launching the full TUI:

ivybloom -m "fold BRCA1"
ivybloom -m "dock erlotinib against EGFR" --follow

See Orchestration for the full AI routing documentation.

Tips and Best Practices

Efficient Navigation

• Use Tab to quickly check job status without leaving the conversation
• Ctrl+P is faster than typing / for frequent commands
• Esc is your universal "go back" key

Working with Files

• Drop files in your project's .ivybloom/inbox/ folder for auto-discovery
• Use @ trigger for quick file attachment
• The context panel shows all attached files

Monitoring Jobs

• Jobs appear in the context panel automatically
• Use /jobs for detailed view with filtering
• SSE provides instant updates (no polling delay)

Keyboard-First Workflow

• Learn the trigger keys: / @ \!
• Use j/k in list views (vim-style)
• Tab and Shift+Tab cycle through elements

Troubleshooting

TUI Not Launching

# Check authentication
ivybloom auth status

# Verify terminal capabilities
ivybloom doctor

Connection Issues

The status bar shows connection state. If disconnected:

1. Check internet connection
2. Verify API key: ivybloom auth status
3. The TUI auto-reconnects; wait a few seconds

Display Problems

Set "enable_animations": false in ~/.config/ivybloom/ui_settings.json, or open /appearance in the TUI and pick a different theme.

Read next

• Sessions & Checkpoints — Persistent conversations and time-travel
• Orchestration — AI routing that powers TUI chat
• Commands Reference — Full command documentation
• Job Management — Detailed job workflows
• Configuration — Customize behavior and themes