Terminal User Interface (TUI)

Overview#

The AWF Terminal User Interface (TUI) is an interactive dashboard for managing your workflows without touching the command line. It provides real-time visibility into workflow execution, browsing of available workflows, exploration of execution history, and monitoring of agent conversations.

Launch the TUI at any time with:

awf tui

The TUI is designed for terminal environments and requires a minimum of 80x24 character dimensions.

Getting Started with the TUI#

Launching the TUI#

# Start the TUI
awf tui

# The TUI will initialize with:
# - Auto-detected project configuration from .awf/config.yaml
# - Loaded workflows from .awf/workflows/, global, and installed packs
# - Recent execution history from history.db

Tab Navigation#

The TUI is organized into five tabs. Switch between them using keyboard shortcuts:

Tip: Use Tab to cycle forward and Shift+Tab to cycle backward through tabs.

The Workflows Tab#

The Workflows tab is your entry point for discovering and launching workflows.

Finding Workflows#

1. Browse the list: All available workflows appear in chronological order (most recently modified first) or by name (alphabetical)
2. Filter the list: Press f and type to search by workflow name or description
3. View details: Press ? on a selected workflow to see its description, inputs, and step count

Launching a Workflow#

1. Select a workflow from the list using arrow keys
2. Press Enter to launch
3. Provide inputs in the prompted dialog (if required by the workflow)
4. Confirm and the TUI will switch to the Monitoring tab

Interactive Input Collection#

If a workflow requires inputs, the TUI prompts you in a form:

Workflow: deploy-app

Input Parameters:
  environment (string, required)
  > prod

  version (string, required)
  > 1.2.3

  timeout (integer, optional, default: 300)
  > (press Enter for default)

Enum inputs present numbered options:

environment (string, required):
Available options:
  1) dev
  2) staging
  3) prod
Select (1-3):
> 2

Validating Workflows#

Validate a workflow without executing it:

1. Select a workflow from the list
2. Press v to validate
3. View results in a popup overlay (errors or success confirmation)

The Monitoring Tab#

The Monitoring tab provides real-time visibility into workflow execution with an execution tree, status indicators, and live log streaming.

Understanding the Execution Tree#

The tree represents the workflow’s state structure:

▶ main (duration: 0.5s)
  ├─ ✓ read_input (0.1s)
  ├─ ▶ process (0.3s)
  │  ├─ ▶ validate (0.1s)
  │  └─ ⏳ transform
  └─ ⏳ output

Viewing Step Logs#

1. Select a step in the execution tree using arrow keys
2. View live logs in the right panel updating in real-time
3. Manual scroll: Press Page Up/Page Down or j/k to scroll
4. Toggle auto-scroll: Press a to lock/unlock automatic scrolling

Tip: When a step fails, the TUI automatically selects it and scrolls the log viewport to show the error message.

Parallel Execution Tracking#

When a workflow runs parallel steps, they appear as siblings in the tree:

▶ process-batch
  ├─ ▶ task_1 (0.2s)
  ├─ ✓ task_2 (0.4s)
  ├─ ▶ task_3 (0.1s)
  └─ ⏳ task_4

Each parallel task has independent status tracking and log output.

Stopping a Running Workflow#

Press Ctrl+C while monitoring a workflow to request cancellation. The workflow will attempt graceful shutdown within the configured timeout.

The History Tab#

The History tab lets you explore past workflow executions without re-running them.

Browsing Execution History#

The history list shows recent executions in reverse chronological order:

Workflow          ID                 Status    Start Time              Duration
deploy            abc123-def456      success   2025-05-01 14:30:22     2m 45s
build             ghi789-jkl012      failed    2025-05-01 13:15:10     45s
test              mno345-pqr678      success   2025-05-01 12:00:00     1m 30s

Filtering History#

Press f to open the filter dialog:

Filter History

Workflow (optional):
> deploy

Status (optional):
  1) All
  2) success
  3) failed
  4) cancelled
