TUI Clone

Explore terminal user interfaces systematically to produce clone-ready documentation.

Key principle: Write findings to file immediately as discovered. This survives context compaction.

Output File

All findings go to: tui-analysis-[app-name]-[timestamp].md

The timestamp ensures multiple sessions don’t clobber each other.

Process

1. Setup and Initialize Output File

source .claude/skills/tmux-cli-test/scripts/tmux_helpers.sh
TMUX_TEST_WIDTH=140
TMUX_TEST_HEIGHT=40

APP_NAME="lazygit"  # Set to target app
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
OUTPUT_FILE="tui-analysis-${APP_NAME}-${TIMESTAMP}.md"

# Initialize output file with header
cat > "$OUTPUT_FILE" << 'EOF'
# [App Name] TUI Analysis

## Overview
- Purpose: [TODO]
- Technology stack: [TODO]
- Target users: [TODO]

## Screen Catalog
EOF

echo "Output file: $OUTPUT_FILE"

2. Launch Target and Capture Initial View

SESSION="tui-analysis"
tmux_start "$SESSION" "$APP_NAME"
tmux_wait_for "$SESSION" "<ready-indicator>" 30

# Immediately write initial view to file
{
    echo ""
    echo "### Initial View"
    echo "- Entry: Launch command"
    echo '```'
    tmux_capture "$SESSION"
    echo '```'
} >> "$OUTPUT_FILE"

echo "Wrote initial view to $OUTPUT_FILE"

3. Write Screen Function

Use this helper to append each discovered screen:

write_screen() {
    local name="$1"
    local entry="$2"
    local session="$3"

    {
        echo ""
        echo "### $name"
        echo "- Entry: $entry"
        echo '```'
        tmux_capture "$session"
        echo '```'
    } >> "$OUTPUT_FILE"

    echo "Wrote screen '$name' to $OUTPUT_FILE"
}

4. Explore and Write Immediately

As you discover each screen, write it immediately:

# Check for help screen
tmux_send "$SESSION" "?"
if tmux_wait_for "$SESSION" "help\|Help\|Keybindings" 3; then
    write_screen "Help Screen" "Press ?" "$SESSION"
fi
tmux_send "$SESSION" Escape

# Explore numbered tabs
for i in 1 2 3 4 5; do
    tmux_send "$SESSION" "$i"
    sleep 0.3
    # Check if view changed meaningfully
    write_screen "Tab $i View" "Press $i" "$SESSION"
done

5. Write Keybindings Section

After exploring, append keybindings:

{
    echo ""
    echo "## Keybindings"
    echo ""
    echo "| Key | Context | Action |"
    echo "|-----|---------|--------|"
    echo "| ? | Global | Show help |"
    echo "| q | Global | Quit |"
    echo "| j/k | List | Navigate up/down |"
    # Add more as discovered
} >> "$OUTPUT_FILE"

6. Write Implementation Notes

At the end, append analysis:

{
    echo ""
    echo "## Implementation Notes"
    echo ""
    echo "### Patterns Identified"
    echo "- [List patterns observed]"
    echo ""
    echo "### Recommended Tech Stack"
    echo "- [Your recommendations]"
    echo ""
    echo "### Complexity Assessment"
    echo "- [Your assessment]"
} >> "$OUTPUT_FILE"

Example Session: Analyzing lazygit

source .claude/skills/tmux-cli-test/scripts/tmux_helpers.sh
TMUX_TEST_WIDTH=140
TMUX_TEST_HEIGHT=40

APP_NAME="lazygit"
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
OUTPUT_FILE="tui-analysis-${APP_NAME}-${TIMESTAMP}.md"
SESSION="analyze-${APP_NAME}"

# Initialize output file
cat > "$OUTPUT_FILE" << EOF
# $APP_NAME TUI Analysis

## Overview
- Purpose: Git TUI client
- Technology stack: Go + gocui/tcell
- Target users: Developers who prefer terminal git workflow

## Screen Catalog
EOF

# Launch and capture initial view
tmux_start "$SESSION" "$APP_NAME"
tmux_wait_for "$SESSION" "Status" 15

{
    echo ""
    echo "### Main View"
    echo "- Entry: Launch command"
    echo '```'
    tmux_capture "$SESSION"
    echo '```'
} >> "$OUTPUT_FILE"
echo "Wrote: Main View"

# Check for help
tmux_send "$SESSION" "?"
if tmux_wait_for "$SESSION" "Keybindings" 5; then
    {
        echo ""
        echo "### Help Screen"
        echo "- Entry: Press ?"
        echo '```'
        tmux_capture "$SESSION"
        echo '```'
    } >> "$OUTPUT_FILE"
    echo "Wrote: Help Screen"
fi
tmux_send "$SESSION" Escape

