Smooth, Flicker-Free Terminal
Ever noticed your terminal flickering during fast output? Monolex completely eliminates this problem with a technology called Atomic State.╔═══════════════════════════════════════════════════════════════════════════════╗
║ ║
║ NO MORE FLICKER ║
║ ║
║ Before Monolex After Monolex ║
║ ┌─────────────┐ ┌─────────────┐ ║
║ │ ▓░▓░▓░▓░▓░ │ │ Hello World │ ║
║ │ FLICKER! │ → │ Smooth text │ ║
║ │ ░▓░▓░▓░▓░▓ │ │ Always clean│ ║
║ └─────────────┘ └─────────────┘ ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════════╝
The Problem: Why Terminals Flicker
When programs print text really fast, traditional terminals struggle to keep up:┌─────────────────────────────────────────────────────────────────┐
│ TRADITIONAL TERMINAL │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Program says: "Print Hello World" │
│ │
│ Step 1: "H" arrives → Show immediately │
│ Step 2: "e" arrives → Show immediately │
│ Step 3: "l" arrives → Show immediately │
│ Step 4: "l" arrives → Show immediately │
│ Step 5: "o" arrives → Show immediately │
│ ...and so on │
│ │
│ Problem: Screen updates 11 times for "Hello World"! │
│ │
│ Your eyes see: │
│ ┌───────────────────────────────────────────┐ │
│ │ H → He → Hel → Hell → Hello → Hello W... │ │
│ └───────────────────────────────────────────┘ │
│ │
│ Result: FLICKER, JITTER, EYE STRAIN │
│ │
└─────────────────────────────────────────────────────────────────┘
The Solution: Atomic State
Monolex waits for complete frames before showing anything:┌─────────────────────────────────────────────────────────────────┐
│ MONOLEX WITH ATOMIC STATE │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Program says: "Print Hello World" │
│ │
│ ┌─────────────────┐ │
│ │ WAITING ROOM │ ← Characters wait here │
│ │ ───────────── │ │
│ │ H e l l o │ │
│ │ W o r l d │ │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ QUALITY CHECK │ ← Is the frame complete? │
│ │ ───────────── │ │
│ │ ✓ All text │ │
│ │ ✓ All colors │ │
│ │ ✓ Cursor pos │ │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ YOUR SCREEN │ ← Show only when ready! │
│ │ ───────────── │ │
│ │ Hello World │ │
│ └─────────────────┘ │
│ │
│ Result: ONE clean update, NO flicker │
│ │
└─────────────────────────────────────────────────────────────────┘
Think of it like a movie theater: Instead of showing you each frame as it’s being drawn, Monolex waits until the entire scene is ready, then displays it perfectly.
How It Works: The Gatekeeper
┌─────────────────────────────────────────────────────────────────┐
│ │
│ THE GATEKEEPER CONCEPT │
│ │
│ Programs Gatekeeper Your Screen │
│ ───────── ────────── ─────────── │
│ │
│ ┌───────┐ ┌────────┐ ┌───────────┐ │
│ │ App 1 │────────▶│ │ │ │ │
│ └───────┘ │ │ │ Perfect │ │
│ │ ATOMIC │──────────▶│ Display │ │
│ ┌───────┐ │ STATE │ │ │ │
│ │ App 2 │────────▶│ │ │ Always │ │
│ └───────┘ │ │ │ Clean │ │
│ └────────┘ │ │ │
│ ┌───────┐ │ └───────────┘ │
│ │ App 3 │──────────────┘ │
│ └───────┘ │
│ │
│ The Gatekeeper: │
│ • Collects all incoming data │
│ • Checks if frame is complete │
│ • Only lets perfect frames through │
│ │
└─────────────────────────────────────────────────────────────────┘
Visual Comparison
Traditional Terminal
Time 0ms: |H___________|
Time 1ms: |He__________|
Time 2ms: |Hel_________|
Time 3ms: |Hell________|
Time 4ms: |Hello_______|
Time 5ms: |Hello ______|
Time 6ms: |Hello W_____|
Time 7ms: |Hello Wo____|
Time 8ms: |Hello Wor___|
Time 9ms: |Hello Worl__|
Time 10ms: |Hello World_|
11 screen updates = FLICKER
Monolex
Time 0ms: |___________|
(waiting...)
(waiting...)
(waiting...)
(waiting...)
(waiting...)
(waiting...)
(waiting...)
(waiting...)
(waiting...)
Time 10ms: |Hello World|
1 screen update = SMOOTH
Smart Detection (4 Patterns)
Monolex uses the Alacritty VTE Parser (the same parser used by the popular Alacritty terminal) to understand terminal output. It detects 4 specific patterns to know when a frame is complete:┌─────────────────────────────────────────────────────────────────┐
│ PATTERN DETECTION (4 MECHANISMS) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Pattern 1: BSU/ESU (Synchronized Update Protocol) │
│ ───────────────────────────────────────────────── │
│ │
│ Modern programs send explicit signals: │
│ "BEGIN UPDATE" → draw content → "END UPDATE" │
│ │
│ Monolex waits for "END UPDATE" before displaying! │
│ │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Pattern 2: CURSOR HIDE/SHOW (Ink Pattern) │
│ ───────────────────────────────────────────────── │
│ │
│ Programs often: │
│ 1. Hide cursor ← "I'm about to draw" │
│ 2. Draw content │
│ 3. Show cursor ← "I'm done drawing" │
│ │
│ Monolex detects this and waits for step 3! │
│ │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Pattern 3: SCREEN CLEAR (Implicit Sync) │
│ ───────────────────────────────────────────────── │
│ │
│ When screen clears: │
│ • Old content gone │
│ • New content definitely coming │
│ • Wait 8ms for complete frame before showing │
│ │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Pattern 4: INCOMPLETE SEQUENCE │
│ ───────────────────────────────────────────────── │
│ │
│ If a command is split across packets: │
│ Packet 1: "Set color to re" │
│ Packet 2: "d" (rest of "red") │
│ │
│ Monolex buffers until the command is complete! │
│ │
└─────────────────────────────────────────────────────────────────┘
Real-World Examples
Example 1: Running a Build Command
┌─────────────────────────────────────────────────────────────────┐
│ npm run build │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Without Atomic State: With Atomic State: │
│ ───────────────────── ────────────────── │
│ │
│ [==== ] 40% [==== ] 40% │
│ [===== ] 50% (smooth transition) │
│ [====== ] 60% [==========] 100% │
│ [======= ] 70% │
│ [======== ] 80% Progress bar updates │
│ [========= ] 90% cleanly, no jitter │
│ [==========] 100% │
│ │
│ Each % causes redraw Only meaningful updates shown │
│ │
└─────────────────────────────────────────────────────────────────┘
Example 2: AI Streaming Output
┌─────────────────────────────────────────────────────────────────┐
│ Claude Code generating response │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Without Atomic State: With Atomic State: │
│ ───────────────────── ────────────────── │
│ │
│ T (waiting...) │
│ Th │
│ The │
│ The The answer is 42. │
│ The a │
│ The an Smooth, complete sentences │
│ The ans appear at natural pauses │
│ The answ │
│ The answe │
│ The answer │
│ ... │
│ │
│ Every character flickers Text appears in readable chunks │
│ │
└─────────────────────────────────────────────────────────────────┘
Example 3: Vim/Neovim Editing
┌─────────────────────────────────────────────────────────────────┐
│ Opening a file in Vim │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Without Atomic State: With Atomic State: │
│ ───────────────────── ────────────────── │
│ │
│ ┌────────────────────┐ ┌────────────────────┐ │
│ │ │ │ │ │
│ │ partial line 1 │ │ complete file │ │
│ │ par │ → │ with syntax │ │
│ │ ░░░░░ (loading) │ │ highlighting │ │
│ │ │ │ ready instantly │ │
│ └────────────────────┘ └────────────────────┘ │
│ │
│ You see the file being File appears complete │
│ drawn line by line with all colors │
│ │
└─────────────────────────────────────────────────────────────────┘
The Result
No Flicker
Your eyes will thank you. No more visual noise or jitter.
Less CPU
Fewer screen updates means your computer works less hard.
Better Battery
Less processing means longer battery life on laptops.
The Journey of One Character
Ever wonder what happens when you type a single letter? Here’s the complete journey:╔═══════════════════════════════════════════════════════════════════════════════╗
║ THE JOURNEY OF THE LETTER "A" ║
╠═══════════════════════════════════════════════════════════════════════════════╣
║ ║
║ STEP 1: You press "A" on keyboard ║
║ ───────────────────────────────── ║
║ ║
║ ┌─────────┐ ║
║ │ A │ Your finger presses the key ║
║ └────┬────┘ ║
║ │ ║
║ ▼ ║
║ ║
║ STEP 2: Travels to PTY (Background Helper) ║
║ ────────────────────────────────────────── ║
║ ║
║ ┌─────────────────────────────────────┐ ║
║ │ PTY DAEMON │ ║
║ │ ──────────── │ ║
║ │ "I received 'A'. Let me pass it │ ║
║ │ to the shell and get the result." │ ║
║ └────┬────────────────────────────────┘ ║
║ │ ║
║ ▼ ║
║ ║
║ STEP 3: Shell responds with output ║
║ ────────────────────────────────── ║
║ ║
║ ┌─────────────────────────────────────┐ ║
║ │ Raw bytes: 0x41 (the letter "A") │ ║
║ │ + cursor position update │ ║
║ │ + maybe some colors │ ║
║ └────┬────────────────────────────────┘ ║
║ │ ║
║ ▼ ║
║ ║
║ STEP 4: Atomic State processes it ║
║ ───────────────────────────────── ║
║ ║
║ ┌─────────────────────────────────────┐ ║
║ │ ATOMIC STATE (Quality Control) │ ║
║ │ ──────────────────────────── │ ║
║ │ □ Parse the bytes │ ║
║ │ □ Understand the content │ ║
║ │ □ Check if frame is complete │ ║
║ │ □ Calculate what changed │ ║
║ │ ✓ Ready to display! │ ║
║ └────┬────────────────────────────────┘ ║
║ │ ║
║ ▼ ║
║ ║
║ STEP 5: Your screen shows "A" ║
║ ───────────────────────────── ║
║ ║
║ ┌─────────────────────────────────────┐ ║
║ │ $ command_A█ │ ║
║ │ │ ║
║ │ Clean, instant, no flicker! │ ║
║ └─────────────────────────────────────┘ ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════════╝
Safety Nets: What If Something Goes Wrong?
Monolex has built-in protection for edge cases:┌─────────────────────────────────────────────────────────────────────────────────┐
│ TIMEOUT PROTECTION │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ Problem: What if a program hides the cursor but crashes before showing it? │
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Program: "Hide cursor!" ─────▶ [crashes] │ │
│ │ │ │
│ │ Traditional terminal: Cursor stays hidden forever! 😱 │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ Solution: Monolex uses a timeout │
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Program: "Hide cursor!" ─────▶ [crashes] │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ Monolex: ⏰ 16ms timer starts │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ After 16ms: "No end signal? Show anyway!" 💪 │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ Your terminal never gets stuck! │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────────┐
│ INCOMPLETE COMMAND PROTECTION │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ Problem: Network splits a command in half │
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Complete command: "Set color to GREEN" │ │
│ │ │ │
│ │ Network splits it: │ │
│ │ Packet 1: "Set color to GRE" ───▶ arrives first │ │
│ │ Packet 2: "EN" ───▶ arrives 5ms later │ │
│ │ │ │
│ │ Traditional terminal: Garbled output! 😱 │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ Solution: Monolex waits for completion │
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Packet 1 arrives: "Set color to GRE" │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ Monolex: "Incomplete! Wait..." │ │
│ │ │ │ │
│ │ Packet 2 arrives: ▼ │ │
│ │ "EN" ───▶ Complete! Now execute. │ │
│ │ │ │
│ │ Result: Perfect green text! ✨ │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
Legacy App Support
Older programs don’t know about modern synchronization. Monolex handles them too:┌─────────────────────────────────────────────────────────────────────────────────┐
│ VIRTUAL SYNCHRONIZED RENDERING (VSR) │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ Modern programs: │
│ ──────────────── │
│ Send explicit signals: "BEGIN" → content → "END" │
│ Easy for Monolex to detect frame boundaries! │
│ │
│ │
│ Legacy programs (vim, htop, npm): │
│ ───────────────────────────────── │
│ No explicit signals │
│ Just raw screen commands │
│ │
│ Example (htop refresh): │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ T=0ms: Clear screen │ │
│ │ T=1ms: Move cursor to top │ │
│ │ T=2ms: Draw "CPU: 45%" │ │
│ │ T=3ms: Move cursor down │ │
│ │ T=4ms: Draw "MEM: 2.1G" │ │
│ │ ... │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ │
│ How Monolex handles this (VSR): │
│ ─────────────────────────────── │
│ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 1. Detects "Clear screen" command │ │
│ │ 2. Says: "New content is definitely coming!" │ │
│ │ 3. Waits 8 milliseconds to collect everything │ │
│ │ 4. Shows the complete htop screen at once │ │
│ │ │ │
│ │ Result: No flash, no flicker - just smooth htop! 🎉 │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
Summary
╔═══════════════════════════════════════════════════════════════════════════════╗
║ ║
║ ATOMIC STATE IN ONE PICTURE ║
║ ║
║ ┌─────────┐ ┌──────────────┐ ┌─────────────┐ ┌─────────┐ ║
║ │Programs │ ───▶ │ Waiting │ ───▶ │ Quality │ ───▶ │ Your │ ║
║ │ output │ │ Room │ │ Check │ │ Screen │ ║
║ │ data │ │ (buffer) │ │ (is ready?)│ │(perfect)│ ║
║ └─────────┘ └──────────────┘ └─────────────┘ └─────────┘ ║
║ ║
║ Fast, messy Collected, Only complete Clean, ║
║ data stream organized frames pass smooth ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════════╝
You don’t need to do anything! Atomic State works automatically in Monolex. Just enjoy the smooth experience.
Next Steps
Why Monolex is Fast
Learn about the other technologies that make Monolex blazing fast.
Troubleshooting
Having issues? Check our troubleshooting guide.
Want to Go Deeper?
For developers and curious minds who want to understand the technical details:Atomic Loop
Technical details of Virtual Synchronized Rendering - how frame boundaries are detected.
BSU/ESU Protocol
The explicit frame synchronization protocol that modern programs use.