Select: > 1

Date Range:
From (YYYY-MM-DD, optional):
> 2025-05-01

To (YYYY-MM-DD, optional):
> (press Enter for today)

Inspecting Execution Details#

1. Select an execution from the filtered list
2. Press Enter to view details
3. Review the execution tree with final step statuses
4. Examine step outputs by selecting steps
5. Press Escape to return to the history list

The Agent Conversations Tab#

The Agent Conversations tab renders multi-turn agent interactions with proper Markdown formatting.

Viewing Agent Messages#

When a workflow with agent steps is running, the Conversations tab shows:

╔════════════════════════════════════════════════════════════════════╗
║                      Agent Conversation                             ║
╚════════════════════════════════════════════════════════════════════╝

USER: Analyze this code for performance issues.

function fibonacci(n) {
  if (n <= 1) return n;
  return fibonacci(n-1) + fibonacci(n-2);
}

AGENT (Claude): This recursive implementation has exponential time
complexity O(2^n) due to overlapping subproblems.

**Recommendations:**
1. Use memoization to cache results
2. Consider iterative approach
3. Dynamic programming solution optimal for n < 93

[Would you like me to show optimization examples?]

Message Types#

• User messages: System prompts and user-provided inputs
• Agent responses: LLM outputs with Markdown formatting (headings, lists, code blocks)
• Tool use: If enabled, shows tool invocations and results
• Approval prompts: Interactive yes/no decisions (if applicable)

Scrolling Through Conversations#

• Use arrow keys or j/k to scroll line-by-line
• Page Up/Page Down for page-by-page navigation
• Press Home/End to jump to conversation start/end

The External Logs Tab#

The External Logs tab live-tails Claude Code JSONL session files for monitoring development sessions alongside workflow execution.

Automatic Session Detection#

The TUI automatically discovers and tails the latest Claude Code session:

