DEEP UNDERSTANDING TMUX PROJECTS

Deep Understanding of tmux: From Unix Primitives to Terminal Multiplexing

Goal: Deeply understand terminal multiplexing—how tmux (and screen) actually work at the Unix primitive level. You’ll learn to compose PTYs, sockets, signals, and event loops into a system that survives disconnects, manages multiple sessions, and renders complex UIs. By the end, you’ll be able to build your own terminal multiplexer from scratch and truly understand every feature you use daily.

Why Terminal Multiplexing Matters

In 1987, Oliver Laumann created GNU Screen at the Technical University of Berlin. His goal was simple: let SSH sessions survive network disconnects. This single feature has saved countless hours of work lost to dropped connections over the past 35+ years.

In 2007, Nicholas Marriott created tmux as a BSD-licensed alternative. Today, tmux is:

Essential for remote work: Every serious server administrator, DevOps engineer, and systems programmer uses tmux or screen daily
The foundation of development workflows: Tools like tmuxinator, tmux-resurrect, and countless dotfile configurations depend on deep tmux understanding
A masterclass in Unix design: tmux elegantly composes fundamental Unix primitives—understanding it teaches you Unix itself

But here’s the problem: most developers use tmux as a black box. They memorize keybindings without understanding why detach/attach is even possible. They don’t know what a PTY is or why their session survives SSH disconnects.

This learning path changes that. You’ll build each component yourself and understand tmux from the inside out.

The Conceptual Stack

┌─────────────────────────────────────────────────────────────────┐
│                     User Experience Layer                        │
│    Prefix keys, status bar, copy mode, configuration            │
├─────────────────────────────────────────────────────────────────┤
│                     Session/Window/Pane Layer                    │
│    Hierarchical organization, layouts, switching                 │
├─────────────────────────────────────────────────────────────────┤
│                     Client-Server Layer                          │
│    Daemon, Unix sockets, attach/detach protocol                  │
├─────────────────────────────────────────────────────────────────┤
│                     Terminal Rendering Layer                     │
│    ANSI escape sequences, screen buffers, scrollback            │
├─────────────────────────────────────────────────────────────────┤
│                     Unix Primitives Layer                        │
│    PTYs, signals, fork/exec, event loops, file descriptors       │
└─────────────────────────────────────────────────────────────────┘

You start at the bottom. Each project builds on the previous, adding one layer at a time until you understand the complete system.

Concept Summary Table

Concept Cluster	What You Need to Internalize
Pseudo-terminals (PTYs)	A PTY is a pair of file descriptors that emulate a terminal. The master side is controlled by your program; the slave side looks like a real terminal to child processes. This is how tmux “sits between” you and your shell.
Unix Domain Sockets	IPC mechanism for processes on the same host. The tmux server listens on a socket file; clients connect to send keystrokes and receive screen updates. This is how detach/attach works.
Client-Server Architecture	The tmux server is a daemon that owns all PTYs and sessions. Clients are thin wrappers that render the server’s output. The server survives client disconnects—that’s the magic.
ANSI Escape Sequences	Control codes embedded in text that manipulate cursor position, colors, and screen state. tmux must parse these from programs and re-emit them for your terminal.
Signal Handling	Asynchronous notifications (SIGCHLD when child dies, SIGWINCH when terminal resizes, SIGHUP on disconnect). tmux must handle these correctly to manage process lifecycles and terminal resizing.
Event-Driven I/O	Non-blocking handling of multiple file descriptors (clients, PTYs, signals) without threads. tmux uses libevent internally. Understanding this is key to understanding tmux’s architecture.
Process Groups & Sessions	How Unix groups processes for job control. tmux creates new sessions for managed processes so they don’t interfere with your terminal’s job control.
Terminal Raw Mode	Disabling line buffering and special key handling so your program receives every keystroke immediately. Required for tmux to intercept keys like Ctrl-C.
Screen Buffering	Maintaining a 2D array of characters with attributes (color, bold, etc.) and efficiently updating only what changed. This is how tmux avoids redrawing the entire screen on every update.
Layout Algorithms	How to divide rectangular space among panes and calculate each pane’s dimensions. tmux uses a tree structure where each node is either a container (split horizontally/vertically) or a leaf (pane).

Deep Dive Reading by Concept

This section maps each concept to specific book chapters for deeper understanding. Read these before or alongside the projects to build strong mental models.

Pseudo-Terminals (The Core of Terminal Multiplexing)

Concept	Book & Chapter
What PTYs are and why they exist	The Linux Programming Interface by Michael Kerrisk — Ch. 64: “Pseudoterminals”
Controlling terminals and sessions	The Linux Programming Interface by Michael Kerrisk — Ch. 34: “Process Groups, Sessions, and Job Control”
Terminal line discipline	Advanced Programming in the UNIX Environment by W. Richard Stevens — Ch. 18: “Terminal I/O”
Historical context	The Design of the UNIX Operating System by Maurice Bach — Ch. 10: “Terminal Drivers”

Unix Domain Sockets & IPC

Concept	Book & Chapter
Unix domain socket fundamentals	The Linux Programming Interface by Michael Kerrisk — Ch. 57: “Sockets: Unix Domain”
Socket API in depth	UNIX Network Programming, Vol. 1 by W. Richard Stevens — Ch. 4: “Elementary TCP Sockets” & Ch. 15: “Unix Domain Protocols”
IPC overview and comparisons	The Linux Programming Interface by Michael Kerrisk — Ch. 43: “Interprocess Communication Overview”

Signals and Process Management

Concept	Book & Chapter
Signal concepts	The Linux Programming Interface by Michael Kerrisk — Ch. 20: “Signals: Fundamental Concepts”
Signal handlers	The Linux Programming Interface by Michael Kerrisk — Ch. 21: “Signals: Signal Handlers”
Advanced signal handling	The Linux Programming Interface by Michael Kerrisk — Ch. 22: “Signals: Advanced Features”
Process creation (fork/exec)	Advanced Programming in the UNIX Environment by W. Richard Stevens — Ch. 8: “Process Control”
Process groups and sessions	The Linux Programming Interface by Michael Kerrisk — Ch. 34: “Process Groups, Sessions, and Job Control”

Event-Driven I/O & Multiplexing

Concept	Book & Chapter
I/O multiplexing overview	The Linux Programming Interface by Michael Kerrisk — Ch. 63: “Alternative I/O Models”
select, poll, and epoll	The Linux Programming Interface by Michael Kerrisk — Ch. 63 (sections on each)
Non-blocking I/O	Advanced Programming in the UNIX Environment by W. Richard Stevens — Ch. 14: “Advanced I/O”
Event loop patterns	High Performance Browser Networking by Ilya Grigorik — Ch. 1-2 (conceptual understanding)

ANSI Escape Sequences & Terminal Rendering

Concept	Book & Chapter
Terminal I/O modes	Advanced Programming in the UNIX Environment by W. Richard Stevens — Ch. 18: “Terminal I/O”
terminfo/termcap	The Linux Programming Interface by Michael Kerrisk — Ch. 62: “Terminals”
Escape sequence parsing	Study VT100/VT510 reference manuals (online)
ncurses library	NCURSES Programming HOWTO by TLDP (online)

Daemon and Client-Server Architecture

Concept	Book & Chapter
Daemon process creation	Advanced Programming in the UNIX Environment by W. Richard Stevens — Ch. 13: “Daemon Processes”
The Linux Programming Interface	The Linux Programming Interface by Michael Kerrisk — Ch. 37: “Daemons”
Client-server design	UNIX Network Programming, Vol. 1 by W. Richard Stevens — Ch. 1: “Introduction”

Configuration & Extensibility

Concept	Book & Chapter
Parsing and language design	Language Implementation Patterns by Terence Parr — Ch. 2-4
Command pattern for actions	Design Patterns by Gamma et al. — “Command Pattern”
Plugin architectures	Study Vim/Neovim plugin systems

Essential Reading Order

For maximum comprehension, read in this order:

Foundation (Week 1-2):
- The Linux Programming Interface Ch. 64 (PTYs)
- The Linux Programming Interface Ch. 34 (Process groups/sessions)
- Advanced Programming in the UNIX Environment Ch. 18 (Terminal I/O)
IPC & Networking (Week 2-3):
- The Linux Programming Interface Ch. 57 (Unix domain sockets)
- The Linux Programming Interface Ch. 63 (I/O multiplexing)
Process Management (Week 3-4):
- Advanced Programming in the UNIX Environment Ch. 8 (Process control)
- The Linux Programming Interface Ch. 20-22 (Signals)
Architecture (Week 4+):
- Advanced Programming in the UNIX Environment Ch. 13 (Daemons)
- Study tmux and mtm source code

Core Concept Analysis

To truly understand tmux, you need to understand why it’s even possible. tmux isn’t magic—it’s a clever composition of fundamental Unix primitives:

The Unix Building Blocks of tmux

Primitive	What It Does	How tmux Uses It
Pseudo-terminals (PTYs)	Virtual terminal pairs (master/slave) that let programs pretend to be terminals	tmux creates a PTY for each pane; programs run on the slave side, tmux reads/writes the master side
Unix Domain Sockets	IPC mechanism for processes on the same host	tmux server listens on a socket; clients connect to control sessions
Client-Server Architecture	Server persists state; clients come and go	The tmux server keeps sessions alive; your terminal is just a client
ANSI Escape Sequences	Control codes for cursor, colors, screen manipulation	tmux interprets escape sequences from programs and re-renders them for your terminal
Signal Handling	Asynchronous notifications (SIGWINCH, SIGHUP, etc.)	tmux responds to terminal resizes, disconnects, and child process deaths
Event-Driven I/O	Non-blocking handling of multiple I/O sources	tmux uses libevent to handle multiple clients, panes, and the controlling terminal simultaneously
fork/exec	Process creation and program execution	tmux forks and execs shells/programs in each pane

The “Magic” Explained

When you run tmux, here’s what actually happens:

Server starts (if not running): A daemon process that will outlive your terminal session
Socket created: Usually at /tmp/tmux-$UID/default
PTY allocated: A master/slave pair is created for your first pane
Shell forked: Your shell runs attached to the PTY slave
Client connects: Your terminal becomes a “thin client” that just renders what the server tells it
Event loop runs: The server multiplexes I/O between all panes, clients, and the socket

When you “detach”, the client disconnects—but the server, PTYs, and programs keep running. When you “attach”, a new client connects and the server sends the current screen state.

This is why tmux sessions survive SSH disconnects: The server doesn’t care about your SSH connection; it only cares about the socket.

Project Recommendations

The following projects are ordered to build your understanding progressively. Each project teaches specific Unix primitives that tmux relies on, culminating in building your own terminal multiplexer.

Project 1: PTY Echo Chamber

File: DEEP_UNDERSTANDING_TMUX_PROJECTS.md
Main Programming Language: C
Alternative Programming Languages: Rust, Go, Python
Coolness Level: Level 4: Hardcore Tech Flex
Business Potential: 1. The “Resume Gold” (Educational/Personal Brand)
Difficulty: Level 3: Advanced
Knowledge Area: Operating Systems / Terminal I/O
Software or Tool: PTY (Pseudo-Terminal)
Main Book: “The Linux Programming Interface” by Michael Kerrisk

What you’ll build: A program that allocates a pseudo-terminal, forks a shell onto it, and acts as a “man-in-the-middle” between your real terminal and the shell—logging all I/O to a file.

Why it teaches tmux fundamentals: This is the core mechanism that makes tmux possible. Without understanding PTYs, tmux is pure magic. You’ll see that a PTY is just a pair of file descriptors that act like a terminal, and that you can sit between a program and its “terminal” to intercept everything.

Core challenges you’ll face:

Opening a PTY pair (posix_openpt, grantpt, unlockpt, ptsname) → maps to tmux pane creation
Forking and setting up a controlling terminal (setsid, ioctl TIOCSCTTY) → maps to how programs get their terminal
Proxying I/O in both directions (read/write between real terminal and PTY master) → maps to tmux screen rendering
Raw mode handling (tcgetattr/tcsetattr, disabling echo/canonical mode) → maps to tmux input handling
Window size propagation (ioctl TIOCGWINSZ/TIOCSWINSZ) → maps to tmux pane resizing

Key Concepts:

Pseudo-terminals: “The Linux Programming Interface” Chapter 64 - Michael Kerrisk
Terminal I/O and Raw Mode: “Advanced Programming in the UNIX Environment” Chapter 18 - W. Richard Stevens
Controlling Terminals: “The Linux Programming Interface” Chapter 34 - Michael Kerrisk
PTY Architecture: The Elegant Architecture of PTYs - Krithika Nithyanandam

Difficulty: Advanced Time estimate: 1 week Prerequisites: C basics, understanding of file descriptors, basic Unix process model

Real world outcome:

$ ./pty_echo
# You get a shell prompt that looks normal
$ ls
# Output appears AND is logged to pty_log.txt
$ cat /etc/passwd
# All output logged
$ exit
$ cat pty_log.txt
# See everything that happened, including escape sequences!

You’ll see raw ANSI escape codes in the log file—this is exactly what tmux sees and must interpret.

Implementation Hints: The key insight is that PTYs come in pairs: a “master” side (which your program controls) and a “slave” side (which looks like a real terminal to programs). When you write to the master, it appears as keyboard input on the slave. When a program writes to the slave, you can read it from the master.

You’ll need to put your real terminal into “raw mode” so that key presses are sent immediately (not line-buffered) and special keys like Ctrl-C are passed through instead of generating signals.

Learning milestones:

PTY allocation works, shell starts → You understand the master/slave relationship
I/O proxies correctly, you can type and see output → You understand how tmux intercepts terminal I/O
Log file shows escape sequences → You see the “raw” data that terminals exchange
Window resize propagates correctly → You understand SIGWINCH and how tmux handles pane resizing

The Core Question You’re Answering

“What IS a pseudo-terminal, and how can a program sit between my shell and my real terminal without either knowing?”

Before you write any code, sit with this question. When you type ls in tmux, your keystrokes go through at least two terminals—your real one and a virtual one. How is that even possible? A PTY is the Unix mechanism that makes this work, and understanding it is the key to understanding all of tmux.

Concepts You Must Understand First

Stop and research these before coding:

File Descriptors and I/O
- What is a file descriptor, really?
- Why can you read() and write() to a terminal?
- What does it mean that “everything in Unix is a file”?
- Book Reference: “The Linux Programming Interface” Ch. 4 - Michael Kerrisk
The PTY Master/Slave Relationship
- What’s the difference between the master and slave side of a PTY?
- If you write to the master, where does the data go?
- If a program writes to the slave, where does that data appear?
- Why is this called a “pseudo” terminal?
- Book Reference: “The Linux Programming Interface” Ch. 64 - Michael Kerrisk
Terminal Raw Mode vs Cooked Mode
- What is “canonical mode” (cooked mode)?
- Why does pressing Enter usually send a whole line, not individual characters?
- What happens when you disable echo?
- Why does Ctrl-C normally kill your program, and how do you stop that?
- Book Reference: “Advanced Programming in the UNIX Environment” Ch. 18 - W. Richard Stevens
Controlling Terminals
- What is a “controlling terminal”?
- What does setsid() do and why would you use it?
- What is TIOCSCTTY and when do you need it?
- Book Reference: “The Linux Programming Interface” Ch. 34 - Michael Kerrisk
Terminal Size and SIGWINCH
- How does a terminal know its size?
- What happens when you resize a terminal window?
- How do programs like vim know to redraw when you resize?
- Book Reference: “The Linux Programming Interface” Ch. 64.6 - Michael Kerrisk

Questions to Guide Your Design

Before implementing, think through these:

PTY Allocation
- What system calls create a PTY pair on modern Unix?
- What’s the difference between posix_openpt() and the old BSD openpty()?
- What do grantpt() and unlockpt() do, and why are they needed?
- How do you get the name of the slave device?
Forking the Child
- After fork(), which process should open the PTY slave?
- Why must the child call setsid() before opening the slave?
- What happens if you don’t set up a controlling terminal correctly?
- How does the child know which program to exec (hint: it’s probably the user’s shell)?
The Proxy Loop
- You need to handle data in both directions simultaneously. How?
- What system call lets you wait for activity on multiple file descriptors?
- What happens if you just do blocking reads? (Answer: deadlock)
- How do you detect when the child process exits?
Raw Mode Setup
- Which termios flags need to change for raw mode?
- How do you save the original terminal settings to restore later?
- What happens if your program crashes without restoring settings?
Logging the Data
- Where in your proxy loop do you capture data for the log?
- Should you log the raw bytes or interpret them somehow?
- How will you distinguish input from output in your log?

Thinking Exercise

Trace the data flow by hand before coding:

You type 'l' on your keyboard
         ↓
   [Your real terminal receives the keypress]
         ↓
   [Your program reads from stdin (fd 0)]
         ↓
   [Your program writes to the PTY master]
         ↓
   [Data appears on the PTY slave as if someone typed it]
         ↓
   [The shell running on the slave reads the 'l']
         ↓
   [You type 's' and then Enter...]
         ↓
   [Shell executes 'ls' and writes output to the slave]
         ↓
   [Output appears on the PTY master]
         ↓
   [Your program reads from the PTY master]
         ↓
   [Your program writes to stdout (fd 1)]
         ↓
   [Your real terminal displays the output]

Draw this diagram yourself. Label each file descriptor. Now consider:

Where does your logging happen?
What if data is available on both stdin AND the PTY master at the same time?
What if the child process exits while you’re waiting for data?

The Interview Questions They’ll Ask

Prepare to answer these:

“What is a pseudo-terminal and why does it exist?”
“How does tmux keep running after you disconnect from SSH?”
“What’s the difference between the master and slave side of a PTY?”
“Why do you need to call setsid() when setting up a PTY?”
“What is terminal raw mode and when would you use it?”
“How does a program know when the terminal has been resized?”
“What is TIOCSCTTY and why is it needed?”
“How can you handle I/O on multiple file descriptors without threading?”
“What happens if you try to read from a PTY master and there’s no data?”
“Why can you see ANSI escape sequences in your log file?”

Hints in Layers

Only read these if you’re stuck. Try each step yourself first.

Hint 1: PTY Allocation Sequence The modern POSIX way to create a PTY:

int master = posix_openpt(O_RDWR | O_NOCTTY);
grantpt(master);
unlockpt(master);
char *slave_name = ptsname(master);
// Now you can open slave_name in the child

Hint 2: The Fork and Exec Pattern

pid_t pid = fork();
if (pid == 0) {
    // Child process
    setsid();  // Create new session, become session leader
    int slave = open(slave_name, O_RDWR);
    ioctl(slave, TIOCSCTTY, 0);  // Make this our controlling terminal
    dup2(slave, 0);  // stdin
    dup2(slave, 1);  // stdout
    dup2(slave, 2);  // stderr
    close(slave);
    close(master);
    execlp(getenv("SHELL"), getenv("SHELL"), NULL);
}

Hint 3: Raw Mode Setup

struct termios orig, raw;
tcgetattr(STDIN_FILENO, &orig);
raw = orig;
cfmakeraw(&raw);  // This clears ICANON, ECHO, and other flags
tcsetattr(STDIN_FILENO, TCSANOW, &raw);
// ... do your work ...
tcsetattr(STDIN_FILENO, TCSANOW, &orig);  // Restore on exit!

Hint 4: The Proxy Loop with select()

fd_set read_fds;
while (1) {
    FD_ZERO(&read_fds);
    FD_SET(STDIN_FILENO, &read_fds);
    FD_SET(master, &read_fds);

    if (select(master + 1, &read_fds, NULL, NULL, NULL) < 0) {
        if (errno == EINTR) continue;  // Signal interrupted us
        break;
    }

    if (FD_ISSET(STDIN_FILENO, &read_fds)) {
        // Read from stdin, write to master, log it
    }
    if (FD_ISSET(master, &read_fds)) {
        // Read from master, write to stdout, log it
    }
}

Hint 5: Window Size Propagation

// When you receive SIGWINCH on your real terminal:
struct winsize ws;
ioctl(STDIN_FILENO, TIOCGWINSZ, &ws);  // Get current size
ioctl(master, TIOCSWINSZ, &ws);         // Set on the PTY
// The kernel will send SIGWINCH to processes on the PTY slave

Books That Will Help

Topic	Book	Chapter
PTY fundamentals	“The Linux Programming Interface”	Ch. 64: Pseudoterminals
Terminal I/O and raw mode	“Advanced Programming in the UNIX Environment”	Ch. 18: Terminal I/O
Process groups and sessions	“The Linux Programming Interface”	Ch. 34: Process Groups, Sessions, and Job Control
File descriptors and I/O	“The Linux Programming Interface”	Ch. 4: File I/O - The Universal I/O Model
fork/exec pattern	“Advanced Programming in the UNIX Environment”	Ch. 8: Process Control
I/O multiplexing (select)	“The Linux Programming Interface”	Ch. 63.2.1: select()
Signal handling basics	“The Linux Programming Interface”	Ch. 20: Signals: Fundamental Concepts

Project 2: ANSI Escape Sequence Renderer

File: DEEP_UNDERSTANDING_TMUX_PROJECTS.md
Main Programming Language: C
Alternative Programming Languages: Rust, Python, Go
Coolness Level: Level 3: Genuinely Clever
Business Potential: 1. The “Resume Gold” (Educational/Personal Brand)
Difficulty: Level 3: Advanced
Knowledge Area: Terminal Rendering / Parsing
Software or Tool: VT100/ANSI Terminal
Main Book: “The Linux Programming Interface” by Michael Kerrisk

What you’ll build: A terminal state machine that parses ANSI escape sequences and maintains a virtual screen buffer (2D array of cells with attributes like color, bold, etc.).

Why it teaches tmux fundamentals: tmux must interpret escape sequences from programs running in panes and re-render them to your actual terminal. This project teaches you exactly what tmux’s internal “screen” looks like and how it tracks cursor position, colors, and scrolling.

Core challenges you’ll face:

Parsing CSI sequences (cursor movement, colors, erasing) → maps to tmux screen updates
Maintaining a 2D screen buffer with per-cell attributes → maps to tmux’s internal screen representation
Cursor tracking (absolute vs relative movement) → maps to how tmux knows where to draw
Scrolling regions (DECSTBM) → maps to tmux scroll-back and pane scrolling
Alternate screen buffer (smcup/rmcup) → maps to why vim doesn’t leave garbage when you exit

Key Concepts:

ANSI Escape Codes Overview: Build your own Command Line with ANSI escape codes - Li Haoyi
CSI Sequences Reference: ANSI Escape Sequences Gist - Christian Petersen
VT100 Control Functions: VT510 Reference Manual Chapter 4 - DEC
State Machine Parsing: “Language Implementation Patterns” Chapter 2 - Terence Parr

Difficulty: Intermediate-Advanced Time estimate: 1-2 weeks Prerequisites: State machine concepts, basic parsing, Project 1 completed

Real world outcome:

# Feed your renderer the output from Project 1's log file
$ ./ansi_renderer < pty_log.txt
# See a reconstructed screen showing what the terminal looked like!

# Or pipe live output
$ ls --color=always | ./ansi_renderer
# See the screen buffer with color attributes marked

# Interactive mode
$ ./ansi_renderer --interactive
# Watch the screen buffer update as you feed it escape sequences