# Explore numbered panels
for i in 1 2 3 4 5; do
    tmux_send "$SESSION" "$i"
    sleep 0.3
    {
        echo ""
        echo "### Panel $i"
        echo "- Entry: Press $i"
        echo '```'
        tmux_capture "$SESSION"
        echo '```'
    } >> "$OUTPUT_FILE"
    echo "Wrote: Panel $i"
done

# Cleanup
tmux_send "$SESSION" q
tmux_wait_exit "$SESSION" 5

echo "Analysis complete: $OUTPUT_FILE"

Resuming After Compaction

If context compacts mid-session, find and read the output file to see progress:

ls -la tui-analysis-*.md  # Find the current session's file
cat tui-analysis-lazygit-20260203-141523.md  # Read it

Then continue appending new discoveries to the same file. The timestamp in the filename helps identify which session you’re continuing.

Additional Analysis Dimensions

Beyond screens and keybindings, capture these for a complete clone spec:

7. Color/Style Analysis

Capture with ANSI codes to understand the color palette:

{
    echo ""
    echo "## Color Palette"
    echo ""
    echo "Raw ANSI capture:"
    echo '```ansi'
    tmux_capture_ansi "$SESSION"
    echo '```'
} >> "$OUTPUT_FILE"

8. Component Inventory

Document reusable UI components observed:

{
    echo ""
    echo "## Component Inventory"
    echo ""
    echo "| Component | Description | Observed In |"
    echo "|-----------|-------------|-------------|"
    echo "| List | Scrollable item list with selection | Main view, File picker |"
    echo "| Modal | Centered overlay dialog | Commit message, Confirmation |"
    echo "| Tabs | Numbered panel switcher | Top bar |"
    echo "| Status bar | Bottom info line | All views |"
    echo "| Progress | Loading/sync indicator | Push/pull operations |"
    echo "| Input | Text entry field | Search, Commit message |"
} >> "$OUTPUT_FILE"

9. Responsive Behavior

Test terminal resize handling:

# Resize terminal and capture
tmux resize-pane -t "$SESSION" -x 80 -y 24
sleep 0.5
{
    echo ""
    echo "### Compact Layout (80x24)"
    echo '```'
    tmux_capture "$SESSION"
    echo '```'
} >> "$OUTPUT_FILE"

tmux resize-pane -t "$SESSION" -x 200 -y 50
sleep 0.5
{
    echo ""
    echo "### Wide Layout (200x50)"
    echo '```'
    tmux_capture "$SESSION"
    echo '```'
} >> "$OUTPUT_FILE"

10. State Transitions

Document view change triggers:

{
    echo ""
    echo "## State Transitions"
    echo ""
    echo "| From | Trigger | To |"
    echo "|------|---------|-----|"
    echo "| Main | Enter on file | Diff view |"
    echo "| Main | c | Commit dialog |"
    echo "| Any | Escape | Previous view |"
    echo "| Any | q | Exit confirmation |"
} >> "$OUTPUT_FILE"

11. Error/Loading States

Look for and document:

• Error messages (try invalid operations)
• Loading spinners
• Empty states
• Confirmation dialogs

12. Data Structures

Document what data types the UI displays:

• Lists (single select, multi-select)
• Trees (expandable/collapsible)
• Tables (columns, sorting)
• Text views (scrollable, line numbers)
• Diffs (side-by-side, unified)

ASCII Diagram Guidelines

When documenting layouts, use box-drawing characters:

┌─────────────────────────────────────────┐
│ Header / Title Bar                      │
├────────────────┬────────────────────────┤
│ Sidebar        │ Main Content           │
│                │                        │
│ - Item 1       │  Details here          │
│ > Item 2 *     │                        │
│ - Item 3       │                        │
├────────────────┴────────────────────────┤
│ Status Bar / Footer                     │
└─────────────────────────────────────────┘

Use these conventions:

• > for selected item
• * for active/focused
• [Button] for clickable
• [x] / [ ] for checkboxes
• ( ) / (*) for radio buttons
• │ ─ ┌ ┐ └ ┘ ├ ┤ ┬ ┴ ┼ for borders

Known TUI Commands

Deliverable Checklist

The output file tui-analysis-[app-name]-[timestamp].md should contain:

• Overview – Purpose, tech stack, target users
• Screen Catalog – ASCII diagram + entry path for each view
• Keybindings – Complete table with context
• State Transitions – View change triggers
• Component Inventory – Reusable UI elements
• Color Palette – ANSI capture for styling
• Responsive Behavior – Compact/wide layout captures
• Error/Loading States – Edge case UI
• Data Structures – Lists, trees, tables observed
• Implementation Notes – Tech recommendations, complexity

Quick Reference: What Makes a Good Clone Spec