1. Monitors ~/.claude/projects/*/session.jsonl
2. Auto-switches to the most recently modified file
3. Displays new entries within 2 seconds of being written

Session Output Format#

[14:30:22] User: Implement OAuth2 authentication
[14:30:45] Assistant: I'll implement OAuth2 with these components...
[14:31:12] Tool: claude-code exec npm install
[14:31:20] Output: ✓ Installed 5 packages
[14:31:35] Assistant: Now implementing the provider...

When No Session Is Active#

╔════════════════════════════════════════════════════════════════════╗
║                    External Logs (Claude Code)                      ║
╚════════════════════════════════════════════════════════════════════╝

No Claude Code session file detected.

Expected location:
~/.claude/projects/<project-id>/session.jsonl

To start monitoring:
1. Open Claude Code: https://claude.ai/code
2. Create a new session
3. The TUI will auto-detect and begin tailing

Pausing and Resuming#

• Press Space to pause tailing (useful for reading a specific section)
• Press Space again to resume auto-scrolling

Common Workflows#

Workflow: Launch and Monitor#

The most common TUI workflow:

1. Launch TUI: awf tui
2. Navigate to Workflows tab (press 1)
3. Filter by name (press f, type workflow name)
4. Select workflow (arrow keys, press Enter)
5. Provide inputs when prompted
6. TUI auto-switches to Monitoring tab
7. Watch execution in real-time
8. Inspect logs by selecting steps
9. When complete, view summary status

Workflow: Investigate a Failed Execution#

Debugging a recent failure:

1. Launch TUI: awf tui
2. Navigate to History tab (press 3)
3. Filter by status (press f, select “failed”)
4. Select the failed execution
5. Review the execution tree (red ✗ marks)
6. Select the failed step to view error logs
7. Review related steps’ output for context
8. Navigate to Workflows tab to re-run the workflow with corrections

Workflow: Compare Recent Runs#

Analyzing trends across recent executions:

1. Navigate to History tab
2. Select first execution (press Enter to view)
3. Note timing and outputs
4. Press Escape to return to list
5. Select another execution for comparison
6. Compare step durations and status patterns

Workflow: Monitor Agent Development#

Watching a development agent alongside workflow execution:

1. Have a Claude Code session open in another window
2. Launch TUI: awf tui
3. Start a workflow in Workflows tab
4. Switch between tabs to monitor:
   • Monitoring: Workflow execution status
   • Agent Conversations: Multi-turn interactions
   • External Logs: Claude Code session activity
5. All three views update in real-time

Tips & Tricks#

Keyboard Efficiency#

• Quick tab navigation: Use Ctrl+1 through Ctrl+5 for direct tab jumping
• Search filtering: Always available in list views with f key
• Quick quit: q exits cleanly (or Ctrl+C)
• Refresh view: r manually refreshes (auto-refresh happens every 200ms)

Terminal Optimization#

• Maximize terminal window for better tree visualization and log readability
• Use a terminal with true color support for accurate status icon rendering
• Increase scroll buffer in your terminal settings if you need to review long logs

Performance Tips#

• Close other applications if terminal rendering is slow (large log output or slow machine)
• Disable verbose mode in workflows (--verbose flag not needed in TUI)
• Limit history entries in config if database is very large

Secret Handling#

The TUI automatically masks sensitive values in all views:

• Environment variables starting with SECRET_, API_KEY, or PASSWORD are masked as ***
• This applies to logs, execution tree details, and agent conversation output
• Masking happens at render time (original data is never exposed in TUI)

Troubleshooting#

TUI won’t start#

Symptom: awf tui command not found

Solution:

# Rebuild the project
make build

# Or reinstall
make install

Execution tree is empty#

Symptom: Monitoring tab shows no tree nodes

Causes & Solutions:

• Workflow hasn’t started yet — check the status bar at bottom
• Workflow finished very quickly — switch back to Workflows tab and re-run
• Rendering issue — try pressing r to refresh or resizing terminal

Logs not updating#

Symptom: Log viewport stuck at old output

Solutions:

• Toggle auto-scroll off/on (press a)
• Refresh the view (press r)
• Check if workflow is actually running in status bar
• Terminal might be too small — resize to minimum 80x24

History tab shows no entries#

Symptom: History tab is empty despite running workflows

Causes & Solutions:

• No workflows have been executed yet — run a workflow first
• history.db file is corrupted — delete .awf/storage/history.db and re-run a workflow
• Permission issue on history.db — check file permissions

Claude Code logs not appearing#

Symptom: External Logs tab empty despite active Claude Code session

Causes & Solutions:

• Session file location differs from expected path — check ~/.claude/projects/
• File format changed — the TUI expects JSONL format
• Tailer hasn’t detected the file yet — wait a few seconds and refresh (press r)

Colors look wrong#

Symptom: Text is hard to read or colors are incorrect

Solutions:

• Check terminal TERM variable: echo $TERM
• Set correct term type: export TERM=xterm-256color
• Test with basic ANSI mode: the TUI auto-detects and degrades gracefully
• Verify terminal supports true color (most modern terminals do)

Best Practices#

For Daily Operations#

• Keep TUI open during development sessions to monitor background workflows
• Use History tab to track execution patterns and identify slowdowns
• Combine with dry-run: Use awf run --dry-run to preview before launching from TUI

For Troubleshooting#

• Capture logs: Take screenshots or pipe logs to file for analysis
• Check Agent tab: Before assuming a step failed, view the agent conversation
• Cross-reference with CLI: Use awf status <id> from terminal for raw JSON output

For Performance Monitoring#

• Monitor step durations: Watch for steps taking longer than expected
• Check parallel performance: Verify parallel steps complete as expected
• Review history trends: Spot regressions in execution time

See Also#

• Commands Reference - awf tui command details
• Workflow Syntax - Define workflows for TUI execution
• Interactive Inputs - Prompting for workflow inputs
• Execution History - CLI-based history access