Implementation Hints: Build a state machine with states like GROUND, ESCAPE, CSI_ENTRY, CSI_PARAM, etc. Most escape sequences start with ESC [ (CSI - Control Sequence Introducer) followed by numbers and a final letter that determines the action.

Your screen buffer should be a 2D array of “cells”, where each cell contains a character and attributes (foreground color, background color, bold, underline, etc.). Keep track of cursor position as a (row, col) pair.

Learning milestones:

Basic text rendering works → You understand ground state
Cursor movement commands work → You understand CSI parsing
Colors and attributes render correctly → You understand SGR (Select Graphic Rendition)
Scrolling works → You understand scroll regions and the complexity of terminal emulation

The Core Question You’re Answering

“When a program writes \033[31mHello\033[0m, how does my terminal know to show red text? What IS an escape sequence?”

These cryptic-looking byte sequences are the language terminals speak. Every color you see, every cursor movement, every screen clear—it’s all escape sequences. tmux must parse these from programs and re-emit them for your terminal. Understanding this layer is understanding how terminals render anything beyond plain text.

Concepts You Must Understand First

Stop and research these before coding:

What Is an Escape Sequence?
- Why is it called “escape”? What are we escaping from?
- What’s the difference between control characters (like \n) and escape sequences?
- What does ESC (0x1B or \033) mean to a terminal?
- Reference: ANSI X3.64 standard, VT100 User Guide
CSI (Control Sequence Introducer)
- What is ESC [ and why is it so common?
- How do you parse parameters in a CSI sequence (e.g., \033[1;31m)?
- What does the final character determine (e.g., ‘m’ for SGR, ‘H’ for cursor)?
- Reference: ANSI Escape Sequences Gist
State Machines for Parsing
- Why is a state machine the right approach for parsing escape sequences?
- What states do you need (GROUND, ESCAPE, CSI_ENTRY, CSI_PARAM, etc.)?
- How do you handle incomplete sequences (partial input)?
- Book Reference: “Language Implementation Patterns” Ch. 2 - Terence Parr
Screen Buffer Representation
- How do you represent a 2D grid of characters?
- What attributes does each cell need (character, fg color, bg color, bold, underline)?
- What’s the difference between the visible screen and the scrollback buffer?
- Reference: Study libvterm or any terminal emulator source
Cursor State
- What state does the cursor have beyond position (row, col)?
- What’s the difference between absolute and relative cursor movement?
- What is the “saved cursor” and when is it used?

Questions to Guide Your Design

Before implementing, think through these:

Parser Architecture
- How will you represent parser state? An enum? A state transition table?
- Where do you accumulate parameter digits as you parse?
- How do you handle an unknown or unimplemented sequence?
Screen Buffer Design
- Will you use a 2D array or a 1D array with indexing math?
- How do you handle terminal resize (reallocate the buffer)?
- What’s the default character for an empty cell?
Color and Attribute Handling
- How do you represent 16-color, 256-color, and 24-bit color?
- What happens when you see \033[0m (reset)?
- How do you combine attributes (bold AND red AND underlined)?
Cursor Movement
- What’s the difference between \033[H (home) and \033[5;10H (goto)?
- What do \033[A, \033[B, \033[C, \033[D do?
- How do you handle cursor moves that would go out of bounds?
Scrolling
- What happens when you write to the last line and need to scroll?
- What is \033[r (DECSTBM - set scroll region)?
- How does the alternate screen buffer work?

Thinking Exercise

Parse this sequence by hand:

\033[2J\033[H\033[1;31mERROR:\033[0m File not found\n\033[3A\033[10C!

Step by step:

\033[2J → CSI with param 2, final ‘J’ = Erase in Display (clear entire screen)
\033[H → CSI with no params, final ‘H’ = Cursor Position (go to 1,1)
\033[1;31m → CSI with params [1, 31], final ‘m’ = SGR (bold + red foreground)
ERROR: → Literal text, written at cursor position with current attributes
\033[0m → CSI with param 0, final ‘m’ = SGR (reset all attributes)
` File not found` → Literal text, written with default attributes
\n → Control character, move cursor to next line
\033[3A → CSI with param 3, final ‘A’ = Cursor Up (move up 3 lines)
\033[10C → CSI with param 10, final ‘C’ = Cursor Forward (move right 10 columns)
! → Literal text, written at new cursor position

Now draw what the screen looks like. Where is the cursor? What color is each character?

The Interview Questions They’ll Ask

Prepare to answer these:

“How does a terminal display colored text?”
“What is an ANSI escape sequence and why is it called that?”
“How would you parse escape sequences efficiently?”
“What’s the difference between CSI and OSC sequences?”
“What is SGR and what can it control?”
“How does the alternate screen buffer work and why do programs use it?”
“What happens when a program outputs an incomplete escape sequence?”
“How does tmux handle programs that use color differently than your terminal supports?”
“What is DECSTBM and why is it important for terminal emulation?”
“How would you implement efficient screen updates (only redraw what changed)?”

Hints in Layers

Only read these if you’re stuck. Try each step yourself first.

Hint 1: Basic State Machine Structure

typedef enum {
    STATE_GROUND,      // Normal text processing
    STATE_ESCAPE,      // Saw ESC (0x1B)
    STATE_CSI_ENTRY,   // Saw ESC [
    STATE_CSI_PARAM,   // Collecting numeric parameters
    STATE_CSI_IGNORE,  // Invalid sequence, skip to end
} ParserState;

typedef struct {
    ParserState state;
    int params[16];    // Numeric parameters
    int param_count;
    int current_param; // Accumulator for current number
} Parser;

Hint 2: Cell and Screen Structure

typedef struct {
    uint32_t ch;       // Unicode codepoint (or char for ASCII only)
    uint8_t fg;        // Foreground color
    uint8_t bg;        // Background color
    uint8_t attrs;     // Bold, underline, etc. as bit flags
} Cell;

typedef struct {
    Cell *cells;       // rows * cols cells
    int rows;
    int cols;
    int cursor_row;
    int cursor_col;
    uint8_t current_fg;
    uint8_t current_bg;
    uint8_t current_attrs;
} Screen;

Hint 3: Processing a CSI Sequence

void handle_csi_final(Screen *screen, char final, int *params, int count) {
    switch (final) {
        case 'H': case 'f':  // Cursor position
            screen->cursor_row = (count > 0 ? params[0] : 1) - 1;
            screen->cursor_col = (count > 1 ? params[1] : 1) - 1;
            break;
        case 'A':  // Cursor up
            screen->cursor_row -= (count > 0 ? params[0] : 1);
            break;
        case 'm':  // SGR - Select Graphic Rendition
            handle_sgr(screen, params, count);
            break;
        case 'J':  // Erase in display
            handle_ed(screen, count > 0 ? params[0] : 0);
            break;
        // ... many more
    }
}

Hint 4: SGR (Color/Attribute) Handling

void handle_sgr(Screen *screen, int *params, int count) {
    for (int i = 0; i < count; i++) {
        int p = params[i];
        if (p == 0) {
            // Reset all attributes
            screen->current_fg = 7;  // Default white
            screen->current_bg = 0;  // Default black
            screen->current_attrs = 0;
        } else if (p == 1) {
            screen->current_attrs |= ATTR_BOLD;
        } else if (p >= 30 && p <= 37) {
            screen->current_fg = p - 30;  // Standard foreground colors
        } else if (p >= 40 && p <= 47) {
            screen->current_bg = p - 40;  // Standard background colors
        }
        // Handle 256-color (38;5;N) and truecolor (38;2;R;G;B) separately
    }
}

Hint 5: Rendering the Screen (for debugging)

void print_screen(Screen *screen) {
    for (int row = 0; row < screen->rows; row++) {
        for (int col = 0; col < screen->cols; col++) {
            Cell *c = &screen->cells[row * screen->cols + col];
            // Print with ANSI colors for visualization
            printf("\033[%d;%dm%c\033[0m",
                   c->attrs & ATTR_BOLD ? 1 : 0,
                   30 + c->fg,
                   c->ch ? c->ch : ' ');
        }
        printf("\n");
    }
    printf("Cursor at (%d, %d)\n", screen->cursor_row, screen->cursor_col);
}

Books That Will Help

Topic	Book	Chapter
Escape sequence fundamentals	VT510 Reference Manual	Ch. 4: Control Functions
State machine parsing	“Language Implementation Patterns”	Ch. 2: Basic Parsing Patterns
Terminal capabilities	“Advanced Programming in the UNIX Environment”	Ch. 18: Terminal I/O
Data structure design	“The C Programming Language”	Ch. 6: Structures
ncurses for comparison	“NCURSES Programming HOWTO”	All chapters

Project 3: Unix Domain Socket Chat

File: DEEP_UNDERSTANDING_TMUX_PROJECTS.md
Main Programming Language: C
Alternative Programming Languages: Rust, Go, Python
Coolness Level: Level 2: Practical but Forgettable
Business Potential: 1. The “Resume Gold” (Educational/Personal Brand)
Difficulty: Level 2: Intermediate
Knowledge Area: IPC / Networking
Software or Tool: Unix Domain Sockets
Main Book: “The Linux Programming Interface” by Michael Kerrisk

What you’ll build: A chat system with a server daemon and multiple clients that communicate over a Unix domain socket—the exact IPC mechanism tmux uses.

Why it teaches tmux fundamentals: This is how the tmux server and clients communicate. When you type tmux attach, you’re connecting to a Unix socket. When you type keys, they go over the socket to the server. When the screen updates, the server sends data back over the socket.

Core challenges you’ll face:

Creating and binding a socket (socket(AF_UNIX, SOCK_STREAM, 0), bind) → maps to tmux server startup
Handling multiple clients (select/poll/epoll or forking) → maps to tmux multi-client support
Message framing (how do you know where one message ends and another begins?) → maps to tmux protocol
Graceful disconnect handling → maps to tmux client detach
Permission management (socket file permissions) → maps to tmux session security

Key Concepts:

Unix Domain Sockets: “The Linux Programming Interface” Chapter 57 - Michael Kerrisk
Socket API: “The Sockets Networking API: UNIX Network Programming Volume 1” Chapters 4, 15 - W. Richard Stevens
I/O Multiplexing: “The Linux Programming Interface” Chapter 63 - Michael Kerrisk
Practical Example: UNIX Domain Socket Tutorial - NTU

Difficulty: Intermediate Time estimate: 3-5 days Prerequisites: Basic C, file descriptors, basic process model

Real world outcome:

# Terminal 1: Start the server
$ ./chat_server
Server listening on /tmp/chat.sock

# Terminal 2: Connect as client
$ ./chat_client alice
Connected as alice
> Hello everyone!

# Terminal 3: Connect as another client
$ ./chat_client bob
Connected as bob
[alice]: Hello everyone!
> Hey Alice!

# Terminal 2 sees:
[bob]: Hey Alice!

# If Terminal 2 disconnects, Terminal 3 sees:
[SERVER]: alice has disconnected

Implementation Hints: The socket path (e.g., /tmp/chat.sock) is like a rendezvous point. The server creates it with bind(), clients connect to it with connect(). After connection, it’s just file descriptors—read() and write() work normally.

For handling multiple clients, start with select() which lets you wait for activity on multiple file descriptors. Later you can explore epoll for better performance.

Learning milestones:

Single client connects and chats → You understand basic socket flow
Multiple clients work simultaneously → You understand I/O multiplexing
Disconnection is handled gracefully → You understand connection lifecycle
Server survives client crashes → You understand robust IPC

The Core Question You’re Answering

“How does the tmux server keep running after you close your terminal, and how does tmux attach reconnect to it?”

The answer is Unix domain sockets—a file-based IPC mechanism where a “socket file” acts as a rendezvous point. The server listens on this file; clients connect to it. When you detach, the client just disconnects—the server keeps running because it doesn’t care about your terminal at all.

Concepts You Must Understand First

Stop and research these before coding:

Socket Fundamentals
- What is a socket? How is it different from a regular file descriptor?
- What’s the difference between SOCK_STREAM and SOCK_DGRAM?
- What is the socket lifecycle (socket → bind → listen → accept)?
- Book Reference: “The Linux Programming Interface” Ch. 56-57 - Michael Kerrisk
Unix Domain vs Internet Sockets
- Why use AF_UNIX instead of AF_INET for local communication?
- What is the socket file on disk? What happens if it already exists?
- What are the performance differences?
- Book Reference: “UNIX Network Programming, Vol. 1” Ch. 15 - W. Richard Stevens
I/O Multiplexing with select()
- Why can’t you just call accept() in a loop to handle multiple clients?
- How does select() let you wait on multiple file descriptors?
- What’s the difference between select(), poll(), and epoll()?
- Book Reference: “The Linux Programming Interface” Ch. 63 - Michael Kerrisk
Message Framing
- Why is “message framing” a problem with stream sockets?
- If you send “Hello” and then “World”, what might the receiver get?
- What techniques exist for framing (length prefix, delimiter, fixed size)?
- Reference: Beej’s Guide to Network Programming
Connection Lifecycle
- What happens when a client closes its connection?
- How do you detect that a client has disconnected?
- What is the SO_REUSEADDR socket option and why might you need it?

Questions to Guide Your Design

Before implementing, think through these:

Socket Path
- Where should the socket file live? (/tmp? $XDG_RUNTIME_DIR?)
- How do you make the socket path unique per user?
- What if the socket file exists from a crashed server?
Server Architecture
- How do you handle multiple clients simultaneously?
- Do you use one process per client (fork) or handle all in one event loop?
- What data structure tracks connected clients?
Message Protocol
- What information needs to flow from client to server?
- What information needs to flow from server to clients?
- How do you broadcast a message to all clients?
Error Handling
- What if bind() fails because the socket file exists?
- What if a client sends malformed data?
- What if write() to a client fails?
Clean Shutdown
- How do you handle Ctrl-C on the server?
- Do you notify clients before shutting down?
- How do you remove the socket file when done?

Thinking Exercise

Design your message protocol on paper:

Client → Server Messages:
┌───────────────┬──────────────────────────────────────┐
│ Message Type  │ Payload                              │
├───────────────┼──────────────────────────────────────┤
│ JOIN          │ Username (null-terminated string)    │
│ MESSAGE       │ Text content                         │
│ QUIT          │ (empty)                              │
└───────────────┴──────────────────────────────────────┘

Server → Client Messages:
┌───────────────┬──────────────────────────────────────┐
│ Message Type  │ Payload                              │
├───────────────┼──────────────────────────────────────┤
│ WELCOME       │ Client ID, current user list         │
│ USER_JOINED   │ Username                             │
│ USER_LEFT     │ Username                             │
│ BROADCAST     │ Sender + Message text                │
└───────────────┴──────────────────────────────────────┘

Now decide:

How do you encode message types? (enum byte? string?)
How do you encode variable-length payloads? (length prefix? newline?)
How big should your read buffer be?

The Interview Questions They’ll Ask

Prepare to answer these:

“What is a Unix domain socket and how does it differ from a TCP socket?”
“How would you handle multiple simultaneous clients in a server?”
“What is the select() system call and when would you use it?”
“How do you handle the case where a client disconnects unexpectedly?”
“What is message framing and why is it necessary?”
“What happens if you try to bind to a socket path that already exists?”
“How does tmux use Unix domain sockets internally?”
“What are the security implications of socket file permissions?”
“How would you implement a graceful shutdown of a socket server?”
“What’s the difference between blocking and non-blocking I/O?”

Hints in Layers

Only read these if you’re stuck. Try each step yourself first.

Hint 1: Creating a Unix Domain Socket Server

int server_fd = socket(AF_UNIX, SOCK_STREAM, 0);

struct sockaddr_un addr;
memset(&addr, 0, sizeof(addr));
addr.sun_family = AF_UNIX;
strncpy(addr.sun_path, "/tmp/chat.sock", sizeof(addr.sun_path) - 1);

unlink(addr.sun_path);  // Remove old socket file if exists
bind(server_fd, (struct sockaddr*)&addr, sizeof(addr));
listen(server_fd, 5);

Hint 2: Accept Loop with select()

fd_set active_fds, read_fds;
FD_ZERO(&active_fds);
FD_SET(server_fd, &active_fds);
int max_fd = server_fd;

while (1) {
    read_fds = active_fds;  // select() modifies the set
    if (select(max_fd + 1, &read_fds, NULL, NULL, NULL) < 0) break;

    if (FD_ISSET(server_fd, &read_fds)) {
        int client_fd = accept(server_fd, NULL, NULL);
        FD_SET(client_fd, &active_fds);
        if (client_fd > max_fd) max_fd = client_fd;
    }

    // Check each client for activity...
}

Hint 3: Simple Length-Prefixed Protocol

// Send a message with length prefix
void send_message(int fd, const char *msg) {
    uint32_t len = strlen(msg);
    uint32_t net_len = htonl(len);  // Network byte order
    write(fd, &net_len, 4);
    write(fd, msg, len);
}

// Receive a message
char* recv_message(int fd) {
    uint32_t net_len;
    if (read(fd, &net_len, 4) != 4) return NULL;  // Client disconnected
    uint32_t len = ntohl(net_len);
    char *buf = malloc(len + 1);
    read(fd, buf, len);
    buf[len] = '\0';
    return buf;
}

Hint 4: Detecting Client Disconnect

// When read() returns 0, the client has closed the connection
char buf[1024];
ssize_t n = read(client_fd, buf, sizeof(buf));
if (n <= 0) {
    // n == 0: graceful close
    // n < 0: error (check errno)
    close(client_fd);
    FD_CLR(client_fd, &active_fds);
    // Notify other clients...
}

Hint 5: Client Connection

int client_fd = socket(AF_UNIX, SOCK_STREAM, 0);

struct sockaddr_un addr;
memset(&addr, 0, sizeof(addr));
addr.sun_family = AF_UNIX;
strncpy(addr.sun_path, "/tmp/chat.sock", sizeof(addr.sun_path) - 1);

if (connect(client_fd, (struct sockaddr*)&addr, sizeof(addr)) < 0) {
    perror("connect");
    // Server not running?
    exit(1);
}
// Now read/write to client_fd

Books That Will Help

Topic	Book	Chapter
Unix domain sockets	“The Linux Programming Interface”	Ch. 57: Sockets: Unix Domain
Socket API fundamentals	“UNIX Network Programming, Vol. 1”	Ch. 4: Elementary TCP Sockets
I/O multiplexing	“The Linux Programming Interface”	Ch. 63: Alternative I/O Models
Protocol design	“UNIX Network Programming, Vol. 1”	Ch. 15: Unix Domain Protocols
Error handling	“The Linux Programming Interface”	Ch. 56: Sockets: Introduction

Project 4: Signal-Aware Process Supervisor

File: DEEP_UNDERSTANDING_TMUX_PROJECTS.md
Main Programming Language: C
Alternative Programming Languages: Rust, Go
Coolness Level: Level 3: Genuinely Clever
Business Potential: 3. The “Service & Support” Model
Difficulty: Level 3: Advanced
Knowledge Area: Process Management / Signals
Software or Tool: Process Supervisor / Init System
Main Book: “Advanced Programming in the UNIX Environment” by W. Richard Stevens

What you’ll build: A process supervisor that spawns child processes, monitors them, handles their termination (including signals), and can restart them—like a mini-init or mini-systemd.

Why it teaches tmux fundamentals: tmux must manage the lifecycle of all the programs running in panes. When you close a pane, tmux must kill the process. When a process exits, tmux must update the pane. When you resize a window, tmux must send SIGWINCH to processes.

Core challenges you’ll face:

Forking and executing child processes (fork, exec* family) → maps to tmux pane process creation
Handling SIGCHLD (child death notification) → maps to tmux pane process exit handling
Signal forwarding (sending signals to managed processes) → maps to tmux kill-pane, send-keys
Process groups and sessions (setpgid, setsid) → maps to tmux session/window process hierarchy
Zombie prevention (waitpid with WNOHANG) → maps to tmux resource cleanup

Key Concepts:

Process Control: “Advanced Programming in the UNIX Environment” Chapter 8 - W. Richard Stevens
Signals: “The Linux Programming Interface” Chapters 20-22 - Michael Kerrisk
Process Groups and Sessions: “The Linux Programming Interface” Chapter 34 - Michael Kerrisk
Signal Handler Example: Unix signal handling example in C - aspyct

Difficulty: Advanced Time estimate: 1 week Prerequisites: fork/exec basics, signal fundamentals, Project 3 completed

Real world outcome:

$ ./supervisor
supervisor> spawn sleep 100
[1] Started: sleep 100 (PID 12345)

supervisor> spawn top
[2] Started: top (PID 12346)

supervisor> list
[1] RUNNING sleep 100 (PID 12345)
[2] RUNNING top (PID 12346)

supervisor> kill 1
[1] Killed: sleep 100

supervisor>
[2] Exited: top (status 0)  # When you quit top

supervisor> spawn bash
[3] Started: bash (PID 12347)

# Ctrl-C here doesn't kill the supervisor, it forwards to the child

Implementation Hints: Use sigaction() instead of signal() for reliable signal handling. Set up a SIGCHLD handler that calls waitpid(-1, &status, WNOHANG) in a loop to reap all terminated children.

When creating child processes, use setpgid(0, 0) to put them in their own process group. This lets you send signals to the entire group later.

Learning milestones:

Can spawn and track processes → You understand fork/exec
Detects when children exit → You understand SIGCHLD
Can send signals to managed processes → You understand signal forwarding
Handles multiple rapid exits correctly → You understand robust signal handling

The Core Question You’re Answering

“When I close a tmux pane, how does tmux know to update the display? When I press Ctrl-C, how does the signal reach the right process?”

tmux manages dozens of child processes across multiple panes. It must know when they exit, be able to kill them on demand, and correctly propagate signals. Understanding process groups, sessions, and signal handling is essential for any program that supervises child processes.

Concepts You Must Understand First

Stop and research these before coding:

fork() and exec()
- What exactly does fork() return in the parent vs child?
- Why is the exec() family of functions so large? What’s the difference?
- What happens to file descriptors across fork? Across exec?
- Book Reference: “Advanced Programming in the UNIX Environment” Ch. 8 - W. Richard Stevens
Signals and Signal Handlers
- What is a signal? How is it different from a function call?
- What can you safely do in a signal handler (and what can’t you do)?
- What’s the difference between signal() and sigaction()?
- Book Reference: “The Linux Programming Interface” Ch. 20-22 - Michael Kerrisk
SIGCHLD and Zombie Processes
- What is SIGCHLD and when is it delivered?
- What is a zombie process and why does it exist?
- What does waitpid() do and what options does it take?
- Book Reference: “The Linux Programming Interface” Ch. 26 - Michael Kerrisk
Process Groups and Sessions
- What is a process group? What is a session?
- What does setpgid() do?
- Why would you put a child in its own process group?
- Book Reference: “The Linux Programming Interface” Ch. 34 - Michael Kerrisk
Sending Signals
- What’s the difference between kill(pid, sig) and kill(-pgid, sig)?
- What is SIGTERM vs SIGKILL? When would you use each?
- What is SIGWINCH and when is it sent?

Questions to Guide Your Design

Before implementing, think through these:

Child Tracking
- What data structure do you use to track child processes?
- What information do you need to store for each child?
- How do you find a child by PID vs by ID?
Signal Handler Design
- What’s the minimum work you should do in a SIGCHLD handler?
- How do you communicate from the signal handler to your main loop?
- What’s the “self-pipe trick” and why might you need it?
Spawn Semantics
- Should child processes inherit your signal handlers?
- Should children be in their own process group?
- What environment does the child inherit?
Signal Forwarding
- When you receive SIGTERM, what should happen to children?
- How do you forward Ctrl-C to a specific child?
- How do you handle sending signals to an already-dead process?
Clean Exit
- How do you reap all zombies before exiting?
- What if a child refuses to die after SIGTERM?
- Should you wait indefinitely or timeout?

Thinking Exercise

Trace the signal flow by hand:

You have processes:
  Supervisor (PID 1000, PGID 1000)
    ├── Child A (PID 1001, PGID 1001) ← in its own process group
    │     └── Grandchild (PID 1002, PGID 1001)
    └── Child B (PID 1003, PGID 1003) ← in its own process group

Scenario: User presses Ctrl-C while Child A is "focused"

Questions:

Who receives SIGINT first?
Does the supervisor receive SIGINT?
Does Child B receive SIGINT?
What if Child A ignores SIGINT?

Scenario 2: Child A exits normally

Who receives SIGCHLD?
What happens to the Grandchild?
What’s the Grandchild’s new parent?

The Interview Questions They’ll Ask

Prepare to answer these:

“What is a zombie process and how do you prevent them?”
“What’s the difference between SIGTERM and SIGKILL?”
“How does a process supervisor know when a child process exits?”
“What can and can’t you do safely in a signal handler?”
“What is a process group and why would you use one?”
“How do you send a signal to a group of related processes?”
“What happens to child processes when the parent dies?”
“What is the self-pipe trick and when would you use it?”
“How does tmux handle sending Ctrl-C to a specific pane?”
“What’s the difference between waitpid with WNOHANG and blocking wait?”

Hints in Layers

Only read these if you’re stuck. Try each step yourself first.

Hint 1: Proper SIGCHLD Handler Setup

void sigchld_handler(int sig) {
    // Save and restore errno—signal handler might interrupt code that uses it
    int saved_errno = errno;

    // Reap ALL available zombies (multiple children might exit rapidly)
    while (1) {
        int status;
        pid_t pid = waitpid(-1, &status, WNOHANG);
        if (pid <= 0) break;  // No more zombies

        // Record the exit for main loop to process later
        // (Use a simple flag or self-pipe trick for safety)
    }

    errno = saved_errno;
}

// Install with sigaction for reliability
struct sigaction sa;
sa.sa_handler = sigchld_handler;
sigemptyset(&sa.sa_mask);
sa.sa_flags = SA_RESTART | SA_NOCLDSTOP;  // Don't notify for stop/continue
sigaction(SIGCHLD, &sa, NULL);

Hint 2: Spawning a Child in Its Own Process Group

pid_t spawn(const char *cmd) {
    pid_t pid = fork();
    if (pid == 0) {
        // Child process
        setpgid(0, 0);  // Put child in its own process group
        execlp(cmd, cmd, NULL);
        _exit(127);  // exec failed
    }
    // Parent: also set child's pgid (race condition prevention)
    setpgid(pid, pid);
    return pid;
}

Hint 3: Sending Signals to a Process Group

// Kill an entire process group
void kill_job(pid_t pgid) {
    // Send SIGTERM first for graceful shutdown
    kill(-pgid, SIGTERM);

    // Give it a moment
    sleep(1);

    // Check if still alive and force kill if necessary
    if (kill(-pgid, 0) == 0) {
        kill(-pgid, SIGKILL);
    }
}

Hint 4: The Self-Pipe Trick

int selfpipe[2];
pipe(selfpipe);
fcntl(selfpipe[0], F_SETFL, O_NONBLOCK);
fcntl(selfpipe[1], F_SETFL, O_NONBLOCK);

void sigchld_handler(int sig) {
    int saved_errno = errno;
    write(selfpipe[1], "x", 1);  // Wake up the event loop
    errno = saved_errno;
}

// In your select() loop:
FD_SET(selfpipe[0], &read_fds);
// ...
if (FD_ISSET(selfpipe[0], &read_fds)) {
    char buf[16];
    read(selfpipe[0], buf, sizeof(buf));  // Drain the pipe
    reap_children();  // Now safe to call reaping logic
}

Hint 5: Tracking Children

typedef struct {
    pid_t pid;
    pid_t pgid;
    int id;  // User-visible job number
    char *cmd;
    int status;  // Exit status once reaped
    int alive;   // Still running?
} Job;

#define MAX_JOBS 100
Job jobs[MAX_JOBS];
int job_count = 0;

Job* find_job_by_pid(pid_t pid) {
    for (int i = 0; i < job_count; i++) {
        if (jobs[i].pid == pid) return &jobs[i];
    }
    return NULL;
}

Books That Will Help

Topic	Book	Chapter
Process creation (fork/exec)	“Advanced Programming in the UNIX Environment”	Ch. 8: Process Control
Signal fundamentals	“The Linux Programming Interface”	Ch. 20: Signals: Fundamental Concepts
Signal handlers	“The Linux Programming Interface”	Ch. 21: Signals: Signal Handlers
Child process monitoring	“The Linux Programming Interface”	Ch. 26: Monitoring Child Processes
Process groups and sessions	“The Linux Programming Interface”	Ch. 34: Process Groups, Sessions, and Job Control

Project 5: Event-Driven I/O Multiplexer

File: DEEP_UNDERSTANDING_TMUX_PROJECTS.md
Main Programming Language: C
Alternative Programming Languages: Rust, Go
Coolness Level: Level 3: Genuinely Clever
Business Potential: 4. The “Open Core” Infrastructure
Difficulty: Level 3: Advanced
Knowledge Area: Systems Programming / Event Loops
Software or Tool: libevent / epoll
Main Book: “The Linux Programming Interface” by Michael Kerrisk

What you’ll build: An event loop library (or use libevent) that handles multiple file descriptors, timers, and signals in a single-threaded, non-blocking manner—then use it to build a more robust version of the chat server.

Why it teaches tmux fundamentals: tmux uses libevent internally. A terminal multiplexer must handle: multiple client connections, multiple PTY outputs, keyboard input, signals, and timers—all without blocking on any single source.

Core challenges you’ll face:

Understanding epoll/kqueue/select (platform-specific I/O multiplexing) → maps to tmux’s cross-platform event handling
Integrating signals into the event loop (signalfd or self-pipe trick) → maps to tmux signal integration
Non-blocking I/O (O_NONBLOCK, handling EAGAIN) → maps to tmux responsive I/O
Timer management (for things like status line refresh) → maps to tmux periodic updates
Callback-based programming → maps to tmux’s internal architecture

Key Concepts:

epoll: “The Linux Programming Interface” Chapter 63 - Michael Kerrisk
libevent Basics: A Gentle Intro to libevent - Gaurav
Event Loop Patterns: libevent Echo Server Tutorial - Pacific Simplicity
Non-blocking I/O: “Advanced Programming in the UNIX Environment” Chapter 14 - W. Richard Stevens

Difficulty: Advanced Time estimate: 1-2 weeks Prerequisites: I/O multiplexing basics (select/poll), signal handling, Project 3-4 completed

Real world outcome:

# Enhanced chat server with event loop
$ ./event_chat_server
[EVENT] Listening on /tmp/chat.sock
[EVENT] Timer registered: status every 5s

# Connect clients...
[EVENT] New client connected
[EVENT] Read ready on client 1
[EVENT] Timer fired: 2 clients connected, 42 messages sent
[EVENT] Signal: SIGWINCH (terminal resized)
[EVENT] Read ready on client 2

# All handled in a single thread, no blocking!

Implementation Hints: If building from scratch, start with epoll_create1, epoll_ctl, and epoll_wait on Linux. The key insight is that epoll_wait returns only the file descriptors that are ready, so you never block on I/O that isn’t available.

For signals, use signalfd() to turn signals into file descriptor events that integrate with your event loop. Alternatively, use the classic “self-pipe trick”: the signal handler writes a byte to a pipe, and the event loop reads from that pipe.

Learning milestones:

Event loop handles multiple connections → You understand epoll
Signals integrate cleanly → You understand signal integration strategies
Timers fire correctly → You understand timer management
No busy-waiting, minimal CPU usage → You understand efficient event loops

The Core Question You’re Answering

“How does tmux handle input from multiple clients, output from multiple PTYs, and signals—all without blocking on any single one?”

The answer is event-driven I/O. Instead of using threads or processes, tmux uses a single event loop that efficiently waits for activity on any of its file descriptors. Understanding this pattern is understanding how to build scalable, responsive systems programs.

Concepts You Must Understand First

Stop and research these before coding:

Why I/O Multiplexing Exists
- Why can’t you just use multiple threads?
- What’s the problem with blocking I/O when you have multiple sources?
- What does “the C10K problem” refer to?
- Book Reference: “The Linux Programming Interface” Ch. 63.1 - Michael Kerrisk
select(), poll(), and epoll()
- What are the differences between these three?
- What are the performance characteristics of each?
- Why is epoll Linux-specific and what’s the portable alternative?
- Book Reference: “The Linux Programming Interface” Ch. 63.2-63.4 - Michael Kerrisk
Non-Blocking I/O
- What does O_NONBLOCK do?
- What happens when you read from a non-blocking fd with no data?
- What is EAGAIN and how do you handle it?
- Book Reference: “Advanced Programming in the UNIX Environment” Ch. 14 - W. Richard Stevens
Event Loop Architecture
- What is the basic structure of an event loop?
- What is a callback function and how is it used in event loops?
- How do timers integrate with event loops?
- Reference: libevent documentation, libev documentation
Integrating Signals
- Why is it dangerous to call arbitrary functions from signal handlers?
- What is signalfd() and how does it help?
- What is the self-pipe trick and when do you use it?
- Book Reference: “The Linux Programming Interface” Ch. 22.9 - Michael Kerrisk

Questions to Guide Your Design

Before implementing, think through these:

Event Loop Core
- What data structures track registered file descriptors?
- How do you map an fd to its handler function?
- What’s your main loop structure?
epoll Specifics
- What’s the difference between EPOLLIN and EPOLLOUT?
- What is edge-triggered vs level-triggered mode?
- How do you modify an already-registered fd?
Timer Implementation
- How do you implement timers without a dedicated timer thread?
- What data structure efficiently tracks pending timers? (heap?)
- How do you integrate timers with epoll_wait’s timeout?
Signal Integration
- How do you block signals in the main thread?
- How does signalfd() convert signals to file events?
- What if you need portability to systems without signalfd()?
API Design
- What interface do users get to register handlers?
- How do they request one-shot vs repeating handlers?
- How do they cancel a registered handler?

Thinking Exercise

Design the event loop on paper:

// Your API might look like:
EventLoop *loop = eventloop_new();

// Register a read handler
eventloop_add_fd(loop, client_fd, EVENT_READ, on_client_data, client);

// Register a timer
eventloop_add_timer(loop, 5000, on_timeout, NULL);  // 5 second timer

// Register a signal handler
eventloop_add_signal(loop, SIGTERM, on_shutdown, NULL);

// Run forever (or until someone stops it)
eventloop_run(loop);

Draw the internal data structures:

How does eventloop_add_fd store the mapping from fd → callback?
How does eventloop_add_timer order timers by expiration time?
What does eventloop_run do in each iteration?

The Interview Questions They’ll Ask

Prepare to answer these:

“What is epoll and how does it differ from select()?”
“What’s the difference between edge-triggered and level-triggered modes?”
“How would you implement timers in an event loop?”
“What is non-blocking I/O and when would you use it?”
“How do you integrate signal handling with an event loop?”
“What is the C10K problem and how do modern servers address it?”
“What’s the difference between libevent, libev, and libuv?”
“How does tmux handle multiple clients without threading?”
“What happens if a callback function blocks in an event loop?”
“How would you prioritize certain events over others?”

Hints in Layers

Only read these if you’re stuck. Try each step yourself first.

Hint 1: Basic epoll Setup

int epfd = epoll_create1(0);

struct epoll_event ev;
ev.events = EPOLLIN;
ev.data.fd = fd;  // Or use data.ptr for a struct
epoll_ctl(epfd, EPOLL_CTL_ADD, fd, &ev);

struct epoll_event events[MAX_EVENTS];
int n = epoll_wait(epfd, events, MAX_EVENTS, timeout_ms);
for (int i = 0; i < n; i++) {
    int ready_fd = events[i].data.fd;
    // Handle events[i].events (EPOLLIN, EPOLLOUT, EPOLLERR, etc.)
}

Hint 2: Timer Implementation with a Min-Heap

typedef struct {
    uint64_t expiration_ms;  // Absolute time
    void (*callback)(void*);
    void *arg;
} Timer;

// Use a binary heap for O(log n) insert and O(1) get-min
Timer *timer_heap[MAX_TIMERS];
int timer_count = 0;

int next_timer_timeout_ms() {
    if (timer_count == 0) return -1;  // Block indefinitely
    uint64_t now = current_time_ms();
    int64_t delta = timer_heap[0]->expiration_ms - now;
    return delta > 0 ? delta : 0;
}

Hint 3: Integrating Signals with signalfd()

sigset_t mask;
sigemptyset(&mask);
sigaddset(&mask, SIGINT);
sigaddset(&mask, SIGTERM);

// Block these signals from being delivered normally
sigprocmask(SIG_BLOCK, &mask, NULL);

// Create a file descriptor that receives them
int sigfd = signalfd(-1, &mask, SFD_NONBLOCK);

// Add to epoll like any other fd
struct epoll_event ev = {.events = EPOLLIN, .data.fd = sigfd};
epoll_ctl(epfd, EPOLL_CTL_ADD, sigfd, &ev);

// Later, when signalfd is readable:
struct signalfd_siginfo info;
read(sigfd, &info, sizeof(info));
// info.ssi_signo tells you which signal

Hint 4: Callback Registration

typedef struct {
    int fd;
    uint32_t events;
    void (*read_cb)(int fd, void *arg);
    void (*write_cb)(int fd, void *arg);
    void *arg;
} FdHandler;

FdHandler handlers[MAX_FDS];

void on_event(int fd, uint32_t events) {
    FdHandler *h = &handlers[fd];
    if ((events & EPOLLIN) && h->read_cb) {
        h->read_cb(fd, h->arg);
    }
    if ((events & EPOLLOUT) && h->write_cb) {
        h->write_cb(fd, h->arg);
    }
}

Hint 5: The Main Event Loop

void eventloop_run(EventLoop *loop) {
    while (loop->running) {
        int timeout = next_timer_timeout_ms();
        int n = epoll_wait(loop->epfd, loop->events, MAX_EVENTS, timeout);

        // Handle expired timers
        fire_expired_timers(loop);

        // Handle I/O events
        for (int i = 0; i < n; i++) {
            int fd = loop->events[i].data.fd;
            uint32_t events = loop->events[i].events;
            on_event(fd, events);
        }
    }
}

Books That Will Help

Topic	Book	Chapter
I/O multiplexing overview	“The Linux Programming Interface”	Ch. 63: Alternative I/O Models
epoll in depth	“The Linux Programming Interface”	Ch. 63.4: epoll
Non-blocking I/O	“Advanced Programming in the UNIX Environment”	Ch. 14: Advanced I/O
Signal handling in event loops	“The Linux Programming Interface”	Ch. 22: Signals: Advanced Features
libevent/libev concepts	“High Performance Browser Networking”	Event-driven architecture concepts

Project 6: Terminal UI Library (Mini-ncurses)

File: DEEP_UNDERSTANDING_TMUX_PROJECTS.md
Main Programming Language: C
Alternative Programming Languages: Rust, Go
Coolness Level: Level 3: Genuinely Clever
Business Potential: 4. The “Open Core” Infrastructure
Difficulty: Level 3: Advanced
Knowledge Area: Terminal UI / Graphics
Software or Tool: ncurses / TUI
Main Book: “The Linux Programming Interface” by Michael Kerrisk

What you’ll build: A small terminal UI library that handles raw mode, cursor positioning, colors, window/box drawing, and efficient screen updates (only redraw what changed).

Why it teaches tmux fundamentals: tmux draws its status bar, pane borders, and handles copy mode using similar techniques. Understanding how to efficiently update a terminal screen is crucial for a responsive multiplexer.

Core challenges you’ll face:

Terminal capability detection (terminfo/termcap or hardcoded ANSI) → maps to tmux terminal compatibility
Efficient screen updates (diff-based rendering) → maps to tmux performance
Drawing primitives (boxes, lines, text with attributes) → maps to tmux pane borders and status
Input handling (function keys, mouse, UTF-8) → maps to tmux key bindings
Alternate screen buffer → maps to why tmux doesn’t mess up your shell history

Key Concepts:

ncurses Overview: NCURSES Programming HOWTO - TLDP
Terminal Capabilities: “Advanced Programming in the UNIX Environment” Chapter 18 - W. Richard Stevens
Escape Sequences: ANSI Escape Sequences Gist - Christian Petersen
ncurses Examples: ncurses examples - Paul Griffiths

Difficulty: Advanced Time estimate: 1-2 weeks Prerequisites: ANSI escape sequences (Project 2), raw mode terminal I/O

Real world outcome:

$ ./tui_demo
┌─────────────────────────────────────┐
│  Welcome to Mini-TUI                │
│                                     │
│  [Button 1]  [Button 2]  [Button 3] │
│                                     │
│  Status: Ready                      │
└─────────────────────────────────────┘

# Arrow keys navigate, Enter selects
# Resizing the terminal redraws correctly
# Exiting restores the terminal perfectly

Implementation Hints: The key to efficient updates is double-buffering: maintain two screen buffers (current and next). When rendering, compare them cell by cell and only emit escape sequences for cells that changed. This minimizes output and makes updates fast.

Enter the alternate screen buffer with \033[?1049h and exit with \033[?1049l. This is why vim and tmux don’t leave garbage when they exit.

Learning milestones:

Can draw boxes and text at positions → You understand cursor control
Colors work correctly → You understand SGR sequences
Resize is handled → You understand SIGWINCH integration
Updates are efficient (no flicker) → You understand diff-based rendering

The Core Question You’re Answering

“How does tmux draw its status bar, pane borders, and copy mode interface? How does it update the screen without flickering?”

tmux doesn’t use ncurses—it has its own terminal rendering code. Understanding how to efficiently update a terminal screen, draw boxes, and handle attributes is essential for any TUI application and helps you understand tmux’s internals.

Concepts You Must Understand First

Stop and research these before coding:

Terminal Capabilities
- What is terminfo/termcap?
- How do you discover what a terminal supports?
- Why do programs check $TERM?
- Book Reference: “Advanced Programming in the UNIX Environment” Ch. 18 - W. Richard Stevens
Cursor Control
- How do you position the cursor at an arbitrary (row, col)?
- What’s the difference between absolute and relative positioning?
- How do you save and restore cursor position?
- Reference: VT100 User Guide, ANSI escape sequence references
Screen Regions and Alternate Buffer
- What is the alternate screen buffer?
- Why do programs like vim and less use it?
- How do you enter/exit the alternate buffer?
Efficient Updates (Double Buffering)
- What is double buffering?
- How do you minimize the number of escape sequences emitted?
- What is the cost of emitting vs. the cost of comparing?
Drawing Characters
- What are box-drawing characters and where do they come from?
- How do you handle Unicode vs. ASCII box-drawing?
- What is wide character support and why does it complicate things?

Questions to Guide Your Design

Before implementing, think through these:

Buffer Architecture
- How many buffers do you need (front buffer, back buffer)?
- What does each cell in your buffer contain?
- How do you know when a cell has “changed”?
Drawing API
- What primitives do users need? (draw_char, draw_string, draw_box, fill_rect?)
- How do you handle attributes (color, bold) in your API?
- Should drawing be immediate or deferred until flush?
Refresh Strategy
- When do you emit escape sequences to the terminal?
- How do you minimize cursor movement?
- What if the user resizes the terminal mid-draw?
Input Handling
- How do you detect function keys, arrow keys, mouse events?
- How do you handle Ctrl-key combinations?
- What is escape sequence ambiguity and how do you resolve it?
Cleanup
- How do you restore the terminal on exit?
- What if your program crashes without cleanup?
- How do you handle SIGINT, SIGTERM gracefully?

Thinking Exercise

Design the update algorithm:

Previous frame:           Current frame:
┌─────────────┐           ┌─────────────┐
│ Hello World │           │ Hello Earth │
│             │           │             │
│ Status: OK  │           │ Status: ERR │
└─────────────┘           └─────────────┘

Which cells changed?

Row 0: “World” → “Earth” (cols 6-10 differ, but we only need to redraw “Earth”)
Row 2: “OK “ → “ERR” (cols 8-10)
Everything else is identical

The optimal update sequence:

\033[1;7H     # Move cursor to row 1, col 7
Earth         # Write "Earth"
\033[3;9H     # Move cursor to row 3, col 9
\033[31mERR   # Write "ERR" in red (assume status changed color too)
\033[0m       # Reset color

Far more efficient than redrawing the entire screen!

The Interview Questions They’ll Ask

Prepare to answer these:

“What is the alternate screen buffer and why do TUI apps use it?”
“How do you implement efficient screen updates?”
“What are box-drawing characters and how do you use them?”
“How do you handle terminal resize in a TUI application?”
“What is terminfo and how is it used?”
“How would you implement a scrolling text area?”
“What happens if your program exits without restoring the terminal?”
“How do you handle wide characters (like emoji) in a TUI?”
“What is the difference between raw mode and cbreak mode?”
“How would you implement mouse support in a terminal application?”

Hints in Layers

Only read these if you’re stuck. Try each step yourself first.

Hint 1: Cell Structure

typedef struct {
    uint32_t ch;       // Character (UTF-32)
    uint8_t fg;        // Foreground color (0-255 or special)
    uint8_t bg;        // Background color
    uint8_t attrs;     // Bit flags: BOLD, UNDERLINE, etc.
} Cell;

typedef struct {
    Cell *cells;
    int rows, cols;
} Buffer;

Cell* cell_at(Buffer *buf, int row, int col) {
    return &buf->cells[row * buf->cols + col];
}

Hint 2: Double Buffer and Diff

Buffer front;  // What's currently on screen
Buffer back;   // What we want to display

void swap_buffers() {
    // After rendering, swap
    Buffer tmp = front;
    front = back;
    back = tmp;
}

void refresh() {
    for (int row = 0; row < rows; row++) {
        for (int col = 0; col < cols; col++) {
            Cell *f = cell_at(&front, row, col);
            Cell *b = cell_at(&back, row, col);
            if (memcmp(f, b, sizeof(Cell)) != 0) {
                move_cursor(row, col);
                set_attrs(b->fg, b->bg, b->attrs);
                output_char(b->ch);
            }
        }
    }
    flush_output();
}

Hint 3: Entering and Exiting Alternate Screen

void enter_alternate_screen() {
    printf("\033[?1049h");  // smcup - enter alternate screen
    printf("\033[2J");      // Clear screen
    printf("\033[H");       // Home cursor
    fflush(stdout);
}

void exit_alternate_screen() {
    printf("\033[?1049l");  // rmcup - exit alternate screen
    fflush(stdout);
}

// Register cleanup on exit
void cleanup(void) {
    exit_alternate_screen();
    tcsetattr(STDIN_FILENO, TCSANOW, &orig_termios);
}
atexit(cleanup);

Hint 4: Box Drawing

// Unicode box-drawing characters
#define BOX_UL  0x250C  // ┌
#define BOX_UR  0x2510  // ┐
#define BOX_LL  0x2514  // └
#define BOX_LR  0x2518  // ┘
#define BOX_H   0x2500  // ─
#define BOX_V   0x2502  // │

void draw_box(Buffer *buf, int r1, int c1, int r2, int c2) {
    cell_at(buf, r1, c1)->ch = BOX_UL;
    cell_at(buf, r1, c2)->ch = BOX_UR;
    cell_at(buf, r2, c1)->ch = BOX_LL;
    cell_at(buf, r2, c2)->ch = BOX_LR;

    for (int c = c1 + 1; c < c2; c++) {
        cell_at(buf, r1, c)->ch = BOX_H;
        cell_at(buf, r2, c)->ch = BOX_H;
    }
    for (int r = r1 + 1; r < r2; r++) {
        cell_at(buf, r, c1)->ch = BOX_V;
        cell_at(buf, r, c2)->ch = BOX_V;
    }
}

Hint 5: Handling Resize (SIGWINCH)

volatile sig_atomic_t resize_pending = 0;

void sigwinch_handler(int sig) {
    resize_pending = 1;
}

void check_resize() {
    if (resize_pending) {
        resize_pending = 0;
        struct winsize ws;
        ioctl(STDIN_FILENO, TIOCGWINSZ, &ws);
        resize_buffers(ws.ws_row, ws.ws_col);
        // Mark everything dirty so it redraws
        memset(front.cells, 0, sizeof(Cell) * rows * cols);
    }
}

// Call check_resize() at the start of each main loop iteration

Books That Will Help

Topic	Book	Chapter
Terminal I/O and modes	“Advanced Programming in the UNIX Environment”	Ch. 18: Terminal I/O
ncurses fundamentals	“NCURSES Programming HOWTO”	All chapters (for comparison)
terminfo/termcap	“The Linux Programming Interface”	Ch. 62: Terminals
Unicode handling	“UTF-8 and Unicode FAQ”	Online resource
Escape sequences reference	“XTerm Control Sequences”	Thomas Dickey (online)

Project 7: Mini-Screen (Single-Window Multiplexer)

File: DEEP_UNDERSTANDING_TMUX_PROJECTS.md
Main Programming Language: C
Alternative Programming Languages: Rust
Coolness Level: Level 4: Hardcore Tech Flex
Business Potential: 1. The “Resume Gold” (Educational/Personal Brand)
Difficulty: Level 4: Expert
Knowledge Area: Systems Programming / Terminal Multiplexing
Software or Tool: GNU Screen / tmux
Main Book: “Advanced Programming in the UNIX Environment” by W. Richard Stevens

What you’ll build: A simplified terminal multiplexer with multiple “windows” (not panes—full-screen tabs) that you can switch between with keyboard shortcuts. Like GNU Screen without splits.

Why it teaches tmux fundamentals: This combines PTYs, escape sequence rendering, event loops, and signal handling into one coherent system. It’s tmux without the hard part (pane splitting).

Core challenges you’ll face:

Managing multiple PTYs (one per window) → maps to tmux window management
Switching “active” window (stop rendering one, start rendering another) → maps to tmux window switching
Key prefix handling (Ctrl-A or Ctrl-B to access commands) → maps to tmux prefix key
Window list display → maps to tmux’s Ctrl-B w window list
Proper cleanup on exit → maps to tmux graceful shutdown

Key Concepts:

PTY Management: “The Linux Programming Interface” Chapter 64 - Michael Kerrisk
Event-Driven Architecture: libevent documentation - libevent
tmux Architecture: tmux Wiki - Getting Started - tmux project
Reference Implementation: mtm - Micro Terminal Multiplexer - deadpixi

Difficulty: Expert Time estimate: 2-3 weeks Prerequisites: All previous projects (1-6)

Real world outcome:

$ ./miniscreen
# Starts with one window running your shell

# Ctrl-A c - create new window
# Window 1 running shell

# Ctrl-A c - create another
# Window 2 running shell

# Ctrl-A n - next window
# Ctrl-A p - previous window
# Ctrl-A 0-9 - go to window N

# Ctrl-A w - show window list:
  0: bash*
  1: bash
  2: vim

# Ctrl-A d - detach... wait, that needs a server!

Implementation Hints: Start simple: one PTY, proxy I/O like in Project 1. Then add the ability to create a second PTY (Ctrl-A c), and switch which one you’re proxying (Ctrl-A n/p). The inactive PTY still runs—its output just goes into a buffer until you switch to it.

You’ll need a “current window” pointer and a way to pause/resume rendering for each window.

Learning milestones:

Single window works like Project 1 → Foundation is solid
Can create multiple windows → You understand multi-PTY management
Switching is instant and correct → You understand buffer management
Window list shows all windows → You have internal state tracking
Programs keep running in background windows → You understand true multiplexing

The Core Question You’re Answering

“How does tmux manage multiple windows and switch between them instantly while keeping programs running in the background?”

This is the essence of terminal multiplexing: managing multiple PTYs simultaneously, switching which one gets rendered to your screen, while ensuring that background processes continue executing. Understanding this teaches you the fundamental architecture of GNU Screen and tmux before adding the complexity of pane splitting.

Concepts You Must Understand First

Stop and research these before coding:

Multiple PTY Management
- How do you create and manage multiple PTYs in one process?
- What data structures track which PTY is “active”?
- How do you ensure inactive PTYs still receive data and process it?
- Book Reference: “The Linux Programming Interface” Ch. 64: Pseudoterminals - Michael Kerrisk
Window State Machine
- What constitutes a “window” in your program?
- What state does each window maintain (PTY fd, buffer, process ID, name)?
- How do you switch from one window to another atomically?
- Book Reference: “Advanced Programming in the UNIX Environment” Ch. 10: Signals - W. Richard Stevens
Buffering Background Output
- What happens to PTY output when a window is not visible?
- Do you buffer it? How much? What if the buffer fills?
- How do you “catch up” when switching to a background window?
- Reference: tmux source code - window.c and screen.c
Prefix Key State Machine
- How do you intercept a prefix key (Ctrl-A or Ctrl-B)?
- What happens to input after the prefix is pressed?
- How do you distinguish between user input and commands?
- Book Reference: “Advanced Programming in the UNIX Environment” Ch. 18: Terminal I/O - W. Richard Stevens
Event Loop with Multiple FDs
- How do you use select/poll/epoll with multiple PTY master FDs?
- How do you prioritize between stdin and multiple PTYs?
- What happens when multiple FDs have data ready simultaneously?
- Book Reference: “The Linux Programming Interface” Ch. 63: Alternative I/O Models - Michael Kerrisk

Questions to Guide Your Design

Before implementing, think through these:

Window Data Structure
- What information does each window store?
- Should windows be in an array, linked list, or hash map?
- How do you identify windows (index, ID, name)?
Switching Mechanism
- When you switch from window 0 to window 1, what exactly changes?
- Do you stop reading from window 0’s PTY?
- How do you handle pending output from window 0?
Buffer Strategy
- Do inactive windows buffer their output infinitely?
- What if a background process produces gigabytes of output?
- Do you implement a circular buffer with size limits?
Command Mode
- After pressing Ctrl-A, how long do you wait for the next key?
- What if the user presses Ctrl-A then nothing (timeout)?
- How do you handle Ctrl-A followed by an invalid key?
Process Lifecycle
- When you close a window, how do you clean up its PTY?
- What if the process in the PTY has already exited?
- How do you detect dead windows and remove them?

Thinking Exercise

Trace the state changes on paper:

You have 3 windows:

Window 0: running bash (active, visible)
Window 1: running vim (inactive, buffering)
Window 2: running top (inactive, buffering)

Scenario: User presses Ctrl-A 1

Walk through what happens:

Input Processing:
- Your program reads Ctrl-A from stdin
- State changes from NORMAL → PREFIX_MODE
- Next byte read is ‘1’ (the window number)
- Parse ‘1’ → window index 1
Window Deactivation:
- Current window (0) is marked as inactive
- Window 0’s PTY fd: still in select/poll readset? Yes or no?
- Window 0’s buffering: starts buffering or continues?
Window Activation:
- Window 1 becomes active
- Window 1’s PTY output: flush buffered data to screen?
- Window 1’s screen state: restore from where?
Screen Rendering:
- Do you clear the screen first?
- Do you dump the entire buffer of window 1?
- How do you handle if vim resized while in background?

Sketch the data flow and state transitions before coding.

The Interview Questions They’ll Ask

Prepare to answer these:

“How does GNU Screen keep programs running when you switch windows?”
“What happens to output from a background window in a terminal multiplexer?”
“How do you implement a command prefix key like Ctrl-A in tmux?”
“What data structure would you use to manage multiple windows?”
“How do you prevent a background process from filling up all your memory?”
“What’s the difference between a window and a pane in tmux?”
“How would you implement window renaming?”
“What happens if you switch to a window whose process has died?”
“How do you handle terminal resize across multiple windows?”
“Why does tmux need an event loop?”

Hints in Layers

Only read these if you’re stuck. Try each step yourself first.

Hint 1: Window Structure

typedef struct {
    int pty_master;        // File descriptor for PTY master
    pid_t child_pid;       // PID of child process
    char *name;            // Window name (e.g., "bash", "vim")

    // Screen buffer for this window
    char *screen_buffer;   // Buffered output when inactive
    size_t buffer_len;
    size_t buffer_capacity;

    bool is_alive;         // Is the child process still running?
} Window;

Window windows[MAX_WINDOWS];
int current_window = 0;
int num_windows = 0;

Hint 2: Event Loop with Multiple PTYs

void main_loop() {
    fd_set readfds;

    while (1) {
        FD_ZERO(&readfds);
        FD_SET(STDIN_FILENO, &readfds);

        int maxfd = STDIN_FILENO;

        // Add all PTY master FDs
        for (int i = 0; i < num_windows; i++) {
            if (windows[i].is_alive) {
                FD_SET(windows[i].pty_master, &readfds);
                if (windows[i].pty_master > maxfd)
                    maxfd = windows[i].pty_master;
            }
        }

        select(maxfd + 1, &readfds, NULL, NULL, NULL);

        // Check stdin (user input)
        if (FD_ISSET(STDIN_FILENO, &readfds)) {
            handle_user_input();
        }

        // Check each PTY
        for (int i = 0; i < num_windows; i++) {
            if (windows[i].is_alive &&
                FD_ISSET(windows[i].pty_master, &readfds)) {
                handle_pty_output(i);
            }
        }
    }
}

Hint 3: Window Switching Logic

void switch_to_window(int new_window) {
    if (new_window < 0 || new_window >= num_windows)
        return;

    if (new_window == current_window)
        return;  // Already there

    // Optional: save current screen state
    // (not shown - you might snapshot the terminal state)

    // Switch
    current_window = new_window;

    // Clear screen and redraw from buffer
    printf("\033[2J\033[H");  // Clear screen, home cursor

    // Flush the buffered output for this window
    Window *w = &windows[current_window];
    if (w->buffer_len > 0) {
        write(STDOUT_FILENO, w->screen_buffer, w->buffer_len);
        // Optionally clear buffer after flushing
    }

    fflush(stdout);
}

Hint 4: Prefix Key State Machine

enum InputState {
    STATE_NORMAL,     // Regular input goes to active PTY
    STATE_PREFIX,     // Just pressed Ctrl-A, waiting for command
};

enum InputState input_state = STATE_NORMAL;

void handle_user_input() {
    char buf[256];
    ssize_t n = read(STDIN_FILENO, buf, sizeof(buf));

    for (ssize_t i = 0; i < n; i++) {
        if (input_state == STATE_NORMAL) {
            if (buf[i] == 0x01) {  // Ctrl-A
                input_state = STATE_PREFIX;
            } else {
                // Normal input: forward to active window's PTY
                write(windows[current_window].pty_master, &buf[i], 1);
            }
        } else if (input_state == STATE_PREFIX) {
            // Command mode
            handle_command(buf[i]);
            input_state = STATE_NORMAL;
        }
    }
}

void handle_command(char cmd) {
    switch (cmd) {
        case 'c':  // Create new window
            create_window();
            break;
        case 'n':  // Next window
            switch_to_window((current_window + 1) % num_windows);
            break;
        case 'p':  // Previous window
            switch_to_window((current_window - 1 + num_windows) % num_windows);
            break;
        case '0' ... '9':  // Go to window N
            switch_to_window(cmd - '0');
            break;
        case 'w':  // Window list
            show_window_list();
            break;
    }
}

Hint 5: Buffering Background Output

void handle_pty_output(int window_idx) {
    Window *w = &windows[window_idx];
    char buf[4096];
    ssize_t n = read(w->pty_master, buf, sizeof(buf));

    if (n <= 0) {
        // PTY closed or error
        w->is_alive = false;
        return;
    }

    if (window_idx == current_window) {
        // Active window: write directly to stdout
        write(STDOUT_FILENO, buf, n);
    } else {
        // Background window: buffer the output
        // Ensure we have space
        size_t needed = w->buffer_len + n;
        if (needed > w->buffer_capacity) {
            // Grow buffer or implement circular buffer
            // For simplicity, limit buffer size
            if (w->buffer_capacity >= MAX_BUFFER_SIZE) {
                // Discard oldest data (circular buffer logic)
                // Or just discard new data
                return;
            }
            w->buffer_capacity = needed * 2;
            w->screen_buffer = realloc(w->screen_buffer,
                                       w->buffer_capacity);
        }

        memcpy(w->screen_buffer + w->buffer_len, buf, n);
        w->buffer_len += n;
    }
}

Books That Will Help

Topic	Book	Chapter
Pseudoterminals (PTY)	“The Linux Programming Interface”	Ch. 64: Pseudoterminals
Multiple PTY management	“Advanced Programming in the UNIX Environment”	Ch. 19: Pseudo Terminals
Event-driven I/O (select/poll)	“The Linux Programming Interface”	Ch. 63: Alternative I/O Models
Terminal modes and control	“Advanced Programming in the UNIX Environment”	Ch. 18: Terminal I/O
Process management	“The Linux Programming Interface”	Ch. 26: Monitoring Child Processes
tmux internals	“The Tao of tmux”	Technical Stuff section (online)
GNU Screen architecture	GNU Screen source code	`window.c` and `screen.c`

Project 8: Detach/Attach Server Architecture

File: DEEP_UNDERSTANDING_TMUX_PROJECTS.md
Main Programming Language: C
Alternative Programming Languages: Rust
Coolness Level: Level 4: Hardcore Tech Flex
Business Potential: 1. The “Resume Gold” (Educational/Personal Brand)
Difficulty: Level 4: Expert
Knowledge Area: Distributed Systems / IPC
Software or Tool: tmux / GNU Screen
Main Book: “Advanced Programming in the UNIX Environment” by W. Richard Stevens

What you’ll build: Split Project 7 into a server (which manages windows and PTYs) and a client (which renders and handles input). The server persists; clients can attach and detach.

Why it teaches tmux fundamentals: This is the core feature that makes tmux useful. Understanding how the server maintains state while clients come and go is essential.

Core challenges you’ll face:

Daemonizing the server (double-fork pattern or modern systemd-style) → maps to tmux server lifecycle
Client-server protocol (what messages are exchanged?) → maps to tmux internal protocol
Screen state synchronization (client connects, needs current screen state) → maps to tmux attach
Multiple simultaneous clients (same session, different terminals) → maps to tmux pair programming
Handling client terminal size differences → maps to tmux aggressive-resize

Key Concepts:

Daemon Creation: “Advanced Programming in the UNIX Environment” Chapter 13 - W. Richard Stevens
Unix Domain Sockets: “The Linux Programming Interface” Chapter 57 - Michael Kerrisk
tmux Client-Server: The Tao of tmux - Technical Stuff - Tony Narlock
Reference Implementation: Example Forking Daemon - guns

Difficulty: Expert Time estimate: 2-3 weeks Prerequisites: Project 7 completed, Unix domain sockets (Project 3)

Real world outcome:

# Terminal 1
$ ./mux new-session
[server starting...]
# You're now in a session

$ Ctrl-B d  # detach
[detached from session 0]

$ ./mux list-sessions
0: 1 windows (created today)

# Terminal 2 (or after SSH disconnect!)
$ ./mux attach -t 0
# You're back! Everything is exactly as you left it.

# Both terminals attached:
$ ./mux attach -t 0  # from another terminal
# Both terminals show the same thing
# Typing in either affects the session

Implementation Hints: The protocol can be simple: client sends “key pressed: X” or “resize: 80x24”, server sends “screen update: [data]” or “cursor position: row,col”. Use a simple length-prefixed binary format or line-based text protocol.

When a client attaches, the server must send the entire current screen state. After that, it only sends deltas.

Learning milestones:

Server daemonizes, client can connect → You understand the split architecture
Typing in client affects server-side shell → Protocol works for input
Screen updates appear in client → Protocol works for output
Detach and reattach preserves state → You’ve achieved tmux’s core value
Multiple clients work simultaneously → You understand multi-client synchronization

The Core Question You’re Answering

“How does tmux keep my session running when I disconnect? How can I attach from a completely different terminal and see everything exactly as I left it?”

This is the fundamental innovation that makes tmux (and screen before it) invaluable. The separation of the terminal multiplexing logic (server) from the terminal display (client) allows sessions to persist independently of any particular terminal. Understanding this architecture is understanding why tmux exists.

Concepts You Must Understand First

Stop and research these before coding:

What Is a Daemon Process?
- What makes a process a “daemon” versus a normal process?
- Why must a daemon detach from its controlling terminal?
- What is the double-fork pattern and why is it needed?
- What happens to daemon processes when you log out?
- Book Reference: “Advanced Programming in the UNIX Environment” Ch. 13 - W. Richard Stevens
Process Sessions and Process Groups
- What is a session leader and how do you become one with setsid()?
- Why does daemonizing require creating a new session?
- What’s the difference between a session, process group, and controlling terminal?
- How do signals (SIGHUP) relate to sessions?
- Book Reference: “The Linux Programming Interface” Ch. 34 - Michael Kerrisk
Unix Domain Sockets for IPC
- Why use Unix sockets instead of TCP for local communication?
- What’s the difference between SOCK_STREAM and SOCK_DGRAM?
- Where should the socket file live (/tmp/tmux-$UID/default)?
- How do you handle cleanup when the server exits?
- Book Reference: “The Linux Programming Interface” Ch. 57 - Michael Kerrisk
Client-Server Protocol Design
- What messages must the protocol support (attach, detach, key input, resize)?
- How do you serialize screen state for transmission?
- Should you send the entire screen or just deltas?
- How do you handle protocol versioning?
- Reference: Study tmux source code - client.c, server.c
State Synchronization on Attach
- What state must be sent when a client attaches?
- How do you handle multiple clients with different terminal sizes?
- What happens when a second client attaches to the same session?
- How do you notify all attached clients of screen updates?
- Concept: This is similar to distributed systems state transfer

Questions to Guide Your Design

Before implementing, think through these:

Server Lifecycle
- How does the server know when to start? (First client creates it)
- How does the server know when to exit? (No sessions left, or explicit kill)
- How do you prevent multiple servers from running?
- Should you use the double-fork pattern or a simpler modern approach?
Socket Communication
- What’s the format of messages between client and server?
- How do you handle partial reads/writes on sockets?
- How do you multiplex between multiple client connections and multiple PTYs?
- What happens if a client disconnects mid-transmission?
Screen State Management
- Where does the authoritative screen state live? (Server)
- When a client attaches, do you send raw PTY data or processed screen buffer?
- How do you handle the case where clients have different terminal sizes?
- What’s the strategy for aggressive-resize option?
Multi-Client Support
- How do you track which clients are attached to which session?
- If one client types, how does the input reach the PTY?
- If the PTY outputs, how do all attached clients get the update?
- What happens if clients attach/detach while data is flowing?
Protocol Messages
- What does an “attach” message need to include? (Session ID, terminal size)
- What does a “detach” message need? (Just client ID?)
- How do you represent key input? (Raw bytes or interpreted?)
- How do you represent screen updates? (Full refresh or deltas?)

Thinking Exercise

Design the protocol messages on paper:

Client wants to attach to session 0:

Client → Server: [MSG_ATTACH] session_id=0, term_size=80x24

Server → Client: [MSG_SESSION_STATE]
                 - Current screen buffer (80x24 cells)
                 - Cursor position
                 - Current attributes
                 - Window title

Client types 'l', 's', Enter:

Client → Server: [MSG_INPUT] data="ls\n"

Server writes to PTY master → Shell executes ls → Output appears

Server → Client: [MSG_SCREEN_UPDATE]
                 - Changed cells (delta encoding)
                 - New cursor position

Client resizes terminal to 100x30:

Client → Server: [MSG_RESIZE] new_size=100x30

Server calls ioctl(TIOCSWINSZ) on PTY → SIGWINCH to shell

Server → Client: [MSG_SCREEN_UPDATE]
                 - Full screen refresh at new size

Now trace what happens when:

Client detaches (Ctrl-B d)
Server keeps running - where is the state?
New client attaches - how does it get current state?
Both clients are attached - who “owns” the session?

The Interview Questions They’ll Ask

Prepare to answer these:

“How does tmux persist sessions after you close the terminal?”
“What is the double-fork pattern and why is it used for daemons?”
“What’s the difference between a daemon and a background process?”
“How would you design a protocol for client-server communication over Unix sockets?”
“What happens when two clients with different terminal sizes attach to the same session?”
“How does tmux handle network latency or slow clients?” (Hint: it’s local, but design matters)
“What’s the advantage of Unix domain sockets over TCP for local IPC?”
“How would you handle the case where a client disconnects unexpectedly?”
“What is session state and what must be preserved across detach/attach?”
“How would you implement the ‘aggressive-resize’ option in tmux?”

Hints in Layers

Only read these if you’re stuck. Try each step yourself first.

Hint 1: Basic Daemonization Pattern

pid_t pid = fork();
if (pid > 0) exit(0);  // Parent exits, child continues

// Child process
setsid();  // Become session leader, lose controlling terminal

pid = fork();  // Fork again
if (pid > 0) exit(0);  // First child exits

// Second child (grandchild of original) is the daemon
// It's not a session leader, so can't reacquire a controlling terminal

chdir("/");  // Change working directory to root
umask(0);    // Clear file mode creation mask

// Close all open file descriptors
for (int fd = 0; fd < getdtablesize(); fd++) {
    close(fd);
}

// Reopen stdin, stdout, stderr to /dev/null
int fd = open("/dev/null", O_RDWR);
dup2(fd, 0);
dup2(fd, 1);
dup2(fd, 2);

Hint 2: Unix Socket Server Setup

int server_fd = socket(AF_UNIX, SOCK_STREAM, 0);
struct sockaddr_un addr = {0};
addr.sun_family = AF_UNIX;
snprintf(addr.sun_path, sizeof(addr.sun_path),
         "/tmp/tmux-%d/default", getuid());

// Create directory if needed
char dir[256];
snprintf(dir, sizeof(dir), "/tmp/tmux-%d", getuid());
mkdir(dir, 0700);

unlink(addr.sun_path);  // Remove old socket file
bind(server_fd, (struct sockaddr*)&addr, sizeof(addr));
listen(server_fd, 5);

// Main server loop
while (1) {
    int client_fd = accept(server_fd, NULL, NULL);
    // Handle client (add to set of active connections)
}

Hint 3: Simple Protocol - Length-Prefixed Messages

typedef enum {
    MSG_ATTACH,
    MSG_DETACH,
    MSG_INPUT,
    MSG_SCREEN_UPDATE,
    MSG_RESIZE,
} MessageType;

typedef struct {
    MessageType type;
    uint32_t length;  // Length of data that follows
    // Data follows...
} MessageHeader;

// Sending
void send_message(int fd, MessageType type, void *data, size_t len) {
    MessageHeader hdr = { .type = type, .length = len };
    write(fd, &hdr, sizeof(hdr));
    write(fd, data, len);
}

// Receiving
MessageHeader hdr;
read(fd, &hdr, sizeof(hdr));
char *data = malloc(hdr.length);
read(fd, data, hdr.length);

Hint 4: Multiplexing with select() - Server Main Loop

fd_set read_fds;
int max_fd = server_socket_fd;

while (1) {
    FD_ZERO(&read_fds);
    FD_SET(server_socket_fd, &read_fds);  // New connections

    // Add all client connections
    for (each client in clients) {
        FD_SET(client->socket_fd, &read_fds);
        max_fd = max(max_fd, client->socket_fd);
    }

    // Add all PTY masters (one per session)
    for (each session in sessions) {
        FD_SET(session->pty_master, &read_fds);
        max_fd = max(max_fd, session->pty_master);
    }

    select(max_fd + 1, &read_fds, NULL, NULL, NULL);

    if (FD_ISSET(server_socket_fd, &read_fds)) {
        // New client connecting
        int client_fd = accept(server_socket_fd, NULL, NULL);
        // Create client structure, add to clients list
    }

    for (each client in clients) {
        if (FD_ISSET(client->socket_fd, &read_fds)) {
            // Client sent a message
            handle_client_message(client);
        }
    }

    for (each session in sessions) {
        if (FD_ISSET(session->pty_master, &read_fds)) {
            // PTY has output - read it, update screen buffer
            // Send screen updates to all attached clients
            handle_pty_output(session);
        }
    }
}

Hint 5: Sending Full Screen State on Attach

typedef struct {
    int rows;
    int cols;
    int cursor_row;
    int cursor_col;
    // Followed by rows*cols cells
} ScreenState;

void send_screen_state(int client_fd, Session *session) {
    ScreenState state = {
        .rows = session->screen.rows,
        .cols = session->screen.cols,
        .cursor_row = session->screen.cursor_row,
        .cursor_col = session->screen.cursor_col,
    };

    send_message(client_fd, MSG_SCREEN_UPDATE, &state, sizeof(state));

    // Send all cells
    size_t cells_size = state.rows * state.cols * sizeof(Cell);
    send_message(client_fd, MSG_SCREEN_DATA,
                 session->screen.cells, cells_size);
}

Books That Will Help

Topic	Book	Chapter
Daemon processes	“Advanced Programming in the UNIX Environment”	Ch. 13: Daemon Processes
Process sessions	“The Linux Programming Interface”	Ch. 34: Process Groups, Sessions, and Job Control
Unix domain sockets	“The Linux Programming Interface”	Ch. 57: Sockets: Unix Domain
Socket programming	“The Linux Programming Interface”	Ch. 56-61: Sockets (entire section)
I/O multiplexing	“The Linux Programming Interface”	Ch. 63: Alternative I/O Models
File descriptor management	“Advanced Programming in the UNIX Environment”	Ch. 3: File I/O
Signal handling in servers	“The Linux Programming Interface”	Ch. 20-22: Signals
Client-server architecture	“Unix Network Programming Vol 1”	Ch. 1-6: Introduction and Elementary Sockets

Project 9: Pane Splitting and Layouts

File: DEEP_UNDERSTANDING_TMUX_PROJECTS.md
Main Programming Language: C
Alternative Programming Languages: Rust
Coolness Level: Level 5: Pure Magic (Super Cool)
Business Potential: 1. The “Resume Gold” (Educational/Personal Brand)
Difficulty: Level 4: Expert
Knowledge Area: UI Layout / Terminal Multiplexing
Software or Tool: tmux
Main Book: “Advanced Programming in the UNIX Environment” by W. Richard Stevens

What you’ll build: Extend Project 8 with pane splitting—dividing a window into multiple regions, each with its own PTY.

Why it teaches tmux fundamentals: This is where tmux gets complex. You must render multiple virtual screens into sub-regions of the physical terminal, handle focus, and deal with layout algorithms.

Core challenges you’ll face:

Layout calculation (how to divide space among panes?) → maps to tmux layout algorithms
Sub-screen rendering (each pane renders into a region) → maps to tmux pane rendering
Focus management (which pane receives input?) → maps to tmux select-pane
Border drawing (visual separation between panes) → maps to tmux pane-border-style
Resize propagation (terminal resize → recalculate layouts → resize PTYs → SIGWINCH to programs) → maps to tmux resize handling

Key Concepts:

Layout Algorithms: Understanding tiled window managers (i3wm concepts apply)
Screen Regions: “NCURSES Programming HOWTO” Panel Library - TLDP
tmux Source Reference: tmux source code - layout.c, screen.c

Difficulty: Expert Time estimate: 3-4 weeks Prerequisites: Project 8 completed, TUI library (Project 6)

Real world outcome:

$ ./mux new-session
# Full-screen shell

$ Ctrl-B %  # vertical split
# Now two panes side-by-side, each with a shell

$ Ctrl-B "  # horizontal split
# Now three panes

$ Ctrl-B o  # cycle focus
$ Ctrl-B arrow  # directional focus change

# Each pane runs independently
# Resizing works correctly
# Borders update on focus change

Implementation Hints: Think of panes as a tree structure: each node is either a “container” (with children split horizontally or vertically) or a “leaf” (containing a PTY). To render, recursively calculate each pane’s rectangle, then render each leaf pane’s screen buffer into its region.

Start with a simple 50/50 split. Later add resizing (Ctrl-B arrow with Ctrl held) and preset layouts.

Learning milestones:

Can split once (two panes) → Basic layout works
Can split recursively (arbitrary layouts) → Tree structure works
Focus and input routing work → UI navigation works
Resize propagates correctly → The hard part works
Preset layouts work (even-horizontal, etc.) → You understand layout algorithms

The Core Question You’re Answering

“How can I divide a rectangular terminal into arbitrary nested regions, where each region is a fully functional independent terminal, and have all of them render efficiently into a single physical screen?”

Before you write any code, sit with this question. When you split a tmux window, you’re not just drawing borders—you’re creating a tree of nested terminals, each with its own PTY, screen buffer, and cursor state. How do you calculate where each pane goes? How do you route keystrokes to the focused pane? How do you propagate terminal resizes through the entire tree? This is where tmux’s architecture becomes truly elegant.

Concepts You Must Understand First

Stop and research these before coding:

Tree Data Structures for Layout Representation
- How can you represent nested horizontal and vertical splits as a tree?
- What’s the difference between a “container” node and a “leaf” node?
- How do you traverse this tree to calculate each pane’s position?
- Why is a tree better than a list for this problem?
- Book Reference: “Introduction to Algorithms” Ch. 10.4 - Cormen et al.
Recursive Layout Calculation
- How do you divide available space among children?
- What happens when splits aren’t even (60/40 instead of 50/50)?
- How do you handle minimum size constraints (panes can’t be 0 pixels)?
- How do you calculate absolute positions from relative percentages?
- Book Reference: “Programming Pearls” Column 4: Writing Correct Programs - Jon Bentley
Sub-Screen Rendering (Rendering into a Region)
- How do you render a virtual screen buffer into a rectangular region?
- What coordinate transformations are needed?
- How do you clip content that would overflow the pane?
- How do you translate cursor positions from pane-local to screen-global?
- Book Reference: “Computer Graphics: Principles and Practice” Ch. 6: Viewing - Foley et al.
Focus Management and Input Routing
- How do you track which pane has focus?
- How do you route keystrokes to only the focused pane?
- What data structure makes focus navigation efficient (up/down/left/right)?
- How do you handle “cycle focus” vs directional focus change?
- Book Reference: “Design Patterns” - Command Pattern for input routing - Gamma et al.
SIGWINCH Propagation Through Pane Hierarchy
- When the terminal resizes, what’s the sequence of operations?
- How do you recalculate layouts without destroying state?
- How do you resize each PTY and send SIGWINCH to child processes?
- What happens if a pane becomes too small for its minimum size?
- Book Reference: “The Linux Programming Interface” Ch. 64.6 - Michael Kerrisk

Questions to Guide Your Design

Before implementing, think through these:

Tree Structure Design
- What fields does each tree node need (split direction, children, dimensions)?
- How do you distinguish between horizontal and vertical splits?
- How do you store the PTY handle and screen buffer for leaf nodes?
- How do you represent the percentage/size allocation for each child?
Layout Calculation Algorithm
- Should you calculate layouts top-down (parent assigns child positions) or bottom-up?
- How do you handle rounding errors when dividing pixels (49.5 rounds to what)?
- What’s your minimum pane size (10x10? 5x5?) and how do you enforce it?
- How do you prevent splits that would violate minimum sizes?
Rendering Strategy
- Do you render pane by pane, or build a complete screen buffer first?
- How do you draw borders between panes (who owns the border pixels)?
- How do you highlight the focused pane’s border?
- Do you render everything on every update, or track what changed?
Focus Navigation
- For directional focus change, how do you find “the pane to the right”?
- What if there are multiple panes in that direction?
- How does “cycle focus” differ from directional navigation?
- Should focus state be stored in nodes or separately?
Resize Handling
- When do you recalculate layouts (on every SIGWINCH, or throttled)?
- How do you preserve pane ratios during resize?
- What if the new terminal size is too small for all panes?
- How do you batch PTY resize operations for efficiency?

Thinking Exercise

Draw the tree structure by hand before coding:

Terminal: 80x24
├── VSplit (50/50)
    ├── Pane 1: 40x24 (left half)
    └── HSplit (50/50)
        ├── Pane 2: 40x12 (top-right)
        └── Pane 3: 40x12 (bottom-right)

Now trace through the layout calculation:

1. Root gets full space: (0,0) to (80,24)
2. VSplit divides width:
   - Left child gets: (0,0) to (40,24)
   - Right child gets: (40,0) to (80,24)
3. Pane 1 (leaf) renders at (0,0) to (40,24)
4. HSplit divides height of (40,0) to (80,24):
   - Top child gets: (40,0) to (80,12)
   - Bottom child gets: (40,12) to (80,24)
5. Pane 2 (leaf) renders at (40,0) to (80,12)
6. Pane 3 (leaf) renders at (40,12) to (80,24)

Now answer:

What if you split Pane 2 horizontally again?
Where would borders be drawn?
If you resize the terminal to 100x30, what are the new coordinates?
If focus is on Pane 3 and you press “focus left”, which pane gets focus?

The Interview Questions They’ll Ask

Prepare to answer these:

“How do you represent nested pane layouts in memory?”
“What algorithm do you use to calculate each pane’s screen position?”
“How do you handle terminal resize when you have multiple panes?”
“What’s the minimum pane size you allow, and why does that matter?”
“How do you determine which pane is ‘to the right’ of the current pane?”
“How do you render multiple virtual screens into one physical terminal?”
“What happens if you try to split a pane that’s too small?”
“How do you propagate SIGWINCH to all child processes efficiently?”
“Why use a tree structure instead of a flat list of panes?”
“How does tmux’s ‘even-horizontal’ layout differ from manual splitting?”

Hints in Layers

Only read these if you’re stuck. Try each step yourself first.

Hint 1: Tree Node Structure A minimal tree node might look like:

typedef enum { HORIZONTAL, VERTICAL, LEAF } NodeType;

typedef struct LayoutNode {
    NodeType type;
    struct {
        int x, y, width, height;  // Calculated screen position
    } rect;

    // For container nodes (HORIZONTAL/VERTICAL)
    struct LayoutNode **children;
    int num_children;
    float *child_ratios;  // e.g., [0.5, 0.5] for 50/50 split

    // For leaf nodes (LEAF)
    int pty_fd;
    ScreenBuffer *screen;

    struct LayoutNode *parent;
} LayoutNode;

Hint 2: Recursive Layout Calculation

void calculate_layout(LayoutNode *node, int x, int y, int width, int height) {
    node->rect = (Rect){x, y, width, height};

    if (node->type == LEAF) {
        // Leaf node: resize PTY to match allocated space
        struct winsize ws = {height, width, 0, 0};
        ioctl(node->pty_fd, TIOCSWINSZ, &ws);
        return;
    }

    // Container node: divide space among children
    if (node->type == HORIZONTAL) {
        int remaining_width = width;
        int offset_x = x;
        for (int i = 0; i < node->num_children; i++) {
            int child_width = (i == node->num_children - 1)
                ? remaining_width  // Last child gets all remaining (handles rounding)
                : (int)(width * node->child_ratios[i]);

            calculate_layout(node->children[i], offset_x, y, child_width, height);
            offset_x += child_width;
            remaining_width -= child_width;
        }
    } else {  // VERTICAL
        // Similar logic but divide height instead of width
    }
}

Hint 3: Rendering a Pane into a Region

void render_pane(LayoutNode *pane, Screen *output) {
    if (pane->type != LEAF) return;

    ScreenBuffer *buf = pane->screen;
    int pane_x = pane->rect.x;
    int pane_y = pane->rect.y;

    for (int row = 0; row < pane->rect.height; row++) {
        for (int col = 0; col < pane->rect.width; col++) {
            // Translate pane-local coordinates to screen coordinates
            int screen_x = pane_x + col;
            int screen_y = pane_y + row;

            // Copy cell from pane buffer to screen buffer
            if (row < buf->height && col < buf->width) {
                output->cells[screen_y][screen_x] = buf->cells[row][col];
            }
        }
    }

    // Draw border if this pane has focus
    if (pane == focused_pane) {
        draw_border(output, pane->rect, BORDER_COLOR_ACTIVE);
    } else {
        draw_border(output, pane->rect, BORDER_COLOR_INACTIVE);
    }
}

Hint 4: Focus Navigation (Directional)

LayoutNode* find_pane_in_direction(LayoutNode *current, Direction dir) {
    // Get center point of current pane
    int cx = current->rect.x + current->rect.width / 2;
    int cy = current->rect.y + current->rect.height / 2;

    // Find all leaf panes
    LayoutNode **all_panes = get_all_leaf_panes(root);
    LayoutNode *best = NULL;
    int best_distance = INT_MAX;

    for (int i = 0; all_panes[i]; i++) {
        if (all_panes[i] == current) continue;

        int tx = all_panes[i]->rect.x + all_panes[i]->rect.width / 2;
        int ty = all_panes[i]->rect.y + all_panes[i]->rect.height / 2;

        // Check if target is in the correct direction
        bool correct_dir = false;
        if (dir == RIGHT && tx > cx) correct_dir = true;
        if (dir == LEFT && tx < cx) correct_dir = true;
        if (dir == DOWN && ty > cy) correct_dir = true;
        if (dir == UP && ty < cy) correct_dir = true;

        if (correct_dir) {
            int dist = abs(tx - cx) + abs(ty - cy);
            if (dist < best_distance) {
                best_distance = dist;
                best = all_panes[i];
            }
        }
    }

    return best;
}

Hint 5: Handling Split Operations

LayoutNode* split_pane(LayoutNode *pane, NodeType split_type) {
    if (pane->type != LEAF) return NULL;  // Can only split leaf panes

    // Check minimum size
    int min_size = 10;
    if ((split_type == HORIZONTAL && pane->rect.width < min_size * 2) ||
        (split_type == VERTICAL && pane->rect.height < min_size * 2)) {
        return NULL;  // Too small to split
    }

    // Create new container node
    LayoutNode *container = create_node(split_type);
    container->num_children = 2;
    container->children = malloc(sizeof(LayoutNode*) * 2);
    container->child_ratios = malloc(sizeof(float) * 2);
    container->child_ratios[0] = 0.5;
    container->child_ratios[1] = 0.5;

    // Create new pane
    LayoutNode *new_pane = create_leaf_pane();

    // Rearrange tree: container replaces pane in parent
    container->parent = pane->parent;
    if (pane->parent) {
        // Replace pane with container in parent's children
        for (int i = 0; i < pane->parent->num_children; i++) {
            if (pane->parent->children[i] == pane) {
                pane->parent->children[i] = container;
                break;
            }
        }
    } else {
        // pane was root; container becomes new root
        root = container;
    }

    // Container's children are old pane and new pane
    container->children[0] = pane;
    container->children[1] = new_pane;
    pane->parent = container;
    new_pane->parent = container;

    // Recalculate layout
    calculate_layout(root, 0, 0, terminal_width, terminal_height);

    return new_pane;
}

Books That Will Help

Topic	Book	Chapter
Tree data structures	“Introduction to Algorithms”	Ch. 10.4: Representing rooted trees
Recursive algorithms	“The Algorithm Design Manual”	Ch. 3: Data Structures
Layout algorithms (conceptual)	Study i3wm source code	i3 tree documentation
Screen buffer management	“NCURSES Programming HOWTO”	Panel Library section
PTY resizing	“The Linux Programming Interface”	Ch. 64.6: Changing Terminal Window Size
Signal propagation	“Advanced Programming in the UNIX Environment”	Ch. 10: Signals
Focus and input routing	“Design Patterns”	Command Pattern
Coordinate systems	“Computer Graphics: Principles and Practice”	Ch. 6: Viewing in 2D

Project 10: Session and Window Hierarchy

File: DEEP_UNDERSTANDING_TMUX_PROJECTS.md
Main Programming Language: C
Alternative Programming Languages: Rust
Coolness Level: Level 4: Hardcore Tech Flex
Business Potential: 1. The “Resume Gold” (Educational/Personal Brand)
Difficulty: Level 4: Expert
Knowledge Area: State Management / UI Design
Software or Tool: tmux
Main Book: “Advanced Programming in the UNIX Environment” by W. Richard Stevens

What you’ll build: Add the full session → window → pane hierarchy, allowing multiple named sessions, multiple windows per session, and switching between them.

Why it teaches tmux fundamentals: This is the complete tmux data model. Understanding how sessions, windows, and panes relate is essential for power-user workflows.

Core challenges you’ll face:

Hierarchical state management (sessions contain windows contain panes) → maps to tmux’s object model
Naming and indexing (session names, window numbers) → maps to tmux new-session -s, new-window
Session switching (attach to different session) → maps to tmux switch-client
Window selection (status bar, window list) → maps to tmux select-window
State persistence (save/restore session layouts) → maps to tmux-resurrect plugin concept

Key Concepts:

tmux Object Model: The Tao of tmux - Technical Stuff - Tony Narlock
State Machine Design: “Design Patterns” State Pattern - Gamma et al.
Tree Data Structures: “Algorithms, Fourth Edition” Chapter 3 - Sedgewick & Wayne

Difficulty: Expert Time estimate: 2-3 weeks Prerequisites: Project 9 completed

Real world outcome:

$ ./mux new-session -s work
# Session "work" created

$ Ctrl-B c  # new window
$ Ctrl-B ,  # rename window to "code"

$ Ctrl-B c  # another window
$ Ctrl-B ,  # rename to "tests"

$ ./mux new-session -s personal
# Session "personal" created (in background)

$ Ctrl-B (  # previous session
$ Ctrl-B )  # next session
$ Ctrl-B s  # session list
  work: 2 windows
  personal: 1 windows

$ Ctrl-B w  # window list
  (0) work
    0: code*
    1: tests
  (1) personal
    0: bash

Implementation Hints: Model this as: Server has a list of Sessions. Each Session has a list of Windows. Each Window has a tree of Panes. Each Pane has a PTY and a Screen buffer. Each Session tracks its current Window. Each Window tracks its active Pane.

When rendering, you render the current Window of the attached Session.

Learning milestones:

Can create multiple sessions → Session management works
Can create multiple windows → Window management works
Session/window selection works → Navigation works
Status line shows hierarchy → State is visible
Detach from one session, attach to another → Full workflow works

The Core Question You’re Answering

“How does tmux organize sessions, windows, and panes into a coherent hierarchy, and how does the server manage multiple independent workspaces?”

Before you code, understand this: tmux’s genius is its three-level hierarchy. A session is a workspace that can have multiple windows. A window is a view that can have multiple panes. A pane is the actual terminal. When you “switch sessions,” you’re not killing anything—you’re just changing which session’s windows the client displays. This data model is what makes tmux infinitely more powerful than simple terminal splitting.

Concepts You Must Understand First

Stop and research these before coding:

Object Hierarchies and Ownership
- How do you model a tree where each node owns its children?
- What’s the difference between composition and aggregation?
- Who is responsible for freeing memory in a parent-child hierarchy?
- How do you navigate upward (child to parent) and downward (parent to children)?
- Book Reference: “Design Patterns” - Composite Pattern - Gamma et al.
Naming vs Indexing
- Sessions have string names (e.g., “work”), windows have numeric indices (0, 1, 2…)
- How do you implement both lookup by name and lookup by index efficiently?
- What happens when you delete window 1 from [0, 1, 2]—do you renumber?
- Should session names be unique? What about window names?
- Book Reference: “Algorithms, Fourth Edition” Ch. 3 - Sedgewick & Wayne
Current/Active Tracking
- The server has a “current session” (the one the client is attached to)
- Each session has a “current window” (the one being displayed)
- Each window has an “active pane” (the one receiving input)
- How do you maintain these “current” pointers as things are created/destroyed?
- What happens when you delete the current window?
- Book Reference: “Design Patterns” State Pattern - Gamma et al.
Session Attachment Model
- Multiple clients can attach to the same session (pair programming!)
- A session can exist with zero attached clients (detached)
- How do you track which clients are attached to which session?
- What happens when the last client detaches?
- Book Reference: “Advanced Programming in the UNIX Environment” Ch. 13 - W. Richard Stevens
List Navigation UI
- Ctrl-B s shows a session list you can navigate with arrow keys
- Ctrl-B w shows a hierarchical window list
- How do you render a selectable list in the terminal?
- How do you handle input while in “selection mode”?
- Book Reference: “The Tao of tmux - Technical Stuff” - Tony Narlock

Questions to Guide Your Design

Before implementing, think through these:

Data Structure Design
- What struct represents a Session? What fields does it need?
- What struct represents a Window? How does it reference its parent Session?
- How do you represent the “list of windows” in a session—array or linked list?
- Where do you store session names? Window titles?
- Should sessions store a pointer to the server, or should the server store a list of sessions?
Creation and Destruction
- When you create a new session, what’s the minimum setup required?
- Does a new session automatically get a first window? Does that window get a first pane?
- When you delete a session, how do you ensure all its windows and panes are freed?
- What happens if you try to delete the last session?
- What happens if you try to delete the last window in a session?
Navigation and Selection
- How do you implement “switch to session by name”?
- How do you implement “switch to next session”?
- How do you implement “select window 3 in the current session”?
- What happens if you select window 5 but the session only has 3 windows?
- How do you implement Ctrl-B w’s hierarchical list?
Current/Active Management
- When you create a new window, does it become the current window automatically?
- When you delete the current window, which window becomes current?
- If you’re attached to session “work” and you create session “personal,” which is current?
- How do you switch back to the previous session (Ctrl-B ( and Ctrl-B ))?
State Visibility
- How do you generate the session list shown by Ctrl-B s?
- How do you count “2 windows” for each session?
- How do you mark the current session and current window in the list?
- Where in your rendering pipeline do you display this information?

Thinking Exercise

Draw the object hierarchy on paper before coding:

Server
  |
  +-- List of Sessions
        |
        +-- Session "work"
        |     |
        |     +-- Name: "work"
        |     +-- Current Window: pointer to Window 0
        |     +-- List of Windows
        |           |
        |           +-- Window 0: "code"
        |           |     |
        |           |     +-- Title: "code"
        |           |     +-- Index: 0
        |           |     +-- Active Pane: pointer to Pane
        |           |     +-- Pane tree (from Project 9)
        |           |
        |           +-- Window 1: "tests"
        |                 |
        |                 +-- Title: "tests"
        |                 +-- Index: 1
        |                 +-- Active Pane: pointer to Pane
        |                 +-- Pane tree
        |
        +-- Session "personal"
              |
              +-- Name: "personal"
              +-- Current Window: pointer to Window 0
              +-- List of Windows
                    |
                    +-- Window 0: "bash"
                          |
                          +-- Title: "bash"
                          +-- Index: 0
                          +-- Active Pane: pointer to Pane
                          +-- Pane tree

Now trace these operations:

User runs ./mux new-session -s work → What gets created? In what order?
User presses Ctrl-B c → Where is the new window inserted? What becomes current?
User runs ./mux new-session -s personal → Does this change the attached session?
User presses Ctrl-B s → What data do you traverse to build the list?
User selects “personal” from the list → What pointers change?

The Interview Questions They’ll Ask

Prepare to answer these:

“Explain tmux’s three-level hierarchy: sessions, windows, and panes.”
“What’s the difference between a session and a window in tmux?”
“How can multiple clients attach to the same tmux session?”
“What happens to a session’s windows when you detach from the session?”
“How does tmux track which window is ‘current’ in each session?”
“Why use numeric indices for windows but string names for sessions?”
“What data structure would you use to store a session’s list of windows?”
“How would you implement ‘switch to next session’ in O(1) time?”
“What happens when you delete the current window in a session with 3 windows?”
“How would you implement session name uniqueness? Where would you check for duplicates?”

Hints in Layers

Only read these if you’re stuck. Try each step yourself first.

Hint 1: Core Data Structures Think in terms of ownership. The server owns sessions, sessions own windows, windows own pane trees:

typedef struct Server {
    struct Session **sessions;  // Dynamic array of session pointers
    int num_sessions;
    struct Session *current_session;  // The one clients are viewing
} Server;

typedef struct Session {
    char *name;                 // "work", "personal", etc.
    struct Window **windows;    // Dynamic array of window pointers
    int num_windows;
    struct Window *current_window;  // The one being displayed
    struct Server *server;      // Back-pointer to parent
} Session;

typedef struct Window {
    int index;                  // 0, 1, 2...
    char *title;               // "code", "tests", etc.
    struct Pane *pane_tree;    // Root of the pane tree (from Project 9)
    struct Pane *active_pane;  // Which pane has focus
    struct Session *session;   // Back-pointer to parent
} Window;

Hint 2: Session Creation When creating a session, you need to initialize it with at least one window:

Session *create_session(Server *server, const char *name) {
    Session *sess = malloc(sizeof(Session));
    sess->name = strdup(name);
    sess->server = server;
    sess->num_windows = 0;
    sess->windows = NULL;

    // Create first window automatically
    Window *win = create_window(sess, 0);
    add_window_to_session(sess, win);
    sess->current_window = win;

    // Add session to server's list
    add_session_to_server(server, sess);

    return sess;
}

Hint 3: Window Management Windows need both index-based and current tracking:

Window *create_window(Session *session, int index) {
    Window *win = malloc(sizeof(Window));
    win->index = index;
    win->title = strdup("bash");  // Default title
    win->session = session;

    // Create initial pane (from Project 9)
    win->pane_tree = create_pane();
    win->active_pane = win->pane_tree;

    return win;
}

void add_window_to_session(Session *sess, Window *win) {
    sess->windows = realloc(sess->windows,
                           (sess->num_windows + 1) * sizeof(Window*));
    sess->windows[sess->num_windows++] = win;
}

Hint 4: Session Switching Switching sessions is just changing the server’s current_session pointer:

void switch_session(Server *server, const char *session_name) {
    for (int i = 0; i < server->num_sessions; i++) {
        if (strcmp(server->sessions[i]->name, session_name) == 0) {
            server->current_session = server->sessions[i];
            // Trigger a full redraw
            render_current_window(server);
            return;
        }
    }
    fprintf(stderr, "Session '%s' not found\n", session_name);
}

void next_session(Server *server) {
    int current_idx = find_session_index(server, server->current_session);
    int next_idx = (current_idx + 1) % server->num_sessions;
    server->current_session = server->sessions[next_idx];
    render_current_window(server);
}

Hint 5: Rendering the Session List The Ctrl-B s command needs to traverse all sessions and format them:

void render_session_list(Server *server) {
    printf("\nSessions:\n");
    for (int i = 0; i < server->num_sessions; i++) {
        Session *sess = server->sessions[i];

        // Mark current session with an asterisk
        char marker = (sess == server->current_session) ? '*' : ' ';

        printf("%c (%d) %s: %d window%s\n",
               marker,
               i,
               sess->name,
               sess->num_windows,
               sess->num_windows == 1 ? "" : "s");

        // Optionally show windows too (Ctrl-B w style)
        for (int j = 0; j < sess->num_windows; j++) {
            Window *win = sess->windows[j];
            char win_marker = (win == sess->current_window) ? '*' : ' ';
            printf("  %c %d: %s\n", win_marker, win->index, win->title);
        }
    }

    // Now enter selection mode (wait for arrow keys and Enter)
    int selected = handle_list_selection(server->num_sessions);
    if (selected >= 0) {
        server->current_session = server->sessions[selected];
    }
}

Books That Will Help

Topic	Book	Chapter
Hierarchical data structures	“Algorithms, Fourth Edition”	Ch. 3: Searching (symbol tables, trees)
Composite pattern (tree of objects)	“Design Patterns”	Composite Pattern
State pattern (current/active tracking)	“Design Patterns”	State Pattern
Memory management in C	“The C Programming Language”	Ch. 5: Pointers and Arrays
Dynamic arrays and realloc	“Advanced Programming in the UNIX Environment”	Ch. 7: Process Environment
List data structures	“Introduction to Algorithms”	Ch. 10: Elementary Data Structures
Session management concepts	“The Tao of tmux - Technical Stuff”	Session and Window sections

Project 11: Status Bar and Mode Rendering

File: DEEP_UNDERSTANDING_TMUX_PROJECTS.md
Main Programming Language: C
Alternative Programming Languages: Rust, Go
Coolness Level: Level 3: Genuinely Clever
Business Potential: 2. The “Micro-SaaS / Pro Tool”
Difficulty: Level 3: Advanced
Knowledge Area: Terminal UI / Configuration
Software or Tool: tmux
Main Book: “tmux 3: Productive Mouse-Free Development” by Brian P. Hogan

What you’ll build: A customizable status bar showing session/window info, time, and other data, plus different “modes” (normal, copy, command prompt).

Why it teaches tmux fundamentals: The status bar is tmux’s primary UI element. Understanding how it’s rendered and updated teaches you about tmux’s refresh cycle and format strings.

Core challenges you’ll face:

Status bar rendering (reserve a line, update periodically) → maps to tmux status-left, status-right
Format string parsing (#W for window name, #S for session, etc.) → maps to tmux’s format language
Mode overlays (copy mode shows different UI) → maps to tmux modes
Color and style (status bar styling) → maps to tmux status-style
Conditional rendering (show alerts, activity markers) → maps to tmux monitoring options

Key Concepts:

tmux Status Bar: “tmux 3: Productive Mouse-Free Development” Chapter 2 - Brian P. Hogan
Format Strings: “tmux 3” Appendix A - Brian P. Hogan
Terminal Rendering: Project 6 experience

Difficulty: Advanced Time estimate: 1 week Prerequisites: Project 10 completed, TUI library (Project 6)

Real world outcome:

# Status bar at bottom:
[work] 0:bash  1:vim*  2:tests                    12:34 PM

# In copy mode:
[work] 0:bash  1:vim*  2:tests        [copy mode] 12:34 PM

# Activity in window 2:
[work] 0:bash  1:vim*  2:tests#                   12:34 PM
                           ^-- alert indicator

# Custom format:
$ ./mux set-option status-right '#H | %Y-%m-%d'
[work] 0:bash  1:vim*              hostname | 2024-01-15

Implementation Hints: Reserve the last line of the terminal for the status bar. Render panes in rows 0 to (height-2), status bar in row (height-1).

For format strings, implement a simple substitution engine: scan for #, look up the format character, substitute the value. Start with #S (session), #W (window), #P (pane), #T (title).

Learning milestones:

Static status bar renders → Basic rendering works
Format substitution works → Dynamic content works
Mode indicator changes → Mode system works
Periodic updates work (time changes) → Timer integration works
Activity alerts appear → Event system works

The Core Question You’re Answering

“How does tmux reserve screen space for its UI chrome, and how does it parse those cryptic format strings like #S and #W to display dynamic information?”

The status bar is tmux’s “control panel”—it shows you what’s happening without interfering with your terminal programs. Understanding how to reserve a line, update it periodically, and parse user-defined format strings teaches you about UI rendering in TUI applications and the separation between application state and presentation.

Concepts You Must Understand First

Stop and research these before coding:

Screen Real Estate Management
- How do you “reserve” a line at the bottom of the terminal?
- What happens to pane rendering when the status bar is enabled?
- How do you prevent panes from writing to the status bar line?
- If your terminal is 24 rows, how many rows can panes use with a status bar?
- Book Reference: “tmux 3: Productive Mouse-Free Development” Ch. 2 - Brian P. Hogan
Format String Parsing
- What is a format string (think printf, strftime)?
- How do you scan a string for special markers like #S or #W?
- What’s the difference between #S (session name) and #(command) (shell execution)?
- How do you handle invalid or unknown format codes gracefully?
- Reference: tmux man page, “FORMAT” section
- Book Reference: “The Practice of Programming” Ch. 9 - Kernighan & Pike
Periodic Updates and Timers
- Why does the status bar showing time need to update even when nothing happens?
- How do you integrate a periodic timer into your event loop?
- What’s the difference between “update on event” and “update on timer”?
- How frequently should the status bar refresh (hint: tmux uses status-interval)?
- Book Reference: “The Linux Programming Interface” Ch. 23 - Timers and Sleeping
Mode Indicators
- What modes does tmux have (normal, copy mode, command prompt)?
- How does the status bar change when you enter copy mode?
- Should the mode indicator be part of status-left, status-right, or separate?
- How do you communicate mode changes from your mode system to the status bar?
Activity and Alert Markers
- What does the # marker next to a window name mean in tmux?
- How does the status bar know when a window has activity?
- What’s the difference between “activity” and “bell”?
- How do you track which windows have unseen activity?
- Book Reference: “tmux 3: Productive Mouse-Free Development” Ch. 2 - Brian P. Hogan

Questions to Guide Your Design

Before implementing, think through these:

Status Bar Layout
- Will you use the top line or bottom line for the status bar?
- How do you split the status bar into left, center, and right sections?
- What if status-left is too long and overlaps status-right?
- How do you handle truncation (show ... when text is too long)?
Format String Engine
- Will you parse the entire format string once and cache the result, or parse on every render?
- How do you handle nested format codes (e.g., #[fg=red]#S#[default])?
- Should #(command) be executed synchronously or asynchronously?
- How do you escape a literal # character?
Update Strategy
- What events should trigger a status bar redraw?
  - Window creation/destruction?
  - Pane focus change?
  - Timer tick?
  - Mode change?
- How do you avoid redrawing the status bar unnecessarily?
- Can you implement “dirty tracking” to only update when needed?
Color and Style Handling
- How do you apply colors to the status bar (hint: status-style)?
- What about per-section styles (status-left-style, status-right-style)?
- How do you handle inline style changes (e.g., #[fg=red]text#[default])?
- Do you need to track a “current style” stack?
Mode Overlay
- When entering copy mode, does the entire status bar change or just part of it?
- Should the mode indicator have its own style?
- How do you communicate the current mode to the status bar renderer?
- What happens if the user customizes the status bar and there’s no room for the mode indicator?

Thinking Exercise

Design the format string parser on paper before coding:

Given the format string:

[#S] #I:#W#F  #(uptime | awk '{print $3}')  %H:%M

Expected output:

[work] 1:vim*  up 5 days  14:32

Trace through parsing:

Input: "[#S] #I:#W#F  #(uptime | awk '{print $3}')  %H:%M"

Step 1: Find '[', it's literal, output '['
Step 2: Find '#S', it's a format code, substitute with session name "work"
Step 3: Find ']', literal, output ']'
Step 4: Find ' ', literal, output ' '
Step 5: Find '#I', substitute with window index "1"
Step 6: Find ':', literal, output ':'
Step 7: Find '#W', substitute with window name "vim"
Step 8: Find '#F', substitute with window flags "*"
... and so on

Now consider:

What data structure holds the current session, window, and pane info?
How do you execute #(uptime | awk '{print $3}') and capture its output?
How do you handle %H:%M (strftime format)?
What if the command takes too long (hangs)?

Draw a state machine or write pseudocode for your parser before touching C.

The Interview Questions They’ll Ask

Prepare to answer these:

“How does tmux reserve a line at the bottom for its status bar?”
“What’s the difference between #S, #W, and #(command) in tmux format strings?”
“How would you implement a format string parser that handles escape sequences?”
“Why does the tmux status bar update every second even when nothing is happening?”
“What’s the difference between status-left and status-right? How do you handle overlaps?”
“How does tmux know when a window has activity?”
“What happens when you enter copy mode? How does the status bar change?”
“How would you prevent a long-running #(command) from freezing the entire UI?”
“What’s the purpose of status-interval in tmux?”
“How do you apply colors to different parts of the status bar?”

Hints in Layers

Only read these if you’re stuck. Try each step yourself first.

Hint 1: Reserving the Status Bar Line

// If terminal has H rows, panes can use rows 0 to (H-2)
// Status bar is always row (H-1)
int pane_height = terminal_height - 1;  // Reserve last line
// When rendering panes, restrict to pane_height rows
// Then render status bar at row pane_height

Hint 2: Basic Format String Substitution

// Naive approach: scan for '#', check next char, substitute
char* render_format(const char* format, Session* session, Window* window) {
    char result[1024];
    int j = 0;
    for (int i = 0; format[i]; i++) {
        if (format[i] == '#' && format[i+1]) {
            switch (format[i+1]) {
                case 'S':
                    j += sprintf(result + j, "%s", session->name);
                    i++;  // Skip next char
                    break;
                case 'W':
                    j += sprintf(result + j, "%s", window->name);
                    i++;
                    break;
                case 'I':
                    j += sprintf(result + j, "%d", window->index);
                    i++;
                    break;
                // ... more cases
                default:
                    result[j++] = format[i];
            }
        } else {
            result[j++] = format[i];
        }
    }
    result[j] = '\0';
    return strdup(result);
}

Hint 3: Periodic Timer Updates

// In your event loop, add a timer
struct timeval timeout;
timeout.tv_sec = 1;  // Update every second
timeout.tv_usec = 0;

while (1) {
    fd_set read_fds;
    FD_ZERO(&read_fds);
    // ... add your other fds

    int ret = select(max_fd + 1, &read_fds, NULL, NULL, &timeout);

    if (ret == 0) {
        // Timeout expired, update status bar
        render_status_bar();
        timeout.tv_sec = 1;  // Reset timer
    } else {
        // Handle other events
    }
}

Hint 4: Mode Indicator

// Keep track of current mode
enum Mode {
    MODE_NORMAL,
    MODE_COPY,
    MODE_COMMAND
};

// In status bar rendering:
const char* mode_indicator(enum Mode mode) {
    switch (mode) {
        case MODE_COPY:    return "[copy mode]";
        case MODE_COMMAND: return "[command]";
        default:           return "";
    }
}

// Render as part of status-right:
sprintf(status_right, "%s  %s", mode_indicator(current_mode), time_string);

Hint 5: Activity Markers

// Each window tracks activity
struct Window {
    // ... other fields
    bool has_activity;  // Set when pane writes and window isn't focused
    bool has_bell;      // Set when bell char received
};

// In format string:
case 'F':  // Flags
    if (window->is_active) {
        result[j++] = '*';
    }
    if (window->has_activity) {
        result[j++] = '#';
    }
    if (window->has_bell) {
        result[j++] = '!';
    }
    break;

Books That Will Help

Topic	Book	Chapter
Status bar concepts	“tmux 3: Productive Mouse-Free Development”	Ch. 2: Configuring tmux
Format strings reference	tmux man page	FORMATS section
String parsing techniques	“The Practice of Programming”	Ch. 9: Notation
Timer and event loops	“The Linux Programming Interface”	Ch. 23: Timers and Sleeping
String formatting in C	“C Programming: A Modern Approach”	Ch. 13: Strings
Terminal attribute handling	“NCURSES Programming HOWTO”	Ch. 5: Attributes
Event-driven programming	“Unix Network Programming Vol. 1”	Ch. 6: I/O Multiplexing

Project 12: Copy Mode and Scrollback

File: DEEP_UNDERSTANDING_TMUX_PROJECTS.md
Main Programming Language: C
Alternative Programming Languages: Rust
Coolness Level: Level 3: Genuinely Clever
Business Potential: 2. The “Micro-SaaS / Pro Tool”
Difficulty: Level 4: Expert
Knowledge Area: Text Editing / Terminal Buffers
Software or Tool: tmux / vim
Main Book: “tmux 3: Productive Mouse-Free Development” by Brian P. Hogan

What you’ll build: Scrollback history (lines that scrolled off the top) and a “copy mode” where you can navigate, search, and select text.

Why it teaches tmux fundamentals: Copy mode is one of tmux’s most powerful features. It transforms a terminal from “ephemeral” to “persistent”—you can scroll back and copy anything.

Core challenges you’ll face:

Scrollback buffer (storing lines that scroll off) → maps to tmux history-limit
Mode switching (entering/exiting copy mode) → maps to tmux copy-mode
Vi-style navigation (hjkl, gg, G, /search) → maps to tmux copy-mode-vi
Selection and copying (visual selection, yanking) → maps to tmux copy-selection
Paste buffer (storing copied text) → maps to tmux paste-buffer

Key Concepts:

tmux Copy Mode: “tmux 3: Productive Mouse-Free Development” Chapter 4 - Brian P. Hogan
Vi Key Bindings: “Practical Vim, 2nd Edition” Chapters 1-3 - Drew Neil
Circular Buffers: “Data Structures the Fun Way” - Jeremy Kubica

Difficulty: Expert Time estimate: 2-3 weeks Prerequisites: Project 11 completed

Real world outcome:

# Normal mode, lots of output has scrolled by...

$ Ctrl-B [  # enter copy mode
[copy mode]

$ k/j  # scroll up/down
$ gg   # go to top of scrollback
$ G    # go to bottom
$ /error  # search for "error"
$ n/N  # next/previous match
$ v    # start selection
$ y    # yank selection

$ Ctrl-B ]  # paste

Implementation Hints: The scrollback buffer is typically a circular buffer of lines. When a line scrolls off the top of the screen, append it to scrollback. In copy mode, you’re rendering from the scrollback buffer plus the current screen.

Selection requires tracking start and end positions. When yanking, extract the text between them and store it in a paste buffer (could also integrate with system clipboard via escape sequences or external commands).

Learning milestones:

Scrollback stores history → Buffer management works
Copy mode shows scrollback → Mode rendering works
Navigation works (hjkl, gg, G) → Vi bindings work
Search works → Text search works
Select and yank works → Copy/paste works

The Core Question You’re Answering

“How do you make terminal output persistent and navigable, allowing users to search through, select, and copy any text that has scrolled off the screen?”

Before you write any code, consider this: In a normal terminal, once text scrolls off the top, it’s gone (or limited by the terminal emulator’s buffer). But tmux transforms the terminal into something more like a text editor—you can enter “copy mode” and navigate through history with vim keybindings. How do you store that history? How do you switch between “normal terminal mode” and “navigation mode”? This is what makes tmux feel powerful and professional.

Concepts You Must Understand First

Stop and research these before coding:

Circular Buffers / Ring Buffers
- Why use a circular buffer instead of a dynamic array?
- How do you handle buffer overflow (when history exceeds the limit)?
- How do read and write pointers work in a circular buffer?
- What’s the modulo arithmetic for wrapping around?
- Book Reference: “Data Structures the Fun Way” Ch. 5 - Jeremy Kubica
Mode Switching and State Machines
- How do you represent “normal mode” vs “copy mode” in your program state?
- What data needs to be saved/restored when entering/exiting copy mode?
- How does mode affect key binding interpretation?
- What is the cursor position in copy mode vs normal mode?
- Book Reference: “tmux 3: Productive Mouse-Free Development” Ch. 4 - Brian P. Hogan
Vi-Style Navigation Keybindings
- What are the fundamental vi movement commands (hjkl, w, b, 0, $, gg, G)?
- How does vi’s visual selection mode work?
- What’s the difference between character-wise and line-wise selection?
- How does search (/ and ?) work in vi, including n/N for next/previous?
- Book Reference: “Practical Vim, 2nd Edition” Ch. 1-3 - Drew Neil
Text Selection Models
- How do you represent a selection (start position + end position)?
- Should selection be inclusive or exclusive at the boundaries?
- How do you handle selections that span multiple lines?
- What happens when the user moves the cursor after starting a selection?
- Book Reference: “tmux 3: Productive Mouse-Free Development” Ch. 4.3 - Brian P. Hogan
Clipboard Integration
- What’s the difference between tmux’s internal paste buffer and the system clipboard?
- How do you access the system clipboard from a terminal program?
- What are OSC 52 escape sequences and how do they enable clipboard access?
- How does X11 clipboard (xclip/xsel) vs macOS pbcopy/pbpaste work?
- Book Reference: “tmux 3: Productive Mouse-Free Development” Ch. 4.4 - Brian P. Hogan

Questions to Guide Your Design

Before implementing, think through these:

Scrollback Buffer Architecture
- How many lines of history will you store (history-limit)?
- Will you use a circular buffer or a linked list of line objects?
- How do you store line data (fixed-width arrays, or variable-length with pointers)?
- Should you store raw text or screen cells with attributes (colors, bold, etc.)?
Mode Transition Logic
- What key combination enters copy mode (Ctrl-B [)?
- How do you exit copy mode (q, Escape, or Enter)?
- What happens to the cursor position when entering copy mode?
- Should the view start at the bottom (current screen) or at a specific position?
Viewport and Cursor Management
- In copy mode, how do you track both viewport position and cursor position?
- How do you scroll the viewport when the cursor moves beyond visible area?
- What’s the coordinate system (0-indexed? line number + column number)?
- How do you handle viewport limits (can’t scroll above first line or below last line)?
Vi Keybinding Implementation
- How will you map keys to actions (switch statement, function pointer table, hash map)?
- How do you handle multi-key commands like “gg” (requires state)?
- How do you implement count prefixes like “5j” (move down 5 lines)?
- What subset of vi commands will you support initially?
Search Functionality
- How do you store the search pattern (regex or simple string matching)?
- Should search wrap around from bottom to top?
- How do you highlight search matches in the display?
- How do you implement n/N for navigating between matches?
Selection and Yank
- How do you represent selection state (start position, current position, mode)?
- What visual feedback shows the selected region?
- How do you extract the text between two positions (handle line wrapping)?
- Where do you store the yanked text (internal buffer, global variable)?
Paste Buffer and Clipboard
- Will you maintain multiple paste buffers (like vim’s registers)?
- How do you integrate with the system clipboard?
- Should pasting happen in normal mode or copy mode?
- How do you handle special characters in pasted text?

Thinking Exercise

Design the scrollback buffer and selection model on paper before coding:

Terminal Screen (24 rows visible):
Row 0:  [old output that scrolled off]
Row 1:  [old output that scrolled off]
...
Row 999: [oldest line in scrollback buffer]

Scrollback Buffer (circular buffer, 1000 line limit):
  write_ptr → [newest line that scrolled off]
  read_ptr →  [where we're currently viewing from in copy mode]

Current Screen (what's actively displayed in normal mode):
  Row 0:  $ ls -la
  Row 1:  total 48
  Row 2:  drwxr-xr-x  12 user  staff   384 Dec 20 10:23 .
  ...
  Row 23: $█  [cursor here in normal mode]

Copy Mode State:
  mode: COPY_MODE
  viewport_top: line 500 in scrollback
  cursor_line: 520
  cursor_col: 15
  selection_active: true
  selection_start: (line=520, col=10)
  selection_end: (cursor_line, cursor_col)

Draw this diagram yourself. Now trace what happens when:

User presses Ctrl-B [ to enter copy mode
User presses k (move up) 10 times
User presses v (start visual selection)
User presses w (move forward by word)
User presses y (yank selection)
User presses q (exit copy mode)
User presses Ctrl-B ] (paste)

Where does each piece of state live? What needs to be updated at each step?

The Interview Questions They’ll Ask

Prepare to answer these:

“Why would you use a circular buffer for scrollback history instead of a dynamic array?”
“How does tmux’s copy mode differ from a terminal emulator’s scrollback feature?”
“What’s the difference between tmux’s paste buffer and the system clipboard?”
“How do you implement vi-style keybindings without reimplementing all of vim?”
“What’s the computational complexity of searching through scrollback history?”
“How would you optimize rendering when scrolling through large amounts of history?”
“Why does tmux support both emacs and vi keybindings for copy mode?”
“How do OSC 52 escape sequences enable clipboard integration in remote sessions?”
“What happens to the scrollback buffer when a pane is resized?”
“How would you implement a feature to save scrollback history to a file?”

Hints in Layers

Only read these if you’re stuck. Try each step yourself first.

Hint 1: Circular Buffer for Scrollback

typedef struct {
    char **lines;          // Array of line pointers
    int capacity;          // Max lines (history-limit)
    int count;             // Current number of lines
    int head;              // Index where next line will be written
} ScrollbackBuffer;

void scrollback_append(ScrollbackBuffer *sb, const char *line) {
    if (sb->count < sb->capacity) {
        sb->lines[sb->count++] = strdup(line);
    } else {
        free(sb->lines[sb->head]);
        sb->lines[sb->head] = strdup(line);
        sb->head = (sb->head + 1) % sb->capacity;
    }
}

Hint 2: Copy Mode State Structure

typedef enum {
    MODE_NORMAL,
    MODE_COPY
} PaneMode;

typedef struct {
    PaneMode mode;
    int viewport_offset;    // How many lines scrolled up from bottom
    int cursor_row;         // Cursor position in copy mode
    int cursor_col;
    bool selection_active;
    int sel_start_row;
    int sel_start_col;
    int sel_end_row;
    int sel_end_col;
} CopyModeState;

Hint 3: Vi Keybinding Dispatcher

void handle_copy_mode_key(CopyModeState *state, char key) {
    switch (key) {
        case 'h': move_cursor_left(state); break;
        case 'j': move_cursor_down(state); break;
        case 'k': move_cursor_up(state); break;
        case 'l': move_cursor_right(state); break;
        case 'g':
            // Need to check next key for 'gg'
            if (get_next_key() == 'g') goto_top(state);
            break;
        case 'G': goto_bottom(state); break;
        case 'v': toggle_visual_selection(state); break;
        case 'y': yank_selection(state); exit_copy_mode(state); break;
        case '/': enter_search_mode(state); break;
        case 'q': exit_copy_mode(state); break;
    }
}

Hint 4: Text Selection and Extraction

char *extract_selection(CopyModeState *state, ScrollbackBuffer *sb) {
    int start_row = min(state->sel_start_row, state->sel_end_row);
    int end_row = max(state->sel_start_row, state->sel_end_row);

    // Calculate total size needed
    size_t total_size = 0;
    for (int row = start_row; row <= end_row; row++) {
        total_size += strlen(get_line(sb, row)) + 1;  // +1 for newline
    }

    char *result = malloc(total_size + 1);
    char *ptr = result;

    for (int row = start_row; row <= end_row; row++) {
        const char *line = get_line(sb, row);
        int start_col = (row == start_row) ? state->sel_start_col : 0;
        int end_col = (row == end_row) ? state->sel_end_col : strlen(line);

        memcpy(ptr, line + start_col, end_col - start_col);
        ptr += (end_col - start_col);
        *ptr++ = '\n';
    }
    *ptr = '\0';
    return result;
}

Hint 5: OSC 52 Clipboard Integration

void copy_to_system_clipboard(const char *text) {
    // OSC 52 sequence: ESC ] 52 ; c ; <base64> BEL
    size_t encoded_len = ((strlen(text) + 2) / 3) * 4;
    char *encoded = malloc(encoded_len + 1);
    base64_encode(text, encoded);

    printf("]52;c;%s", encoded);
    fflush(stdout);

    free(encoded);
}

// Alternative: Use system commands
void copy_to_clipboard_command(const char *text) {
#ifdef __APPLE__
    FILE *pipe = popen("pbcopy", "w");
#else
    FILE *pipe = popen("xclip -selection clipboard", "w");
#endif
    if (pipe) {
        fwrite(text, 1, strlen(text), pipe);
        pclose(pipe);
    }
}

Books That Will Help

Topic	Book	Chapter
Copy mode fundamentals	“tmux 3: Productive Mouse-Free Development”	Ch. 4: Working with Text and Buffers
Vi keybindings and navigation	“Practical Vim, 2nd Edition”	Ch. 1-3: The Vim Way
Circular buffers	“Data Structures the Fun Way”	Ch. 5: Queues and Circular Buffers
Text selection algorithms	“Programming Pearls”	Ch. 9: Code Tuning
Terminal escape sequences	“ANSI Escape Sequences” (VT100.net)	Reference documentation
Clipboard integration (OSC 52)	“Xterm Control Sequences”	OSC section
Pattern matching/search	“The Practice of Programming”	Ch. 9: Notation
State machines for modes	“Design Patterns”	Ch. 5: State Pattern

Project 13: Configuration and Key Bindings

File: DEEP_UNDERSTANDING_TMUX_PROJECTS.md
Main Programming Language: C
Alternative Programming Languages: Rust, Python
Coolness Level: Level 3: Genuinely Clever
Business Potential: 3. The “Service & Support” Model
Difficulty: Level 3: Advanced
Knowledge Area: Parsing / Configuration
Software or Tool: tmux
Main Book: “Language Implementation Patterns” by Terence Parr

What you’ll build: A configuration file parser (like .tmux.conf) that sets options and key bindings.

Why it teaches tmux fundamentals: tmux is highly configurable. Understanding how it parses and applies configuration teaches you about option systems and command languages.

Core challenges you’ll face:

Config file parsing (line-by-line, command syntax) → maps to tmux source-file
Option system (get/set options with types) → maps to tmux set-option, show-options
Key binding (map key sequences to commands) → maps to tmux bind-key
Prefix key handling (Ctrl-B by default, customizable) → maps to tmux prefix
Command execution (internal command language) → maps to tmux command prompt

Key Concepts:

Config Parsing: “Language Implementation Patterns” Chapter 2 - Terence Parr
Command Pattern: “Design Patterns” Command Pattern - Gamma et al.
tmux Configuration: “tmux 3: Productive Mouse-Free Development” Chapter 2 - Brian P. Hogan

Difficulty: Advanced Time estimate: 1-2 weeks Prerequisites: Basic parsing skills, Project 11 completed

Real world outcome:

# ~/.muxrc
set-option -g prefix C-a
unbind-key C-b
bind-key C-a send-prefix

set-option -g status-style "bg=blue fg=white"
set-option -g history-limit 10000

bind-key | split-window -h
bind-key - split-window -v

# At runtime:
$ ./mux
# Ctrl-A is now the prefix
# | and - split panes
# Status bar is blue

$ Ctrl-A :  # command prompt
: set-option status-style "bg=red"
# Status bar turns red

Implementation Hints: Start with a simple line-oriented parser. Each line is a command with arguments. Implement a command table mapping command names to handler functions.

For key bindings, store a mapping from key sequence to command string. When a key is pressed after the prefix, look it up and execute the associated command.

Learning milestones:

Config file loads at startup → Parsing works
Options take effect → Option system works
Key bindings work → Binding system works
Command prompt works → Interactive commands work
Reload config works → Dynamic reconfiguration works

The Core Question You’re Answering

“How does tmux let me customize every aspect of its behavior through a simple text file? How can I remap any key to any command and change options on the fly?”

This is what makes tmux infinitely adaptable to different workflows. Understanding configuration parsing and command execution teaches you about creating user-friendly, scriptable systems. The config file is a domain-specific language (DSL), and the key binding system is a command dispatcher—fundamental patterns in software design.

Concepts You Must Understand First

Stop and research these before coding:

What Is a Line-Oriented Parser?
- How do you parse a file line by line and handle comments?
- What’s the difference between tokenizing and parsing?
- How do you handle quoted strings with spaces (“bg=blue fg=white”)?
- How do you report useful error messages with line numbers?
- Book Reference: “Language Implementation Patterns” Ch. 2 - Terence Parr
Command Pattern Design
- What is the Command pattern and why is it useful?
- How do you represent a command as a data structure?
- How do you store command handlers in a function table?
- How do you pass arguments to commands of different types?
- Book Reference: “Design Patterns” Command Pattern - Gamma et al.
Type-Safe Option System
- How do you store options with different types (string, int, bool, color)?
- What’s a union type and when should you use it?
- How do you implement get/set operations with type checking?
- What’s the difference between session options and global options?
- Concept: This is like a mini key-value store with typed values
Key Binding Tables and Prefix Keys
- How do you represent a key sequence (Ctrl-B, then C)?
- What data structure should store key bindings efficiently?
- How do you distinguish between regular keys and special keys (arrow keys, function keys)?
- How does the prefix key mechanism work (two-stage key handling)?
- Reference: Study tmux key-bindings.c and vim’s key mapping system
Dynamic Command Execution
- How do you parse a command string at runtime?
- How do you look up a command by name and execute it?
- How do you handle command aliases?
- How do you implement an interactive command prompt (: in tmux)?
- Concept: This is a mini interpreter for your command language

Questions to Guide Your Design

Before implementing, think through these:

Config File Format
- What should a line of config look like? (command arg1 arg2 arg3)
- How do you handle comments? (Lines starting with #)
- How do you handle long commands that span multiple lines?
- Should you support variable substitution or keep it simple?
Command Registry
- How do you register all available commands?
- What information does each command need? (Name, handler function, argument count)
- How do you handle commands with variable arguments?
- How do you implement command abbreviations (set vs set-option)?
Option Storage
- Where do you store options in memory?
- How do you organize global vs session vs window options?
- How do you handle option inheritance (session inherits from global)?
- What happens when you query an option that isn’t set?
Key Binding Execution
- When a key is pressed, how do you know if it’s a prefix?
- If it’s after a prefix, how do you look up the binding?
- What if the bound command is a string? (Parse and execute it)
- How do you implement send-prefix (send literal prefix key)?
Error Handling
- What happens if the config file has a syntax error?
- Should you stop processing or skip the bad line?
- How do you report errors from the command prompt?
- How do you validate option values (e.g., history-limit must be positive)?

Thinking Exercise

Design the config parser and command system on paper:

Config file (.muxrc):
    # This is a comment
    set-option -g prefix C-a
    unbind-key C-b
    bind-key C-a send-prefix
    bind-key | split-window -h
    set-option -g history-limit 10000

Parser reads line by line:
    1. Skip lines starting with #
    2. Split line into tokens (respect quotes)
    3. First token is command name
    4. Remaining tokens are arguments
    5. Look up command in command table
    6. Call command handler with arguments

Command table:
    "set-option"  → cmd_set_option(args)
    "bind-key"    → cmd_bind_key(args)
    "unbind-key"  → cmd_unbind_key(args)
    "split-window" → cmd_split_window(args)
    ...

Option storage:
    struct Option {
        char *name;
        OptionType type;  // STRING, INT, BOOL, COLOR
        union {
            char *string_value;
            int int_value;
            bool bool_value;
            Color color_value;
        } value;
    };

    // Hash table or linked list
    Option global_options[MAX_OPTIONS];
    Option session_options[MAX_SESSIONS][MAX_OPTIONS];

Key binding storage:
    struct KeyBinding {
        int key;           // e.g., 'c', '|', or KEY_ARROW_LEFT
        char *command;     // e.g., "new-window" or "split-window -h"
    };

    KeyBinding bindings[MAX_BINDINGS];
    int prefix_key = CTRL('b');  // Default, configurable

Key press handling:
    if (key == prefix_key) {
        // Set "expecting command key" state
        in_prefix_mode = true;
    } else if (in_prefix_mode) {
        // Look up binding for this key
        KeyBinding *binding = find_binding(key);
        if (binding) {
            execute_command(binding->command);
        }
        in_prefix_mode = false;
    } else {
        // Regular key, send to PTY
        write(pty_master, &key, 1);
    }

Now trace what happens when:

Config file has: bind-key c new-window
Parser calls: cmd_bind_key(["c", "new-window"])
Handler stores: bindings[n] = {key: 'c', command: "new-window"}
User presses: Ctrl-B, then C
System looks up: binding for ‘c’ → finds “new-window”
System executes: execute_command("new-window")

The Interview Questions They’ll Ask

Prepare to answer these:

“How would you design a configuration file parser that’s both flexible and easy to debug?”
“What’s the Command pattern and how would you use it in a terminal multiplexer?”
“How do you implement a type-safe option system in C?”
“What data structure would you use to store key bindings and why?”
“How does tmux handle the prefix key mechanism? What states are involved?”
“How would you implement command aliases or abbreviations?”
“What’s the difference between parsing at startup vs executing commands at runtime?”
“How do you handle error reporting in a config file parser?”
“How would you implement option inheritance (session options inherit from global)?”
“How would you design a command prompt that can execute any command interactively?”

Hints in Layers

Only read these if you’re stuck. Try each step yourself first.

Hint 1: Simple Line Parser with Tokenization

// Read config file line by line
FILE *f = fopen(".muxrc", "r");
char line[1024];
int line_num = 0;

while (fgets(line, sizeof(line), f)) {
    line_num++;

    // Skip comments and empty lines
    char *p = line;
    while (isspace(*p)) p++;
    if (*p == '#' || *p == '\0') continue;

    // Tokenize the line
    char *tokens[MAX_TOKENS];
    int token_count = tokenize(line, tokens);

    if (token_count == 0) continue;

    // First token is command name
    char *cmd_name = tokens[0];

    // Look up and execute command
    if (!execute_command(cmd_name, token_count - 1, &tokens[1])) {
        fprintf(stderr, "Error on line %d: unknown command '%s'\n",
                line_num, cmd_name);
    }
}

Hint 2: Command Table with Function Pointers

typedef int (*CommandHandler)(int argc, char **argv);

typedef struct {
    const char *name;
    CommandHandler handler;
    int min_args;
    int max_args;
} Command;

Command command_table[] = {
    {"set-option",    cmd_set_option,    2, 3},  // set-option [-g] name value
    {"bind-key",      cmd_bind_key,      2, -1}, // bind-key key command...
    {"unbind-key",    cmd_unbind_key,    1, 1},  // unbind-key key
    {"split-window",  cmd_split_window,  0, 2},  // split-window [-h|-v]
    {"new-window",    cmd_new_window,    0, 1},  // new-window [name]
    {NULL, NULL, 0, 0}
};

int execute_command(const char *name, int argc, char **argv) {
    for (Command *cmd = command_table; cmd->name != NULL; cmd++) {
        if (strcmp(cmd->name, name) == 0) {
            if (argc < cmd->min_args) {
                fprintf(stderr, "Too few arguments for %s\n", name);
                return 0;
            }
            return cmd->handler(argc, argv);
        }
    }
    return 0;  // Command not found
}

Hint 3: Type-Safe Option System

typedef enum {
    OPTION_STRING,
    OPTION_INT,
    OPTION_BOOL,
    OPTION_COLOR,
} OptionType;

typedef struct {
    char name[64];
    OptionType type;
    union {
        char *string_val;
        int int_val;
        bool bool_val;
        struct {
            uint8_t r, g, b;
        } color_val;
    } value;
    bool is_set;
} Option;

Option global_options[MAX_OPTIONS];
int num_global_options = 0;

void set_option(const char *name, OptionType type, const void *value) {
    // Find or create option
    Option *opt = find_option(global_options, &num_global_options, name);
    if (!opt) {
        opt = &global_options[num_global_options++];
        strncpy(opt->name, name, sizeof(opt->name));
    }

    opt->type = type;
    opt->is_set = true;

    switch (type) {
        case OPTION_STRING:
            opt->value.string_val = strdup((const char *)value);
            break;
        case OPTION_INT:
            opt->value.int_val = *(const int *)value;
            break;
        case OPTION_BOOL:
            opt->value.bool_val = *(const bool *)value;
            break;
        // ... handle other types
    }
}

int cmd_set_option(int argc, char **argv) {
    // set-option [-g] name value
    bool global = false;
    int arg_idx = 0;

    if (strcmp(argv[0], "-g") == 0) {
        global = true;
        arg_idx = 1;
    }

    const char *name = argv[arg_idx];
    const char *value = argv[arg_idx + 1];

    // Parse value based on option name
    if (strcmp(name, "history-limit") == 0) {
        int val = atoi(value);
        set_option(name, OPTION_INT, &val);
    } else if (strcmp(name, "prefix") == 0) {
        // Parse key like "C-a" or "C-b"
        set_option(name, OPTION_STRING, value);
    }
    // ... handle other options

    return 1;
}

Hint 4: Key Binding Table and Prefix Handling

typedef struct {
    int key;           // Key code (e.g., 'c', '|', CTRL('c'))
    char command[256]; // Command to execute
    bool is_bound;
} KeyBinding;

KeyBinding key_bindings[256];  // One per possible key
int prefix_key = CTRL('b');    // Default prefix
bool in_prefix_mode = false;

// Parse key notation like "C-a" or "C-b"
int parse_key(const char *str) {
    if (strncmp(str, "C-", 2) == 0) {
        return CTRL(str[2]);
    }
    return str[0];
}

int cmd_bind_key(int argc, char **argv) {
    // bind-key key command [args...]
    int key = parse_key(argv[0]);

    // Build command string from remaining arguments
    char cmd[256] = {0};
    for (int i = 1; i < argc; i++) {
        strcat(cmd, argv[i]);
        if (i < argc - 1) strcat(cmd, " ");
    }

    key_bindings[key].key = key;
    strncpy(key_bindings[key].command, cmd, sizeof(key_bindings[key].command));
    key_bindings[key].is_bound = true;

    return 1;
}

void handle_key_press(int key) {
    if (key == prefix_key) {
        in_prefix_mode = true;
        // Show prefix indicator in status line
        update_status_line("prefix");
    } else if (in_prefix_mode) {
        in_prefix_mode = false;

        if (key_bindings[key].is_bound) {
            // Execute the bound command
            execute_command_string(key_bindings[key].command);
        } else {
            // No binding, do nothing or show error
        }
    } else {
        // Not in prefix mode, send key to PTY
        write(pty_master, &key, 1);
    }
}

Hint 5: Interactive Command Prompt

// When user presses prefix + ':' (command prompt)
void enter_command_prompt() {
    // Display prompt at bottom of screen
    char cmd_buffer[256] = {0};
    int cursor_pos = 0;

    while (1) {
        // Display: ":cmd_buffer_"
        display_command_prompt(cmd_buffer, cursor_pos);

        int key = read_key();

        if (key == '\n' || key == '\r') {
            // Execute command
            execute_command_string(cmd_buffer);
            break;
        } else if (key == 27) {  // ESC
            // Cancel
            break;
        } else if (key == 127 || key == '\b') {  // Backspace
            if (cursor_pos > 0) {
                cmd_buffer[--cursor_pos] = '\0';
            }
        } else if (isprint(key)) {
            cmd_buffer[cursor_pos++] = key;
            cmd_buffer[cursor_pos] = '\0';
        }
    }

    // Clear command prompt, redraw screen
    redraw_screen();
}

void execute_command_string(const char *cmd_str) {
    // Parse command string into tokens
    char *tokens[MAX_TOKENS];
    int token_count = tokenize(strdup(cmd_str), tokens);

    if (token_count > 0) {
        execute_command(tokens[0], token_count - 1, &tokens[1]);
    }
}

Books That Will Help

Topic	Book	Chapter
Lexical analysis and parsing	“Language Implementation Patterns”	Ch. 2: Basic Parsing Patterns
Command pattern	“Design Patterns”	Command Pattern
String tokenization	“The C Programming Language”	Ch. 5: Pointers and Arrays
Hash tables for options	“The C Programming Language”	Ch. 6: Structures
Key mapping systems	“Learning the vi and Vim Editors”	Ch. 10: Vim Customization
Configuration file design	“The Practice of Programming”	Ch. 9: Notation
tmux configuration	“tmux 3: Productive Mouse-Free Development”	Ch. 2: Configuring tmux
Error reporting in parsers	“Language Implementation Patterns”	Ch. 3: Enhanced Parsing Patterns

Project 14: Plugin System or Hooks

File: DEEP_UNDERSTANDING_TMUX_PROJECTS.md
Main Programming Language: C
Alternative Programming Languages: Rust, Lua (for scripting)
Coolness Level: Level 4: Hardcore Tech Flex
Business Potential: 4. The “Open Core” Infrastructure
Difficulty: Level 4: Expert
Knowledge Area: Plugin Architecture / Scripting
Software or Tool: tmux / vim
Main Book: “Language Implementation Patterns” by Terence Parr

What you’ll build: A hook system that runs commands on events (session created, window closed, etc.) or a plugin system with embedded scripting (Lua, Python).

Why it teaches tmux fundamentals: This is how tmux’s ecosystem (plugins like tmux-resurrect, tmux-continuum) works. It also teaches extensibility patterns.

Core challenges you’ll face:

Event system (what events to expose?) → maps to tmux hooks
Hook registration (when X happens, run Y) → maps to tmux set-hook
External command execution (run shell commands, capture output) → maps to tmux run-shell
Embedded scripting (optional: embed Lua/Python) → maps to plugin architectures
Stability (plugins shouldn’t crash the server) → maps to isolation

Key Concepts:

Event-Driven Design: “Design Patterns” Observer Pattern - Gamma et al.
Plugin Architectures: Study vim’s plugin model, or embed Lua (like Neovim)
tmux Hooks: tmux Wiki - Advanced Use - tmux project

Difficulty: Expert Time estimate: 2-3 weeks Prerequisites: Project 13 completed

Real world outcome:

# In config:
set-hook -g session-created 'display-message "Welcome to session #{session_name}!"'
set-hook -g pane-died 'respawn-pane'

# Or with Lua scripting:
lua <<EOF
mux.on("window-created", function(win)
  win:rename(os.date("%H:%M"))
end)
EOF

# When you create a session, you see the welcome message
# When a pane's process exits, it auto-respawns

Implementation Hints: Start with a simple hook system: a list of (event, command) pairs. When an event occurs, iterate through the list and execute matching commands.

For embedded scripting, start simple—maybe just run-shell to execute external scripts. Full embedding of Lua or Python is a significant undertaking but very educational.

Learning milestones:

Basic hooks work → Event system works
Multiple hooks per event work → Registration is flexible
run-shell captures output → External integration works
Hooks can modify state → Bidirectional integration works
(Optional) Embedded scripting works → Full extensibility achieved

The Core Question You’re Answering

“How can a program be extended by users without recompiling? How do you let external code run in response to events while keeping the main program stable?”

This is the essence of plugin systems. Vim, Emacs, web browsers, and tmux all solve this: they define events that trigger user-defined actions. Understanding this teaches you the Observer pattern, event-driven architectures, and how to safely execute external code. It’s the difference between a rigid tool and an extensible platform.

Concepts You Must Understand First

Stop and research these before coding:

The Observer Pattern (Event System)
- What is the relationship between an event and its observers?
- How do you register callbacks for events?
- What happens when an event fires—who gets called and in what order?
- How do you unregister a callback?
- Book Reference: “Design Patterns” Observer Pattern - Gamma et al.
Event-Driven Architecture
- What IS an event? (A notification that something happened)
- What’s the difference between synchronous and asynchronous events?
- Should event handlers run before or after the action completes?
- What if an event handler fails—should it stop other handlers?
- Book Reference: “Design Patterns” Ch. 5 - Gamma et al.
External Command Execution
- How do you spawn a child process and run a shell command?
- What’s the difference between system(), popen(), and fork()/exec()?
- How do you capture the output of an external command?
- How do you handle command failures or timeouts?
- Book Reference: “Advanced Programming in the UNIX Environment” Ch. 8 - W. Richard Stevens
Process Isolation and Stability
- How do you prevent a plugin crash from crashing your main program?
- What happens if a hook runs forever (infinite loop)?
- Should hooks run in the same process or a separate process?
- How do you limit resource usage (CPU, memory) of external code?
- Book Reference: “The Linux Programming Interface” Ch. 26 - Michael Kerrisk
Embedded Scripting (Optional)
- What’s the difference between running external scripts and embedding an interpreter?
- Why would you embed Lua instead of Python? (Size, sandboxing, simplicity)
- How does Neovim embed Lua? (Study the luajit FFI)
- What’s the API surface—what functions do you expose to scripts?
- Book Reference: “Programming in Lua” Ch. 26-28 - Roberto Ierusalimschy

Questions to Guide Your Design

Before implementing, think through these:

Event Definition
- What events should you expose? (session-created, window-closed, pane-died, etc.)
- How do you name events? (strings like “session-created” or enums?)
- Can events have parameters? (e.g., “pane-died” with pane ID)
- Should you support wildcard events? (e.g., “window-*” matches all window events)
Hook Registration
- What’s the data structure for mapping events to callbacks?
- Can you have multiple hooks for the same event?
- In what order do hooks run? (FIFO? LIFO? Priority-based?)
- How do you store hook configuration persistently (in a config file)?
Hook Execution
- Should hooks run synchronously or asynchronously?
- What information is available to the hook? (current state, event parameters)
- Can a hook prevent the action from completing? (e.g., “before-window-close”)
- How do you implement timeouts for long-running hooks?
External Command Interface
- How do you parse shell commands from config (handling quotes, escaping)?
- Should you expand variables in commands? (e.g., #{session_name})
- How do you capture stdout/stderr from the command?
- What’s the working directory for hook commands?
Error Handling
- What happens if a hook command fails (non-zero exit)?
- Should you log hook execution (for debugging)?
- How do you prevent a bad hook from breaking the whole system?
- Should users get feedback when their hooks run?
Optional: Embedded Scripting
- Which language? (Lua is small and embeddable; Python is powerful but heavy)
- What’s the API? (mux.on(), mux.get_panes(), etc.)
- How do you sandbox scripts? (Prevent file I/O, network access, etc.)
- How do you handle script errors without crashing the server?

Thinking Exercise

Design the event system on paper before coding:

Event: "pane-died" (a pane's process exited)
Parameters: pane_id, exit_status

Registered Hooks:
1. Hook A: run-shell "notify-send 'Pane died'"
2. Hook B: run-shell "respawn-pane -t #{pane_id}"

Execution Flow:
1. Pane process exits
2. Server detects SIGCHLD or similar
3. Server fires "pane-died" event with pane_id=5, exit_status=0
4. Server looks up hooks for "pane-died"
5. Server runs Hook A:
   - Forks a child
   - Executes "notify-send 'Pane died'"
   - Waits for completion (or runs async?)
6. Server runs Hook B:
   - Expands #{pane_id} to "5"
   - Forks a child
   - Executes "respawn-pane -t 5"
7. All hooks complete
8. Server continues normal operation

Now trace a failure case:

What if Hook A takes 30 seconds?
What if Hook B tries to respawn a pane that no longer exists?
What if a hook enters an infinite loop?

The Interview Questions They’ll Ask

Prepare to answer these:

“What is the Observer pattern and how does it relate to event systems?”
“How would you implement a hook system that allows multiple callbacks per event?”
“What’s the difference between system(), popen(), and fork()/exec() for running external commands?”
“How do you capture the stdout of an external command in C?”
“How would you prevent a plugin from crashing your main program?”
“What are the trade-offs between synchronous and asynchronous hook execution?”
“How would you implement timeouts for long-running hooks?”
“What’s the advantage of embedding Lua versus running external scripts?”
“How do you safely expand variables in shell commands (e.g., #{session_name})?”
“Describe how tmux’s set-hook and run-shell commands work internally.”

Hints in Layers

Only read these if you’re stuck. Try each step yourself first.

Hint 1: Basic Hook Data Structure

typedef void (*hook_callback)(void *event_data);

typedef struct hook {
    char *event_name;
    char *command;  // Shell command to run
    struct hook *next;
} hook_t;

// Global list of hooks
hook_t *hooks_head = NULL;

void register_hook(const char *event, const char *command) {
    hook_t *h = malloc(sizeof(hook_t));
    h->event_name = strdup(event);
    h->command = strdup(command);
    h->next = hooks_head;
    hooks_head = h;
}

Hint 2: Event Firing

void fire_event(const char *event_name, void *event_data) {
    hook_t *h = hooks_head;
    while (h != NULL) {
        if (strcmp(h->event_name, event_name) == 0) {
            run_hook(h->command, event_data);
        }
        h = h->next;
    }
}

Hint 3: Running External Commands with popen()

void run_hook(const char *command, void *event_data) {
    // TODO: Expand variables in command (e.g., #{pane_id})

    FILE *fp = popen(command, "r");
    if (fp == NULL) {
        fprintf(stderr, "Hook failed: %s\n", command);
        return;
    }

    // Optionally capture output
    char line[256];
    while (fgets(line, sizeof(line), fp) != NULL) {
        // Do something with output (log it, display it, etc.)
    }

    int status = pclose(fp);
    if (status != 0) {
        fprintf(stderr, "Hook exited with status %d: %s\n", status, command);
    }
}

Hint 4: Variable Expansion

char *expand_variables(const char *template, session_t *session, pane_t *pane) {
    // Simple approach: use strstr() to find #{...} and replace
    // More robust: use a regex or state machine

    char *result = strdup(template);

    // Replace #{session_name} with actual session name
    char *pos = strstr(result, "#{session_name}");
    if (pos != NULL && session != NULL) {
        // ... string replacement logic ...
    }

    // Replace #{pane_id} with actual pane ID
    pos = strstr(result, "#{pane_id}");
    if (pos != NULL && pane != NULL) {
        // ... string replacement logic ...
    }

    return result;
}

Hint 5: Embedded Lua (Optional)

#include <lua.h>
#include <lauxlib.h>
#include <lualib.h>

lua_State *L;

// Initialize Lua
void init_lua() {
    L = luaL_newstate();
    luaL_openlibs(L);

    // Register your API
    lua_register(L, "mux_on", lua_mux_on);
    lua_register(L, "mux_get_panes", lua_mux_get_panes);
}

// Lua binding: mux.on(event, callback)
int lua_mux_on(lua_State *L) {
    const char *event = luaL_checkstring(L, 1);
    luaL_checktype(L, 2, LUA_TFUNCTION);

    // Store the callback in Lua registry
    int callback_ref = luaL_ref(L, LUA_REGISTRYINDEX);

    // Register the hook
    register_lua_hook(event, callback_ref);

    return 0;
}

// Fire a Lua hook
void fire_lua_hook(int callback_ref, void *event_data) {
    lua_rawgeti(L, LUA_REGISTRYINDEX, callback_ref);
    // Push event_data as Lua table
    lua_newtable(L);
    // ... populate table with event parameters ...
    lua_pcall(L, 1, 0, 0);  // Call the callback
}

Books That Will Help

Topic	Book	Chapter
Observer pattern	“Design Patterns”	Observer Pattern - Gamma et al.
Event-driven design	“Design Patterns”	Ch. 5: Behavioral Patterns - Gamma et al.
External command execution	“Advanced Programming in the UNIX Environment”	Ch. 8: Process Control - W. Richard Stevens
Pipes and popen()	“The Linux Programming Interface”	Ch. 44: Pipes and FIFOs - Michael Kerrisk
Process isolation	“The Linux Programming Interface”	Ch. 26: Monitoring Child Processes - Michael Kerrisk
String parsing and expansion	“Language Implementation Patterns”	Ch. 2-4 - Terence Parr
Embedded Lua	“Programming in Lua”	Ch. 26-28: The C API - Roberto Ierusalimschy
Plugin architectures	Study Vim/Neovim source code	plugin.c, runtime/lua/

Project 15: Mini-tmux from Scratch (Capstone)

File: DEEP_UNDERSTANDING_TMUX_PROJECTS.md
Main Programming Language: C
Alternative Programming Languages: Rust
Coolness Level: Level 5: Pure Magic (Super Cool)
Business Potential: 1. The “Resume Gold” (Educational/Personal Brand)
Difficulty: Level 5: Master
Knowledge Area: Systems Programming / Terminal Multiplexing
Software or Tool: tmux
Main Book: “Advanced Programming in the UNIX Environment” by W. Richard Stevens

What you’ll build: Starting from scratch (not from your previous projects), build a complete terminal multiplexer in one cohesive codebase. This is the integration test of everything you’ve learned.

Why it teaches tmux fundamentals: By building it all from scratch with proper architecture from the start, you’ll understand how all the pieces fit together. This is different from incrementally adding features.

Core challenges you’ll face:

Clean architecture (how to structure the codebase?) → maps to understanding tmux source
All previous challenges, integrated → maps to systems thinking
Performance (many panes, fast updates) → maps to production quality
Edge cases (weird terminals, Unicode, signals) → maps to robustness
Testing (how do you test a terminal multiplexer?) → maps to software engineering

Key Concepts:

All previous project concepts integrated
tmux Source Code: github.com/tmux/tmux - Read the actual code
mtm Reference: mtm - Micro Terminal Multiplexer - A minimal implementation

Difficulty: Master Time estimate: 1-2 months Prerequisites: All previous projects completed

Real World Outcome

When you complete this capstone project, you’ll have a fully functional terminal multiplexer that rivals tmux for basic workflows. Here’s exactly what you’ll see:

Starting your terminal multiplexer:

# Start the server and create a new session
$ ./mytmux new-session -s development

┌─────────────────────────────────────────────────────────────────────────┐
│ ~/projects $ _                                                          │
│                                                                         │
│                                                                         │
│                                                                         │
│                                                                         │
│                                                                         │
│                                                                         │
│                                                                         │
│                                                                         │
│                                                                         │
│                                                                         │
│                                                                         │
│                                                                         │
│                                                                         │
│                                                                         │
│                                                                         │
│                                                                         │
│                                                                         │
│                                                                         │
├─────────────────────────────────────────────────────────────────────────┤
│ [development] 0:bash*                            "hostname" 14:32 Dec-21│
└─────────────────────────────────────────────────────────────────────────┘

Splitting panes and running multiple processes:

# After pressing Ctrl-b % (vertical split) and Ctrl-b " (horizontal split)

┌────────────────────────────────┬────────────────────────────────────────┐
│ ~/projects $ vim main.c        │ ~/projects $ make && ./mytmux          │
│                                │ Compiling server.c...                  │
│ #include <stdio.h>             │ Compiling client.c...                  │
│ #include <stdlib.h>            │ Compiling screen.c...                  │
│ #include <sys/socket.h>        │ Linking mytmux...                      │
│                                │ Build successful!                      │
│ int main(int argc, char **argv)│                                        │
│ {                              │ ~/projects $ _                         │
│     // Initialize server       │                                        │
│                                ├────────────────────────────────────────┤
│                                │ ~/projects $ htop                      │
│                                │                                        │
│                                │   1  [████████████░░░░░░░░░░░░] 52.3%  │
│                                │   2  [██████████░░░░░░░░░░░░░░] 41.7%  │
│                                │   3  [████████░░░░░░░░░░░░░░░░] 33.2%  │
│                                │   4  [██████░░░░░░░░░░░░░░░░░░] 28.1%  │
│                                │                                        │
│                                │   PID USER     CPU% MEM%  COMMAND      │
│                                │  1234 douglas  12.3  1.2  vim          │
│                                │  1235 douglas   8.7  0.4  mytmux-serve │
├────────────────────────────────┴────────────────────────────────────────┤
│ [development] 0:vim  1:build  2:monitor*          "hostname" 14:45 Dec-21│
└─────────────────────────────────────────────────────────────────────────┘

Detaching and reattaching:

# Press Ctrl-b d to detach
$ ./mytmux detach
[detached from session development]

# Your terminal returns to normal shell
$

# Later, from ANY terminal (even SSH from another machine):
$ ./mytmux list-sessions
development: 3 windows (created Sat Dec 21 14:32:01 2024) [80x24]
backend: 2 windows (created Sat Dec 21 10:15:22 2024) [120x40]

$ ./mytmux attach -t development
# BOOM! You're back exactly where you left off, vim still open,
# htop still running, all three panes restored perfectly!

Copy mode with scrollback:

# Press Ctrl-b [ to enter copy mode
# Navigate with vi-like keys (h,j,k,l), search with /

┌─────────────────────────────────────────────────────────────────────────┐
│ [COPY MODE] Line 1247/5000                                              │
│                                                                         │
│ $ git log --oneline                                                     │
│ a1b2c3d Fix buffer overflow in screen.c                                 │
│ e4f5g6h Add Unicode support for wide characters                         │
│ i7j8k9l Implement copy-mode scrollback buffer        ← cursor here      │
│ m0n1o2p Refactor event loop for better performance                      │
│ q3r4s5t Add configuration file parsing                                  │
│                                                                         │
│ Press 'v' to start selection, 'y' to yank, 'q' to exit copy mode       │
├─────────────────────────────────────────────────────────────────────────┤
│ [development] 0:bash*           [COPY]            "hostname" 14:52 Dec-21│
└─────────────────────────────────────────────────────────────────────────┘

Configuration file in action:

# ~/.mytmuxrc content:
$ cat ~/.mytmuxrc
# Key bindings
bind-key C-a prefix          # Use Ctrl-a instead of Ctrl-b
bind-key | split-horizontal
bind-key - split-vertical

# Status bar customization
set status-bg colour235
set status-fg colour136
set status-left "[#S] "
set status-right "%H:%M %d-%b-%y"

# Enable mouse support
set mouse on

# Set scrollback limit
set history-limit 10000

$ ./mytmux new-session
# Your custom configuration is now active!

Window and session management:

$ ./mytmux list-windows
0: vim (1 panes) [80x24] [layout 1234,80x24,0,0]
1: build* (2 panes) [80x24] [layout 5678,80x24,0,0{40x24,0,0,40x24,41,0}]
2: monitor (1 panes) [80x24] [layout 9012,80x24,0,0]

$ ./mytmux list-panes
0: [80x12] [history 1247/10000]
1: [40x12] [history 523/10000] (active)
2: [40x12] [history 89/10000]

$ ./mytmux send-keys -t development:0.0 "make clean && make" Enter
# Commands executed in pane 0 of window 0, even from outside the session!

What makes this YOUR creation:

Every keystroke is processed by YOUR input parser
Every ANSI escape sequence is rendered by YOUR screen buffer
Every pane layout is calculated by YOUR layout engine
Every session persists through YOUR Unix socket protocol
Every configuration option is parsed by YOUR config system
Every line of scrollback is managed by YOUR copy mode

You can literally strace your own terminal multiplexer and understand EVERY system call it makes!

The Core Question You’re Answering

“How do all the pieces of a terminal multiplexer fit together into one cohesive, production-quality system?”

This capstone isn’t about learning new concepts—you’ve already learned them in projects 1-14. This is about integration, architecture, and systems thinking. It’s about answering:

How do PTYs, sockets, event loops, and terminal rendering work together?
What data structures elegantly represent sessions, windows, and panes?
How do you design a protocol between client and server?
How do you handle ALL the edge cases simultaneously?
What does “production quality” really mean for systems software?

The real question you’re answering is: “Can I think like a systems programmer?”

Concepts You Must Understand First

Stop and verify you truly understand these before starting:

Pseudo-Terminals (PTYs)
- Can you explain the master/slave PTY relationship without hesitation?
- Do you understand why forkpty() exists and what it does atomically?
- Can you debug PTY issues using strace and ls -la /dev/pts/?
- Book Reference: “The Linux Programming Interface” Ch. 64 - Michael Kerrisk
Unix Domain Sockets
- Can you design a protocol for client-server communication?
- Do you understand sendmsg()/recvmsg() for passing file descriptors?
- How does connection multiplexing work with accept()?
- Book Reference: “The Linux Programming Interface” Ch. 57 - Michael Kerrisk
Event-Driven I/O
- Can you explain the difference between select(), poll(), and epoll()?
- Do you understand edge-triggered vs. level-triggered events?
- How do you handle partial reads/writes without blocking?
- Book Reference: “The Linux Programming Interface” Ch. 63 - Michael Kerrisk
Terminal I/O and ANSI Escape Sequences
- Can you parse arbitrary ANSI sequences including CSI, OSC, and DCS?
- Do you understand terminal modes (raw, cbreak, cooked)?
- How does the alternate screen buffer work?
- Book Reference: “The Linux Programming Interface” Ch. 62 - Michael Kerrisk
Signal Handling in Complex Systems
- Can you explain signal safety and what functions are async-signal-safe?
- How do you handle SIGWINCH for terminal resize?
- How do signals interact with your event loop?
- Book Reference: “Advanced Programming in the UNIX Environment” Ch. 10 - Stevens
Process Management
- Can you properly fork, exec, and reap child processes?
- Do you understand process groups, sessions, and controlling terminals?
- How does job control (Ctrl-Z, fg, bg) work?
- Book Reference: “Advanced Programming in the UNIX Environment” Ch. 9 - Stevens
Data Structures for Hierarchical State
- How do you model the session → window → pane hierarchy?
- What data structures support efficient layout recalculation?
- How do you handle deletion and reordering efficiently?
Software Architecture
- What is separation of concerns in systems programming?
- How do you design clean interfaces between modules?
- What patterns does tmux use that you should adopt?

Questions to Guide Your Design

Before writing any code, answer these architectural questions:

Data Structures
- What fields does a struct session need?
- What fields does a struct window need?
- What fields does a struct pane need?
- How are these linked together? (pointers, IDs, both?)
- How do you handle deletion without dangling pointers?
Client-Server Protocol
- What messages can a client send to the server?
- What messages can the server send to the client?
- How do you serialize/deserialize these messages?
- What happens if a message is partially received?
- How do you handle multiple clients attached to the same session?
Event Loop Design
- What file descriptors need to be monitored?
- How do you prioritize different types of events?
- How do you handle timeouts (for status bar updates)?
- How do you avoid starvation?
Screen Buffer Architecture
- How do you represent a cell (character + attributes)?
- How do you handle wide characters (Unicode)?
- How do you track dirty regions for efficient redraw?
- How do you implement scrollback (ring buffer? linked list?)
Layout Algorithm
- How do you represent a layout tree?
- What’s the algorithm for splitting a pane?
- How do you resize all panes when the terminal resizes?
- How do you handle minimum pane sizes?
Configuration System
- What syntax will you use for the config file?
- How do you bind keys to commands?
- How do you set options?
- How do you reload configuration at runtime?
Testing Strategy
- How do you test PTY interaction?
- How do you test the rendering output?
- How do you test client-server communication?
- How do you simulate terminal resize?

Thinking Exercise

Before coding, complete this architectural design exercise:

Exercise 1: Draw the Component Diagram

On paper, draw boxes for each major component and arrows showing data flow:

┌─────────────┐          ┌─────────────┐
│   Client    │◄────────►│   Server    │
└──────┬──────┘  Socket  └──────┬──────┘
       │                        │
       │                        ▼
       │                 ┌─────────────┐
       │                 │ Session Mgr │
       │                 └──────┬──────┘
       │                        │
       ▼                        ▼
┌─────────────┐          ┌─────────────┐
│  Terminal   │          │   Windows   │
│  Renderer   │          │   & Panes   │
└─────────────┘          └──────┬──────┘
                                │
                                ▼
                         ┌─────────────┐
                         │    PTYs     │
                         └─────────────┘

Now expand this with MORE detail. Show every struct. Show every message type.

Exercise 2: Trace a Keystroke

Trace what happens when a user presses ‘a’ in a pane:

Terminal sends ‘a’ to client’s stdin
Client reads ‘a’ from stdin (which syscall?)
Client sends message to server (what message format?)
Server receives message (which syscall?)
Server identifies which pane is active
Server writes ‘a’ to pane’s PTY master (which syscall?)
Shell in pane reads ‘a’ from PTY slave
Shell echoes ‘a’ back to PTY slave
Server reads ‘a’ from PTY master
Server updates screen buffer
Server sends screen update to client
Client writes ANSI sequence to stdout
Terminal displays ‘a’

Write out EVERY step. If you can’t, you don’t understand the system yet.

Exercise 3: Design the Protocol

Write out your client-server protocol:

enum msg_type {
    MSG_IDENTIFY,       // Client → Server: who am I?
    MSG_ATTACH,         // Client → Server: attach to session
    MSG_DETACH,         // Client → Server: detach from session
    MSG_INPUT,          // Client → Server: keyboard input
    MSG_RESIZE,         // Client → Server: terminal resized
    MSG_SCREEN_UPDATE,  // Server → Client: new screen content
    MSG_STATUS_UPDATE,  // Server → Client: status bar changed
    MSG_EXIT,           // Server → Client: session terminated
    // ... what else?
};

struct msg_header {
    uint32_t type;
    uint32_t length;
    // ... what else?
};

Define EVERY message type your system will need.

Exercise 4: Study tmux Source

Before writing code, spend 2-3 days reading tmux source:

git clone https://github.com/tmux/tmux.git
cd tmux

# Start with these files:
less tmux.h          # Core data structures
less server.c        # Server main loop
less client.c        # Client main loop
less screen.c        # Screen buffer
less layout.c        # Pane layouts
less input.c         # Escape sequence parsing

For each file, answer:

What is this file responsible for?
What data structures does it define?
How does it interact with other files?

The Interview Questions They’ll Ask

After completing this capstone, you should be able to answer these confidently:

Architecture & Design:

“Walk me through the architecture of your terminal multiplexer.”
“How did you design the client-server protocol? What tradeoffs did you make?”
“How does your session hierarchy work? What data structures did you use?”
“How did you handle the case of multiple clients attached to the same session?”

Low-Level Systems:

“Explain exactly what happens when a user presses a key in your multiplexer.”
“How does your event loop work? Why did you choose select/poll/epoll?”
“How do you pass file descriptors between processes?”
“How do you handle terminal resize (SIGWINCH)?”

Terminal Specific:

“How does your ANSI escape sequence parser work? What edge cases did you handle?”
“How did you implement the scrollback buffer?”
“How do you handle Unicode and wide characters?”
“What’s the difference between the normal screen and alternate screen buffer?”

Software Engineering:

“How did you test your terminal multiplexer?”
“What was the hardest bug you encountered? How did you debug it?”
“If you had to rewrite this from scratch, what would you do differently?”
“How does your configuration system work?”

Production Quality:

“How did you handle memory management? Any leaks?”
“What’s the performance like with 100+ panes?”
“How robust is it against malformed input?”
“How does your error handling work?”

Hints in Layers

Hint 1: Start with Architecture, Not Code

Don’t write any code for the first week. Instead:

Draw every data structure
Define every message type
Map out every module
Read tmux source code

The biggest mistake is diving into code without a plan. You’ll end up rewriting everything.

Hint 2: Build the Skeleton First

Start with the absolute minimum:

// Day 1: Server that accepts connections
// Day 2: Client that connects
// Day 3: Server creates a PTY
// Day 4: Client sends input, server forwards to PTY
// Day 5: Server reads PTY output, sends to client
// Day 6: Client renders output to terminal

Get a SINGLE PANE working end-to-end before adding ANY features.

Hint 3: The mtm Reference Implementation

Study mtm - it’s only ~2000 lines:

git clone https://github.com/deadpixi/mtm.git
cd mtm
wc -l mtm.c  # About 2000 lines!

# Read it all - it's the minimal complete implementation

mtm proves you can build a working terminal multiplexer in ~2000 lines. Your first version should be similarly small.

Hint 4: Debug with Multiple Terminals

You’ll need multiple terminals to debug:

Terminal 1: Run your server (./mytmux-server)
Terminal 2: Run your client (./mytmux new-session)
Terminal 3: Watch server logs (tail -f /tmp/mytmux.log)
Terminal 4: strace the server (strace -p <pid>)
Terminal 5: strace the client (strace -p <pid>)

Hint 5: Use AddressSanitizer Religiously

Compile EVERY build with sanitizers:

CFLAGS="-fsanitize=address,undefined -g" make

# This will catch:
# - Buffer overflows
# - Use-after-free
# - Memory leaks
# - Undefined behavior

Hint 6: The Screen Buffer Trick

For the screen buffer, use a simple 2D array to start:

struct cell {
    uint32_t ch;        // Unicode codepoint
    uint16_t attr;      // Bold, underline, etc.
    uint8_t fg;         // Foreground color
    uint8_t bg;         // Background color
};

struct screen {
    struct cell *cells; // width * height cells
    int width;
    int height;
    int cursor_x;
    int cursor_y;
};

// Access cell at (x, y):
#define CELL(s, x, y) ((s)->cells[(y) * (s)->width + (x)])

Hint 7: Event Loop Pattern

Here’s the core server event loop pattern:

while (running) {
    // Build poll set
    nfds = 0;
    fds[nfds++] = (struct pollfd){.fd = server_socket, .events = POLLIN};

    for (each client)
        fds[nfds++] = (struct pollfd){.fd = client->fd, .events = POLLIN};

    for (each pane)
        fds[nfds++] = (struct pollfd){.fd = pane->pty_master, .events = POLLIN};

    // Wait for events
    poll(fds, nfds, timeout_ms);

    // Handle each ready fd
    for (int i = 0; i < nfds; i++) {
        if (fds[i].revents & POLLIN) {
            if (fds[i].fd == server_socket)
                accept_new_client();
            else if (is_client_fd(fds[i].fd))
                handle_client_input();
            else if (is_pty_fd(fds[i].fd))
                handle_pty_output();
        }
    }
}

Hint 8: Configuration Parser Starting Point

For config parsing, start simple:

// Parse: "set option-name value"
// Parse: "bind-key key command"

char line[256];
while (fgets(line, sizeof(line), config_file)) {
    char *cmd = strtok(line, " \t\n");
    if (!cmd || cmd[0] == '#') continue;

    if (strcmp(cmd, "set") == 0) {
        char *option = strtok(NULL, " \t\n");
        char *value = strtok(NULL, "\n");
        set_option(option, value);
    } else if (strcmp(cmd, "bind-key") == 0) {
        char *key = strtok(NULL, " \t\n");
        char *action = strtok(NULL, "\n");
        bind_key(key, action);
    }
}

Books That Will Help

Topic	Book	Chapter
Complete Unix API reference	“The Linux Programming Interface” - Kerrisk	Entire book, esp. 57, 62-64
Process/session/terminal relationships	“Advanced Programming in the UNIX Environment” - Stevens	Ch. 9: Process Relationships
Signal handling in complex systems	“Advanced Programming in the UNIX Environment” - Stevens	Ch. 10: Signals
Terminal I/O fundamentals	“The Linux Programming Interface” - Kerrisk	Ch. 62: Terminals
Pseudo-terminals	“The Linux Programming Interface” - Kerrisk	Ch. 64: Pseudoterminals
IPC via sockets	“The Linux Programming Interface” - Kerrisk	Ch. 57: Sockets: Unix Domain
Event-driven I/O	“The Linux Programming Interface” - Kerrisk	Ch. 63: Alternative I/O Models
How tmux works (user perspective)	“tmux 3: Productive Mouse-Free Development” - Hogan	Entire book
Understanding the tmux architecture	“The Tao of tmux” - Tony Narlock	Ch. 1-5: Server, Sessions, Windows, Panes
C systems programming patterns	“C Interfaces and Implementations” - Hanson	Ch. 1-4: Data structures
Debugging systems code	“The Art of Debugging with GDB, DDD, and Eclipse” - Matloff	Ch. 1-5
Terminal emulator internals	“Xterm Control Sequences” (documentation)	Entire document
Event loop design	“libevent documentation”	Programming guide

Implementation Hints from tmux Source:

Study the actual tmux source code structure. Notice how it separates:

server.c - Server main loop
client.c - Client handling
screen.c - Screen buffer management
layout.c - Pane layout algorithms
cmd-*.c - Individual commands
input.c - Escape sequence parsing

Design your architecture before coding. Draw diagrams. Write down the protocol between client and server. Define your data structures for sessions, windows, and panes.

Learning milestones:

Basic client-server works → Foundation is solid
Single window works → Core multiplexing works
Pane splitting works → Layout management works
Detach/attach works → Session persistence works
Copy mode works → Advanced features work
Config file works → Customization works
It’s actually usable for daily work → You’ve built something real

Project Comparison Table

Project	Difficulty	Time	Depth of Understanding	Fun Factor
1. PTY Echo Chamber	Advanced	1 week	Core Unix primitive	★★★★☆
2. ANSI Escape Renderer	Intermediate-Advanced	1-2 weeks	Terminal internals	★★★☆☆
3. Unix Socket Chat	Intermediate	3-5 days	IPC fundamentals	★★★☆☆
4. Process Supervisor	Advanced	1 week	Process management	★★★★☆
5. Event-Driven I/O	Advanced	1-2 weeks	Async programming	★★★☆☆
6. Terminal UI Library	Advanced	1-2 weeks	TUI rendering	★★★★☆
7. Mini-Screen	Expert	2-3 weeks	Window multiplexing	★★★★★
8. Detach/Attach	Expert	2-3 weeks	Session persistence	★★★★★
9. Pane Splitting	Expert	3-4 weeks	Layout algorithms	★★★★★
10. Session Hierarchy	Expert	2-3 weeks	State management	★★★★☆
11. Status Bar	Advanced	1 week	UI polish	★★★☆☆
12. Copy Mode	Expert	2-3 weeks	Text handling	★★★★☆
13. Configuration	Advanced	1-2 weeks	Parsing/extensibility	★★★☆☆
14. Plugin System	Expert	2-3 weeks	Extensibility	★★★★☆
15. Mini-tmux (Capstone)	Master	1-2 months	Everything	★★★★★

Recommended Learning Path

If you’re new to systems programming:

Start with projects 1, 3, 4 in sequence. These teach the fundamental Unix primitives without the complexity of terminal rendering.

If you understand Unix basics but not terminals:

Start with projects 1, 2, 6. These focus on the terminal-specific aspects.

If you want the fastest path to understanding tmux:

Do projects 1, 3, 7, 8 in sequence. This gives you the core architecture in about 5-6 weeks.

If you want complete mastery:

Do all 15 projects. Budget 4-6 months. You’ll emerge with a deep understanding not just of tmux, but of Unix systems programming in general.

My recommendation for you:

Based on your interest in understanding tmux “from the beginning”, I recommend:

Start with Project 1 (PTY Echo Chamber) - This is the “aha!” moment. Once you understand PTYs, tmux makes sense.
Then Project 3 (Unix Socket Chat) - This explains how detach/attach is possible.
Then Project 7 (Mini-Screen) - Combine PTYs with multiple windows.
Then Project 8 (Detach/Attach) - Add the killer feature.
Finally, explore Projects 9-14 as your interest dictates.

Final Capstone Project: Complete Terminal Multiplexer

Following the same pattern above, here is the ultimate project that applies every concept:

Project: Full-Featured Terminal Multiplexer

File: DEEP_UNDERSTANDING_TMUX_PROJECTS.md
Main Programming Language: C
Alternative Programming Languages: Rust
Coolness Level: Level 5: Pure Magic (Super Cool)
Business Potential: 5. The “Industry Disruptor” (if you add unique features)
Difficulty: Level 5: Master
Knowledge Area: Systems Programming / Terminal Multiplexing
Software or Tool: tmux replacement
Main Book: “Advanced Programming in the UNIX Environment” by W. Richard Stevens

What you’ll build: A production-quality terminal multiplexer that you could actually use for your daily work, potentially with unique features that differentiate it from tmux.

Why it teaches everything: This is the culmination of all the Unix primitives, all the terminal knowledge, all the systems programming skills. Building something you’d actually use daily is the ultimate test.

Core challenges you’ll face:

Every challenge from all previous projects, plus:
Unicode handling (multi-width characters)
True color support (24-bit color)
Mouse support (clicks, scrolling, selection)
Clipboard integration (OSC 52, xclip, pbcopy)
Terminal compatibility (different TERM types)
Performance at scale (100+ panes)

Unique features you might add:

Integrated fuzzy finder (like fzf built-in)
Session templating (project-specific layouts)
Built-in SSH integration (connect to remote machines, sessions persist across SSH)
AI-powered command suggestions
Terminal recording and playback
Collaborative sessions (multiple users, same session, with cursor visibility)

Learning milestones:

It works on your machine → Basic functionality
It works on different terminals → Compatibility
You use it daily → It’s actually good
Others use it → It’s production quality
It has features tmux doesn’t → You’ve innovated

Essential Resources

Books (Priority Order)

“The Linux Programming Interface” by Michael Kerrisk - The Bible. Chapters 34, 57, 63, 64 are essential.
“Advanced Programming in the UNIX Environment” by W. Richard Stevens - Classic systems programming reference.
“tmux 3: Productive Mouse-Free Development” by Brian P. Hogan - For understanding tmux usage deeply.

Online Resources

tmux Source Code - The ultimate reference
mtm - Micro Terminal Multiplexer - A minimal implementation to study
The Tao of tmux - Understanding tmux architecture
ANSI Escape Sequences Gist - Essential reference
libevent Documentation - Event loop library tmux uses
pty(7) man page - PTY documentation
NCURSES Programming HOWTO - Terminal UI programming

Man Pages to Study

pty(7) - Pseudo-terminal overview
termios(3) - Terminal I/O
signal(7) - Signal handling
unix(7) - Unix domain sockets
select(2) / epoll(7) - I/O multiplexing
fork(2) / exec(3) - Process creation

Summary

#	Project	Main Language
1	PTY Echo Chamber	C
2	ANSI Escape Sequence Renderer	C
3	Unix Domain Socket Chat	C
4	Signal-Aware Process Supervisor	C
5	Event-Driven I/O Multiplexer	C
6	Terminal UI Library (Mini-ncurses)	C
7	Mini-Screen (Single-Window Multiplexer)	C
8	Detach/Attach Server Architecture	C
9	Pane Splitting and Layouts	C
10	Session and Window Hierarchy	C
11	Status Bar and Mode Rendering	C
12	Copy Mode and Scrollback	C
13	Configuration and Key Bindings	C
14	Plugin System or Hooks	C
15	Mini-tmux from Scratch (Capstone)	C
Final	Full-Featured Terminal Multiplexer	C

All projects are best done in C because:

tmux itself is written in C
The Unix APIs (PTY, signals, sockets) are C APIs
You’ll be reading tmux source code for reference
Systems programming in C gives you the deepest understanding

Rust is an excellent alternative if you prefer memory safety, but you’ll need to use libc bindings for the Unix primitives.