Progressive Streaming

zo's progressive streaming architecture displays responses as they're generated, providing instant feedback and a superior user experience.

How It Works

Dual-Mode Rendering

zo implements a sophisticated dual-mode rendering system:

1. Regular Text - Rendered line-by-line with inline markdown formatting (bold, italic, inline code) applied in real-time
2. Code Blocks - Buffered from opening fence (```) to closing fence, then rendered with full syntax highlighting

This approach ensures:

• ✅ No buffering delay for regular text
• ✅ Professional syntax highlighting for code
• ✅ True streaming UX

Visual Comparison

[Waiting...........................] 10s
[Complete response appears all at once]

[First token appears] ~1s
[Text flows in real-time]
[Code blocks highlight when complete]
[Response completes] ~10s

Technical Implementation

StreamRenderer Architecture

Character Stream → Line Buffer → Decision Point
                                      ↓
                        ┌─────────────┴─────────────┐
                        ↓                           ↓
                 Regular Text              Code Block Fence
                        ↓                           ↓
            Inline Formatting            Buffer Until Close
                        ↓                           ↓
           Immediate Display             Syntax Highlight

Performance Characteristics

• First Token Latency: Approximately 1 second (network + API dependent)
• Regular Text: Immediate display per line
• Code Blocks: Displayed when closing fence received
• Processing Overhead: Minimal (less than 1ms per line)

Rich Markdown Rendering

Inline Elements

Rendered immediately as text streams:

• Headers - # Heading → Rendered in cyan (configurable)
• Bold - **text** → Terminal bold + emphasis color
• Italic - *text* → Terminal italic + emphasis color
• Inline Code - `code` → Yellow (configurable)

Code Blocks

Buffered and syntax-highlighted:

```rust
fn main() {
    println!("Hello, world!");
}
```

Features:

• 100+ programming languages supported
• Professional syntax highlighting (same engine as VS Code)
• 24-bit true color support
• Automatic language detection from fence info

Lists and Tables

- Item 1
- Item 2
  - Nested item
 
| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |

Rendered with proper formatting and alignment.

Syntax Highlighting

Supported Languages

zo uses syntect (the same highlighting engine as VS Code and bat) with support for 100+ languages:

• Rust, Python, JavaScript, TypeScript
• Go, C, C++, Java, Kotlin
• Ruby, PHP, Swift, Shell
• SQL, HTML, CSS, Markdown
• YAML, JSON, TOML, XML
• And many more...

Language Detection

# Automatic detection from fence
zo 'Write a Python script' 
# AI responds with:
```python
def hello():
    print("Hello!")
```

Available Themes

Choose your preferred syntax highlighting theme:

• base16-ocean.dark (default)
• Solarized-dark
• Monokai Extended
• Nord
• Dracula

• base16-ocean.light
• InspiredGitHub
• Solarized-light

theme = "base16-ocean.dark"

Color Customization

Inline Element Colors

Customize colors for inline markdown elements:

# ~/.config/zo/config.toml
 
[inline_colors]
heading = "cyan"        # For # Headers
inline_code = "yellow"  # For `code`
emphasis = "white"      # For *italic* and **bold**

Hex Color Support

[inline_colors]
heading = "#00FFFF"
inline_code = "#FFFF00"
emphasis = "#FFFFFF"

Named Colors

Available named colors:

• black, red, green, yellow
• blue, magenta, cyan, white
• gray, darkgray
• lightred, lightgreen, lightyellow
• lightblue, lightmagenta, lightcyan

Smart Defaults

zo automatically chooses appropriate colors based on your theme:

• Bright colors (cyan, yellow, white)
• High contrast for readability

• Dark colors (blue, magenta, black)
• Optimized for light backgrounds

Real-Time Experience

Immediate Feedback

zo /sonnet 'Explain how TCP works in detail'

1. ~1s - First words appear
2. ~2s - First paragraph visible
3. ~5s - Code example fence opens, buffering starts
4. ~8s - Code fence closes, highlighted code appears
5. ~10s - Response completes

No Buffering Delay

Traditional approach buffers entire response:

Wait 10s → Parse markdown → Highlight → Display

zo's approach streams immediately:

Receive chunk → Render immediately (regular text)
              → Buffer only code blocks

Practical Examples

Long Explanations

zo 'Explain the history of the internet in detail'

• Text appears paragraph by paragraph
• No waiting for complete response
• Can start reading immediately
• Interrupt with Ctrl+C if satisfied

Code Generation

zo /coder 'Implement a web server in Rust with routing and middleware'

• Explanation streams as regular text
• Code blocks appear highlighted when complete
• Multiple code blocks handled correctly
• Maintains context between blocks

Mixed Content

zo 'Explain quicksort with Python implementation and complexity analysis'

1. Introduction text (immediate)
2. Algorithm explanation (immediate)
3. Code block (buffered, highlighted)
4. Complexity analysis (immediate)
5. Example walkthrough (immediate)

Performance Optimization

Character-Level Processing

zo processes streaming response character-by-character to ensure:

• No chunking artifacts
• Correct line boundary detection
• Proper fence marker detection

Efficient Buffering

• Only code blocks are buffered
• Regular text has zero buffering delay
• Memory usage minimal (approximately 1KB per code block)

Terminal Output

• stdout.flush() after each line
• ANSI color codes for styling
• Efficient terminal updates

Comparison

vs Batch Processing

Time to First Token: 10s
Time to Complete: 10s
User Experience: Wait, then read

Time to First Token: 1s
Time to Complete: 10s
User Experience: Read while generating

Improvement: 10x faster perceived response time

vs Other Tools

Configuration

Theme Selection

# Initialize config
zo +init-config
 
# Edit config
vi ~/.config/zo/config.toml
 
# Choose theme
theme = "Monokai Extended"

Color Customization

[inline_colors]
heading = "lightblue"
inline_code = "lightyellow"
emphasis = "lightgreen"

Fallback Behavior

If theme or colors are invalid:

• Falls back to base16-ocean.dark
• Uses sensible color defaults
• Displays warning message
• Continues working

Advanced Features

Multiple Code Blocks

zo correctly handles multiple code blocks in a single response:

First explanation...
 
```python
def example1():
    pass
```
 
More explanation...
 
```rust
fn example2() {}
```
 
Final thoughts...

Each block is syntax-highlighted independently.

Mixed Fence Markers

Supports both ``` and ~~~ fence markers:

```python
code here
```
 
~~~javascript
more code
~~~

Edge Cases

zo handles:

• Empty code blocks
• Code blocks without language specification
• Nested fence markers in inline code
• Unicode characters
• Very long lines (truncated at 2000 chars for performance)

Tips for Best Experience

Use Modern Terminals

For best results, use terminals with:

• 24-bit true color support
• Unicode support
• Good font rendering

• iTerm2 (macOS)
• Alacritty (cross-platform)
• Windows Terminal (Windows)
• GNOME Terminal (Linux)
• kitty (cross-platform)

Terminal Settings

Enable true color support:

# Check if your terminal supports true color
echo $COLORTERM
# Should output: truecolor or 24bit

Font Selection

Use fonts with good unicode support:

• JetBrains Mono
• Fira Code
• Cascadia Code
• Source Code Pro

Troubleshooting

Colors Look Wrong

# Check terminal color support
echo $TERM
# Should be: xterm-256color or better
 
# Try a different theme
# Edit ~/.config/zo/config.toml
theme = "InspiredGitHub"  # Light theme

No Syntax Highlighting

# Verify theme is valid
zo +init-config  # Lists available themes
 
# Check config file
cat ~/.config/zo/config.toml

Slow Performance

# Use faster model for simple tasks
zo /flash 'quick question'
 
# Avoid piping huge files
head -100 large.log | zo 'analyze this'

Next Steps

• Model Selection →
• Configuration →
• View Examples →