Agent TUI

The agent ships with a built-in TUI (terminal user interface) that gives you live logs and status without needing the web dashboard. Run ./agent and you get a colorized, filterable log stream with a status header — useful for debugging or running headless without the browser open.

Heads up: there's no screenshot of the TUI in this doc yet — the orchestrator that captures the rest of our docs only drives a browser, not a terminal. If you want to see what the TUI looks like before installing the agent, ask in Discord.

Features

🎨 Visual Dashboard

• Pitchfork ASCII Art: Prominent branding header
• Real-time Stats: Agent info, connection status, active bots, system metrics
• Color-coded Logs: Different colors for log levels and services
• Interactive Controls: Keyboard navigation and filtering

📊 Dashboard Components

Header Section

• Agent name, ID, and version
• Connection status (Online/Offline/Busy)
• Active bot count
• System metrics (CPU, Memory)
• Uptime counter

Log Window

• Scrollable log output with vim-like navigation

• Log Level Colors:

  • 🔴 ERROR: Red/bright red
  • 🟡 WARN: Yellow/orange
  • 🔵 INFO: Blue/cyan
  • 🟢 DEBUG: Green/dim

• Service Colors:

  • 🟣 AGENT: Purple/magenta
  • 🟢 PYTHON: Green
  • 🔵 CLIENT: Blue
  • 🟨 WRAPPER: Cyan
  • 🟠 WEBACTION: Yellow
  • 🩷 BOT: Pink

Control Panel

• Current filter status
• Scroll position indicator
• Keyboard shortcuts reference

Usage

Starting the Agent with TUI

The TUI is enabled by default. Simply run the agent:

./agent

Disabling TUI Mode

To run in traditional text mode:

./agent -no-tui

Keyboard Controls

Navigation

• ↑/↓ or j/k: Scroll logs up/down
• q or Ctrl+C: Quit application

Log Level Filters

• d: Toggle Debug logs
• i: Toggle Info logs
• w: Toggle Warn logs
• e: Toggle Error logs

Service Filters

• 1: Toggle Agent logs
• 2: Toggle Python logs
• 3: Toggle Client logs
• 4: Toggle Wrapper logs
• 5: Toggle WebAction logs
• 6: Toggle Bot logs

Control Actions

• p: Pause/Resume log scrolling
• c: Clear log buffer
• r: Reset all filters

Automatic Headless Detection

The agent automatically disables TUI mode in clearly headless environments:

• CI/CD environments (CI=true or CONTINUOUS_INTEGRATION=true)
• Docker containers without TTY (DOCKER_CONTAINER=true + no terminal)
• Dumb terminals (TERM=dumb)
• No terminal (no stdin/stdout terminal + empty TERM)

Note: The detection is now more conservative and favors enabling TUI when uncertain. Use AGENT_FORCE_TUI=true to override detection if needed.

Log File Integration

Even with TUI enabled, you can still write logs to a file:

# TUI display + file logging
./agent -log-file agent.log

# Text mode with file logging
./agent -no-tui -log-file agent.log

Troubleshooting

TUI Won't Start

1. Check terminal compatibility: Ensure your terminal supports ANSI colors
2. Verify terminal size: TUI requires minimum terminal dimensions
3. Check environment: May auto-disable in headless environments
   • Set AGENT_FORCE_TUI=true to override headless detection
   • Use AGENT_TUI_MODE=true to explicitly enable TUI
4. Check TUI flag: Ensure you're not using -no-tui flag

Performance Issues

1. Reduce log buffer: Use -tui-buffer 500 for lower memory usage
2. Increase update interval: Use -tui-update-interval 1s for less frequent updates
3. Filter logs: Disable debug logs with d key if too verbose

Display Issues

1. Terminal encoding: Ensure UTF-8 support for ASCII art
2. Color support: Some terminals may not display all colors correctly
3. Resize handling: TUI automatically adapts to terminal resize