Patterns for controlling TUI applications (vim, htop, tig, lazygit, etc.) via terminalcp
TUI Applications Control with terminalcp
This skill provides comprehensive patterns for automating Text User Interface (TUI) applications using terminalcp MCP. It enables AI agents to control interactive terminal applications with full visual feedback.
Overview
terminalcp enables:
Full PTY terminal emulation for TUI apps
ANSI color and cursor positioning preservation
Complex key sequence automation
Screen content capture and parsing
Multi-TUI session management
The MCP server runs via npx @mariozechner/terminalcp@latest --mcp and provides complete terminal rendering.
Vim/Neovim Automation
Starting Vim/Neovim
// Open file in vim{"action":"start","command":"vim myfile.txt","name":"vim-session"}// Open file in neovim{"action":"start","command":"nvim myfile.txt"
,
"name"
:
"nvim-session"
}
// Start vim without file
{
"action"
:
"start"
,
"command"
:
"vim"
,
"name"
:
"vim-session"
}
Vim Mode Navigation
// Enter insert mode{"action":"stdin","id":"vim-session","data":"i"}// Type text{"action":"stdin","id":"vim-session","data":"Hello, World!"}// Exit insert mode (Escape){"action":"stdin","id":"vim-session","data":"\u001b"}// Move cursor (in normal mode){"action":"stdin","id":"vim-session","data":"h"// left}{"action":"stdin","id":"vim-session","data":"j"// down}{"action":"stdin","id":"vim-session","data":"k"// up}{"action":"stdin","id":"vim-session","data":"l"// right}
Note: \u001b is the Escape key in MCP notation.
Vim Editing Commands
// Delete line{"action":"stdin","id":"vim-session","data":"dd"}// Undo{"action":"stdin","id":"vim-session","data":"u"}// Redo{"action":"stdin","id":"vim-session","data":"\u0012"// Ctrl+R}// Copy line (yank){"action":"stdin","id":"vim-session","data":"yy"}// Paste{"action":"stdin","id":"vim-session","data":"p"}// Find and replace{"action":"stdin","id":"vim-session","data":":%s/old/new/g\r"}
Vim File Operations
// Save file{"action":"stdin","id":"vim-session","data":":w\r"}// Save and quit{"action":"stdin","id":"vim-session","data":":wq\r"}// Quit without saving{"action":"stdin","id":"vim-session","data":":q!\r"}// Open another file{"action":"stdin","id":"vim-session","data":":e another_file.txt\r"}// Save as{"action":"stdin","id":"vim-session","data":":saveas newfile.txt\r"}
Vim Search and Navigation
// Search forward{"action":"stdin","id":"vim-session","data":"/search_term\r"}// Search backward{"action":"stdin","id":"vim-session","data":"?search_term\r"}// Next search result{"action":"stdin","id":"vim-session","data":"n"}// Previous search result{"action":"stdin","id":"vim-session","data":"N"}// Go to line{"action":"stdin","id":"vim-session","data":":42\r"}// Go to end of file{"action":"stdin","id":"vim-session","data":"G"}// Go to beginning of file{"action":"stdin","id":"vim-session","data":"gg"}
Vim Visual Mode
// Enter visual mode{"action":"stdin","id":"vim-session","data":"v"}// Select text (move cursor while in visual mode){"action":"stdin","id":"vim-session","data":"jjj"// Select 3 lines down}// Copy selection{"action":"stdin","id":"vim-session","data":"y"}// Exit visual mode{"action":"stdin","id":"vim-session","data":"\u001b"}
Capturing Vim Screen
{"action":"stdout","id":"vim-session"}
This returns the full terminal rendering including vim's UI, status line, and content.
System Monitoring TUIs
htop
// Start htop{"action":"start","command":"htop","name":"htop-session"}// Navigate processes{"action":"stdin","id":"htop-session","data":"\u001b[B"// Down arrow}{"action":"stdin","id":"htop-session","data":"\u001b[A"// Up arrow}// Sort by CPU{"action":"stdin","id":"htop-session","data":"P"}// Sort by memory{"action":"stdin","id":"htop-session","data":"M"}// Filter processes{"action":"stdin","id":"htop-session","data":"F4"}{"action":"stdin","id":"htop-session","data":"python\r"}// Kill process{"action":"stdin","id":"htop-session","data":"F9"}// Capture current state{"action":"stdout","id":"htop-session"}// Quit{"action":"stdin","id":"htop-session","data":"q"}
// Start ranger file manager{"action":"start","command":"ranger","name":"ranger-session"}// Navigate{"action":"stdin","id":"ranger-session","data":"j"// Down}{"action":"stdin","id":"ranger-session","data":"k"// Up}{"action":"stdin","id":"ranger-session","data":"l"// Enter directory}{"action":"stdin","id":"ranger-session","data":"h"// Go up directory}// Search{"action":"stdin","id":"ranger-session","data":"/filename\r"}// Delete file{"action":"stdin","id":"ranger-session","data":"dD"}// Capture current view{"action":"stdout","id":"ranger-session"}// Quit{"action":"stdin","id":"ranger-session","data":"q"}
Database TUIs
mycli (MySQL client)
// Start mycli{"action":"start","command":"mycli -u user -p password -D database","name":"mycli-session"}// Execute query{"action":"stdin","id":"mycli-session","data":"SELECT * FROM users LIMIT 10;\r"}// Navigate results with arrow keys{"action":"stdin","id":"mycli-session","data":"\u001b[B"// Scroll down}// Capture results{"action":"stdout","id":"mycli-session"}// Exit{"action":"stdin","id":"mycli-session","data":"\\q\r"}
pgcli (PostgreSQL client)
// Start pgcli{"action":"start","command":"pgcli -h localhost -U user database","name":"pgcli-session"}// Execute query{"action":"stdin","id":"pgcli-session","data":"SELECT * FROM products WHERE price > 100;\r"}// Capture output{"action":"stdout","id":"pgcli-session"}
Advanced Patterns
Automated Code Editing Workflow
// 1. Open file in vim{"action":"start","command":"vim script.py","name":"edit-session"}// 2. Go to specific line{"action":"stdin","id":"edit-session","data":":50\r"}// 3. Enter insert mode{"action":"stdin","id":"edit-session","data":"i"}// 4. Type new code{"action":"stdin","id":"edit-session","data":" print('Debug info')\r"}// 5. Exit insert mode{"action":"stdin","id":"edit-session","data":"\u001b"}// 6. Save file{"action":"stdin","id":"edit-session","data":":w\r"}// 7. Capture result{"action":"stdout","id":"edit-session"}// 8. Quit{"action":"stdin","id":"edit-session","data":":q\r"}
System Monitoring and Alert
// 1. Start htop{"action":"start","command":"htop","name":"monitor"}// 2. Sort by CPU{"action":"stdin","id":"monitor","data":"P"}// 3. Capture current state{"action":"stdout","id":"monitor"}// Parse output for high CPU processes...// If high CPU detected, capture more details// 4. Periodic monitoring with stream mode{"action":"stream","id":"monitor","since_last":true}// Continue monitoring...
// 1. Start database client{"action":"start","command":"mycli -u root mydb","name":"db-query"}// 2. Run analysis query{"action":"stdin","id":"db-query","data":"SELECT category, COUNT(*), AVG(price) FROM products GROUP BY category;\r"}// 3. Capture results{"action":"stdout","id":"db-query"}// Parse results...// 4. Run follow-up query based on analysis{"action":"stdin","id":"db-query","data":"SELECT * FROM products WHERE category = 'electronics' ORDER BY price DESC LIMIT 5;\r"}// 5. Capture final results{"action":"stdout","id":"db-query"}// 6. Exit{"action":"stdin","id":"db-query","data":"\\q\r"}
Key Sequences Reference
Special Keys in MCP Notation
Enter: \r
Escape: \u001b
Tab: \t
Ctrl+C: \u0003
Ctrl+D: \u0004
Ctrl+Z: \u001a
Ctrl+R: \u0012
Ctrl+L: \u000c
Backspace: \u007f
Up Arrow: \u001b[A
Down Arrow: \u001b[B
Right Arrow: \u001b[C
Left Arrow: \u001b[D
Home: \u001b[H
End: \u001b[F
Page Up: \u001b[5~
Page Down: \u001b[6~
Delete: \u001b[3~
F1-F12: \u001bOP to \u001b[24~
Vim Key Combinations
Ctrl+W + W: Switch windows
Ctrl+W + V: Vertical split
Ctrl+W + S: Horizontal split
Ctrl+F: Page down
Ctrl+B: Page up
Ctrl+U: Half page up
Ctrl+D: Half page down
Best Practices
Screen Capture Timing
Capture after significant actions complete
Use stream mode for continuous monitoring
Wait for UI to settle before capture
Parse output carefully - TUIs include ANSI codes
Navigation Strategy
Use shortcuts when available (e.g., gg in vim vs many k presses)
Learn application-specific navigation
Test key sequences in isolation first
Handle different terminal sizes
Error Handling
// Vim: Handle if file doesn't exist// Check output after :e command{"action":"stdout","id":"vim-session"}// Parse for error messages like "Cannot open file"
Session Management
Name TUI sessions by purpose
Close applications gracefully (quit commands)
Use stop action if application hangs
List sessions to track active TUIs
Output Parsing
TUI output includes formatting codes
Use regex to extract data from formatted tables
Be aware of terminal width affecting layout
Strip ANSI codes for text-only analysis
Common TUI Workflows
Quick File Edit
Open vim with file
Navigate to target location
Make changes in insert mode
Save and quit
System Health Check
Start htop
Capture CPU/memory state
Identify high-usage processes
Document findings
Git Change Review
Start tig or lazygit
Navigate through commits/changes
Capture relevant diffs
Make staging/commit decisions
Database Investigation
Connect to database with TUI client
Run exploratory queries
Capture results
Refine queries based on findings
This skill provides comprehensive automation patterns for TUI applications using terminalcp's full terminal emulation capabilities.