Troubleshooting Guide
Having issues? This guide covers the most common problems and their solutions.╔═══════════════════════════════════════════════════════════════════════════════╗
║ ║
║ QUICK DIAGNOSTIC ║
║ ║
║ What's happening? ║
║ ║
║ □ Terminal feels slow → See "Slow Performance" ║
║ □ Display looks wrong → See "Display Issues" ║
║ □ Colors are off → See "Color Problems" ║
║ □ Scrolling problems → See "Scrolling Issues" ║
║ □ App-specific issues → See "App Compatibility" ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════════╝
Quick Reset
When in doubt, try this first:1
Close all terminal tabs
Click the X on each tab or use Cmd+W (Mac) / Ctrl+W (Windows/Linux)
2
Open a fresh terminal
Click the + button or use Cmd+T (Mac) / Ctrl+T (Windows/Linux)
3
Test if the issue is resolved
Run a simple command to check
┌─────────────────────────────────────────────────────────────────┐
│ QUICK RESET FLOW │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Close │ ────▶ │ Wait │ ────▶ │ Open │ │
│ │ tabs │ │ 2 sec │ │ new │ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ │
│ This fixes 80% of issues! │
│ │
└─────────────────────────────────────────────────────────────────┘
Issue 1: Slow Performance
┌─────────────────────────────────────────────────────────────────┐
│ SYMPTOM: Terminal feels laggy or unresponsive │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Possible causes: │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Cause │ How to check │ │
│ │ ───────────────────────────────────────────────────── │ │
│ │ Too many tabs open │ Count your open tabs │ │
│ │ Large scrollback buffer │ Check settings │ │
│ │ Heavy program running │ Check Activity Monitor │ │
│ │ System low on memory │ Check memory usage │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Solutions
Too many tabs open
Too many tabs open
┌─────────────────────────────────────────────────────────┐
│ SOLUTION: Reduce open tabs │
├─────────────────────────────────────────────────────────┤
│ │
│ Before: │
│ ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐ │
│ │ 1 │ 2 │ 3 │ 4 │ 5 │ 6 │ 7 │ 8 │ 9 │10 │ ← Too many │
│ └───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘ │
│ │
│ After: │
│ ┌───┬───┬───┐ │
│ │ 1 │ 2 │ 3 │ ← Just what you need │
│ └───┴───┴───┘ │
│ │
│ Close tabs you're not actively using. │
│ │
└─────────────────────────────────────────────────────────┘
Large scrollback buffer
Large scrollback buffer
Reduce the scrollback limit in Settings:
┌─────────────────────────────────────────────────────────┐
│ │
│ Settings → Terminal → Scrollback │
│ │
│ Current: [100,000 lines] ← Very large │
│ │
│ Recommended: [10,000 lines] ← Good balance │
│ │
│ Minimal: [1,000 lines] ← Best performance │
│ │
└─────────────────────────────────────────────────────────┘
System resources
System resources
Check if your system has enough resources:
┌─────────────────────────────────────────────────────────┐
│ Check Activity Monitor (Mac) or Task Manager (Windows) │
├─────────────────────────────────────────────────────────┤
│ │
│ Memory usage: │
│ ████████████████████░░░░ 80% ← Might be too high │
│ │
│ If above 90%: │
│ • Close other applications │
│ • Restart your computer │
│ │
└─────────────────────────────────────────────────────────┘
Issue 2: Display Problems
┌─────────────────────────────────────────────────────────────────┐
│ SYMPTOM: Text looks garbled, misaligned, or corrupted │
├─────────────────────────────────────────────────────────────────┤
│ │
│ What you might see: │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ ▒▒▒▒▒▒▒▒ │ │
│ │ █░█░█░█░ ← Garbage characters │ │
│ │ ████████ │ │
│ │ │ │
│ │ Helllo World ← Duplicated or missing characters │ │
│ │ He o Wor d │ │
│ │ │ │
│ │ Text here │ │
│ │ Text should be here ← Misaligned │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Solutions
1
Clear the screen
Type
clear or press Ctrl+L2
Reset terminal state
Type
reset to fully reset the terminal3
If still broken, restart the tab
Close and reopen the tab
┌─────────────────────────────────────────────────────────────────┐
│ RESET COMMANDS │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Command What it does │
│ ────────────────────────────────────────────────────────── │
│ │
│ clear Clears visible screen │
│ (scrollback preserved) │
│ │
│ reset Full terminal reset │
│ (clears everything, fixes most issues) │
│ │
│ Ctrl+L Same as clear (keyboard shortcut) │
│ │
└─────────────────────────────────────────────────────────────────┘
Issue 3: Color Problems
┌─────────────────────────────────────────────────────────────────┐
│ SYMPTOM: Colors look wrong, washed out, or completely off │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Expected: Actual: │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ █ Red │ │ ░ Gray │ │
│ │ █ Green │ │ ░ Gray │ │
│ │ █ Blue │ vs │ ░ Gray │ │
│ │ █ Yellow │ │ ░ Gray │ │
│ └─────────────────────┘ └─────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Solutions
Check TERM variable
Check TERM variable
Your shell needs to know it’s in a modern terminal:
┌─────────────────────────────────────────────────────────┐
│ Check current TERM value by typing: │
│ │
│ echo $TERM │
│ │
│ Should show: xterm-256color │
│ │
│ If it shows something else, add to your shell config: │
│ │
│ For ~/.zshrc or ~/.bashrc: │
│ export TERM=xterm-256color │
│ │
└─────────────────────────────────────────────────────────┘
Theme conflict
Theme conflict
┌─────────────────────────────────────────────────────────┐
│ CHECK FOR THEME CONFLICTS │
├─────────────────────────────────────────────────────────┤
│ │
│ If you have a custom theme in your shell: │
│ │
│ ┌───────────────────────────────────────────────────┐ │
│ │ Monolex Theme ←→ Shell Theme (Oh-My-Zsh, etc.) │ │
│ │ ↓ ↓ │ │
│ │ Sets colors Also sets colors │ │
│ │ ↓ ↓ │ │
│ │ CONFLICT! │ │
│ └───────────────────────────────────────────────────┘ │
│ │
│ Try temporarily disabling your shell theme │
│ to see if that's the cause. │
│ │
└─────────────────────────────────────────────────────────┘
Issue 4: Scrolling Problems
┌─────────────────────────────────────────────────────────────────┐
│ SYMPTOM: Can't scroll, scroll jumps, or scroll is very slow │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Types of scrolling issues: │
│ │
│ 1. Can't scroll at all │
│ └─▶ Terminal might be in alternate screen mode │
│ │
│ 2. Scroll position jumps around │
│ └─▶ Program might be fighting for scroll control │
│ │
│ 3. Very slow scrolling │
│ └─▶ Too much content in scrollback │
│ │
└─────────────────────────────────────────────────────────────────┘
Solutions
Can't scroll (alternate screen)
Can't scroll (alternate screen)
Some programs (vim, less, man) use an alternate screen:
┌─────────────────────────────────────────────────────────┐
│ ALTERNATE SCREEN MODE │
├─────────────────────────────────────────────────────────┤
│ │
│ Normal terminal Alternate screen │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ $ history │ │ vim file.txt │ │
│ │ $ ls │ │ ────────────────│ │
│ │ $ cd project │ │ Line 1 │ │
│ │ ... │ ←→ │ Line 2 │ │
│ │ (can scroll) │ │ (no scroll) │ │
│ └─────────────────┘ └─────────────────┘ │
│ │
│ To exit alternate screen: │
│ • Exit the program (q in vim/less/man) │
│ • Press Ctrl+C to interrupt │
│ │
└─────────────────────────────────────────────────────────┘
Slow scrolling
Slow scrolling
Reduce scrollback history:
┌─────────────────────────────────────────────────────────┐
│ │
│ More history = slower scrolling │
│ │
│ 100,000 lines: ████████████████████ (slow) │
│ 10,000 lines: ████ (normal) │
│ 1,000 lines: █ (fast) │
│ │
│ Adjust in Settings → Terminal → Scrollback │
│ │
└─────────────────────────────────────────────────────────┘
Issue 5: App Compatibility
Some programs have special requirements:┌─────────────────────────────────────────────────────────────────┐
│ APP-SPECIFIC TIPS │
├─────────────────────────────────────────────────────────────────┤
│ │
│ vim / neovim: │
│ ───────────── │
│ Add to your config: │
│ set termguicolors │
│ │
│ tmux: │
│ ───────────── │
│ Add to ~/.tmux.conf: │
│ set -g default-terminal "xterm-256color" │
│ │
│ htop / btop: │
│ ───────────── │
│ Should work out of the box. │
│ If colors look wrong, check TERM variable. │
│ │
│ SSH sessions: │
│ ───────────── │
│ Remote TERM might differ. Add to remote ~/.bashrc: │
│ export TERM=xterm-256color │
│ │
└─────────────────────────────────────────────────────────────────┘
Universal Troubleshooting Checklist
When all else fails, go through this checklist:┌─────────────────────────────────────────────────────────────────┐
│ COMPLETE TROUBLESHOOTING CHECKLIST │
├─────────────────────────────────────────────────────────────────┤
│ │
│ □ Step 1: Close and reopen the tab │
│ └─▶ Fixes: Most temporary glitches │
│ │
│ □ Step 2: Type 'reset' to reset terminal state │
│ └─▶ Fixes: Display corruption, color issues │
│ │
│ □ Step 3: Check TERM variable (echo $TERM) │
│ └─▶ Should be: xterm-256color │
│ │
│ □ Step 4: Reduce scrollback in Settings │
│ └─▶ Fixes: Slow scrolling, memory issues │
│ │
│ □ Step 5: Close other tabs and apps │
│ └─▶ Fixes: Performance issues │
│ │
│ □ Step 6: Restart Monolex completely │
│ └─▶ Fixes: Deep issues, stuck processes │
│ │
│ □ Step 7: Restart your computer │
│ └─▶ Fixes: System-level issues │
│ │
└─────────────────────────────────────────────────────────────────┘
Still Having Issues?
If none of the above solutions work:Community Support
Join our community forum to get help from other users.
Report a Bug
Found a bug? Report it on GitHub so we can fix it.
When Reporting Issues
Please include:┌─────────────────────────────────────────────────────────────────┐
│ BUG REPORT TEMPLATE │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 1. What happened? │
│ ──────────────── │
│ Describe what you saw │
│ │
│ 2. What did you expect? │
│ ──────────────────── │
│ Describe what should have happened │
│ │
│ 3. Steps to reproduce: │
│ ──────────────────── │
│ 1. First I did... │
│ 2. Then I did... │
│ 3. And then this happened... │
│ │
│ 4. System info: │
│ ──────────────────── │
│ • Monolex version: (Help → About) │
│ • Operating system: (macOS/Windows/Linux + version) │
│ • Shell: (zsh/bash/fish) │
│ │
└─────────────────────────────────────────────────────────────────┘
Summary
╔═══════════════════════════════════════════════════════════════════════════════╗
║ ║
║ TROUBLESHOOTING QUICK REFERENCE ║
║ ║
║ Problem First Try Then Try ║
║ ─────────────────────────────────────────────────────────── ║
║ ║
║ Slow performance Close extra tabs Reduce scrollback ║
║ ║
║ Display corruption Type 'reset' Restart tab ║
║ ║
║ Wrong colors Check $TERM Disable shell theme ║
║ ║
║ Can't scroll Exit current app Press Ctrl+C ║
║ ║
║ App looks wrong Set termguicolors Check app docs ║
║ ║
║ Nothing works Restart Monolex Restart computer ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════════╝
Most issues are solved by closing and reopening the tab. Try that first before anything else!