Deep Understanding of tmux: From Unix Primitives to Terminal Multiplexing

Goal: Build a working, mental-model level understanding of terminal multiplexing by recreating tmux from Unix primitives. You will learn how PTYs, termios, signals, sockets, and event loops compose into a resilient client-server system. You will also learn how terminal rendering, screen buffers, and layout trees work under real constraints. By the end, you will be able to implement a minimal tmux-like tool from scratch and explain every major feature with confidence.

Introduction

tmux is a terminal multiplexer: it lets you run and manage many terminal sessions inside a single terminal window and keep them running even when your network or terminal disconnects. It does this by placing a long-lived server between your terminal and the programs you run, using PTYs to simulate terminals and a small protocol to attach or detach clients.

What you will build (by the end of this guide):

A PTY proxy that logs and replays terminal I/O
A tiny ANSI escape sequence renderer
A Unix domain socket client-server protocol
An event-driven I/O multiplexer with a screen buffer
A minimal tmux-like tool with panes, sessions, and detach/attach

Scope (what is included):

Unix terminal primitives: PTYs, termios, signals, job control
Client-server architecture over Unix domain sockets
ANSI/VT terminal protocol parsing and rendering
Screen buffers, layouts, and status bars
Configuration and key bindings

Out of scope (for this guide):

Windows Console APIs or Windows Terminal internals
GPU-accelerated terminal emulators or GUI toolkit rendering
Networked multiplexer servers (beyond local sockets)

The Big Picture (Mental Model)

Keyboard/Terminal
      |
      v
+-------------+     Unix Socket      +------------------+
| tmux client | <------------------> | tmux server      |
+-------------+                      | - sessions       |
       |                              | - windows       |
       v                              | - panes         |
  ANSI output                         | - event loop    |
       |                              +--------+--------+
       v                                       |
  Your terminal                         PTY master fds
                                               |
                                               v
                                        +--------------+
                                        | PTY slaves   |
                                        | /dev/pts/*   |
                                        +------+-------+
                                               |
                                               v
                                         shells/programs

Key Terms You Will See Everywhere

PTY: A master/slave pseudo-terminal pair. Programs run on the slave as if it were a real terminal; tmux controls the master.
Session/Window/Pane: The hierarchy tmux uses to organize running programs.
Client/Server: tmux runs a server that owns state; clients are temporary views into that state.
Termios: The terminal settings API that controls raw/canonical mode, echo, and signal generation.
Escape sequence: Special byte sequences that move the cursor, set colors, and update the terminal.

How to Use This Guide

Read the Theory Primer first. It is the mini-book. Each chapter is a conceptual building block that the projects rely on.
Build projects in order. Each project adds a layer of capability and validates your understanding.
Keep a lab notebook. Write down what confused you, how you debugged it, and which syscalls you used.
Use real tools for verification. strace, lsof, script, and tmux -vv are your truth sources.
Iterate in layers. Make it work, then make it correct, then make it fast, then make it pleasant.

Prerequisites & Background Knowledge

Essential Prerequisites (Must Have)

Programming Skills:

C or Rust basics (functions, pointers or references, structs)
Comfort with the Unix API (open/read/write/close)
Basic data structures (arrays, linked lists, trees)

Unix Fundamentals:

File descriptors and process creation (fork, exec)
Basic signals and process lifecycle
Basic command line usage and shell scripting
Recommended Reading: “The Linux Programming Interface” by Michael Kerrisk - Ch. 4, 5, 6

Helpful But Not Required

Terminal Internals:

terminfo and termcap concepts
Can learn during: Projects 2, 6

Event Loops:

select/poll/epoll patterns
Can learn during: Project 5

Self-Assessment Questions

Can you explain what a file descriptor really is?
Can you write a simple program that forks and execs another process?
Do you understand what a controlling terminal is?
Can you describe the difference between blocking and non-blocking I/O?
Can you read and understand basic C structs and pointer usage?

If you answered “no” to questions 1-3, spend a week with basic Unix programming first.

Development Environment Setup

Required Tools:

A Linux or BSD system (Ubuntu 22.04+, Debian 12+, or macOS with Homebrew)
C compiler (clang or gcc)
make, pkg-config
tmux installed for reference

Recommended Tools:

strace or dtruss (syscall tracing)
gdb or lldb
script for recording terminal I/O
libevent development package

Testing Your Setup:

$ cc --version
$ tmux -V
$ pkg-config --libs libevent

Time Investment

Simple projects (1-3): 3-6 days each
Moderate projects (4-10): 1-2 weeks each
Complex projects (11-15): 2-4 weeks each
Total sprint: 3-5 months for deep mastery

Important Reality Check

tmux mastery is a multi-layer skill. Expect to re-read chapters and rebuild projects. Your first versions will be fragile. That is normal. The goal is to move from “it works” to “I can explain why it works and how it fails.”

Big Picture / Mental Model

Think of tmux as two planes:

Control Plane                          Data Plane
-----------------                      -------------------
Key bindings, commands                 Bytes in/out of PTYs
Session/window/pane state              ANSI escape sequences
Client-server protocol                 Screen buffer updates

               +----------------------------------+
               |              Server              |
               |  sessions -> windows -> panes    |
               |  protocol + event loop           |
               +-----------+--------------+--------+
                           |              |
                      Unix socket      PTY masters
                           |              |
                           v              v
                     tmux clients     running programs

If you can explain how these two planes interact, you understand the architecture.

Theory Primer (Read This Before Coding)

Chapter 1: Unix Terminal Foundations (PTYs, termios, job control)

Fundamentals

A terminal on Unix is not just a UI, it is a device with a driver and a set of rules for how bytes become keystrokes and how output is echoed. The core mental model is that terminals are file descriptors with special behavior. A PTY gives you a pair of file descriptors that behave like a terminal, so you can place a program between a user and the program they are running. This is the key primitive for multiplexing. The termios API lets you toggle line buffering, echo, and signal generation so you can control every keystroke. Job control uses process groups and a controlling terminal to decide who gets input and who receives signals like SIGINT when you press Ctrl-C. tmux uses all of these mechanics at once: it creates PTYs for panes, sets raw mode for input, and carefully manages process groups so your shells behave normally even when you are detached.

Deep Dive into the Concept

Start with the PTY. A pseudo-terminal is a master/slave pair. The slave side behaves like a real terminal device. A shell or program believes it is attached to a terminal when its stdin/stdout/stderr are connected to the slave. The master side is controlled by your program. When you write bytes to the master, they appear as input on the slave; when the program writes to the slave, your program reads those bytes from the master. That simple pair is enough to interpose, record, replay, or multiplex.

To make a program think the PTY slave is its controlling terminal, the child process needs to become a session leader and then acquire the PTY as its controlling terminal. This is done by calling setsid() and then opening the slave device, or explicitly using ioctl(TIOCSCTTY) if needed. The controlling terminal is the mechanism Unix uses for job control: the foreground process group gets keystrokes and signals. Without correct session and process group setup, Ctrl-C and Ctrl-Z will not behave, and background jobs might steal input.

Termios is the next layer. By default, terminals operate in canonical (cooked) mode: input is line buffered and processed by the line discipline. That means you do not receive keys immediately, and special characters generate signals. tmux needs to capture keys and interpret them, so it puts the client side into raw mode (disabling ICANON, ECHO, and ISIG) and then manually forwards bytes to the server. The server then writes the bytes into the PTY master for the selected pane, letting the program in the pane receive input as if it came from a real terminal.

Window sizing is also part of terminal state. Each PTY has a window size accessible via ioctl(TIOCGWINSZ) and set with ioctl(TIOCSWINSZ). When the client terminal resizes, tmux must propagate the new size to the PTY so programs like vim redraw correctly. This is usually coupled with SIGWINCH delivery to the foreground process group. If you do not propagate size changes, you will see broken rendering, truncated output, and inconsistent cursor positions.

Job control is subtle but critical. A shell expects to be in its own process group and to be the foreground group for its controlling terminal. When you run a program inside a pane, the shell may change process groups or stop itself. tmux must not break that logic. It lets the PTY and the kernel line discipline handle it, but it must ensure the session structure is correct. If you have ever seen a pane that ignores Ctrl-C or where job control does not work, the cause is usually incorrect session or controlling terminal setup.

Finally, remember that terminals are byte streams, not structured messages. When a program writes output, it may include control sequences. The PTY master sees those bytes exactly. tmux does not get a structured API for cursor positions or colors. It must parse, interpret, and translate those bytes itself. That means the core of tmux is not a UI toolkit, it is a low-level terminal stream processor backed by correct PTY and termios configuration.

How This Fits in the Projects

Project 1 builds the PTY proxy and teaches master/slave semantics.
Project 4 and 5 rely on correct signal and job control handling.
Projects 7-15 depend on accurate termios settings and window sizing.

Definitions and Key Terms

PTY: A pseudo-terminal pair (master/slave) used to emulate a real terminal.
Controlling terminal: The terminal associated with a session for job control and signal delivery.
Process group: A set of related processes that receive signals together.
Canonical mode: Line-buffered input with special key processing.
Raw mode: Input delivered byte-by-byte with minimal processing.
Line discipline: Kernel code that processes terminal input/output.

Mental Model Diagram

User keystrokes
     |
     v
[Client Terminal] --(raw bytes)--> [tmux client]
     |                                 |
     |                              Unix socket
     v                                 |
[tmux server] --(write)--> [PTY master] -> [PTY slave] -> [shell]

How It Works (Step-by-Step)

tmux server allocates a PTY master and gets the slave path.
Server forks a child, calls setsid(), opens the slave, and makes it the controlling terminal.
Child execs the shell; its stdin/out/err point to the PTY slave.
Client terminal is set to raw mode and forwards keystrokes to the server.
Server writes keystrokes to the PTY master.
Program output is read from the PTY master and rendered to clients.
Window size changes are propagated via ioctl(TIOCSWINSZ).

Minimal Concrete Example

int master = posix_openpt(O_RDWR | O_NOCTTY);
grantpt(master);
unlockpt(master);
char *slave = ptsname(master);

pid_t pid = fork();
if (pid == 0) {
    setsid();
    int sfd = open(slave, O_RDWR);
    ioctl(sfd, TIOCSCTTY, 0);
    dup2(sfd, 0); dup2(sfd, 1); dup2(sfd, 2);
    execlp("/bin/sh", "sh", NULL);
    _exit(1);
}

Common Misconceptions

“A PTY is just a pipe.” It is a terminal device with line discipline and window size.
“Raw mode is optional.” Without it, key handling and prefix keys break.
“Window size is only cosmetic.” It affects program layout and cursor state.

Check-Your-Understanding Questions

Why does the child call setsid() before opening the PTY slave?
What is the difference between canonical and raw mode?
How does Ctrl-C become SIGINT for the foreground process group?

Check-Your-Understanding Answers

setsid() creates a new session so the PTY can become the controlling terminal.
Canonical mode buffers and edits lines; raw mode delivers bytes immediately.
The line discipline detects the Ctrl-C byte and sends SIGINT to the foreground group.

Real-World Applications

Terminal emulators and remote shells
Expect scripts and automation tools
Debuggers and REPLs that require terminal control

Where You’ll Apply It

Projects 1, 4, 7, 8, 12, 15

References

https://man7.org/linux/man-pages/man7/pty.7.html
https://man7.org/linux/man-pages/man3/termios.3.html
https://man7.org/linux/man-pages/man7/signal.7.html
https://man7.org/linux/man-pages/man2/setsid.2.html

Key Insight

A PTY is the smallest possible “fake terminal” you can control; everything else is correct process and termios setup.

Summary

Terminal multiplexing is impossible without PTYs, termios, and job control. This chapter gives you the mechanical foundation for every other feature.

Homework/Exercises

Write a PTY program that runs /bin/cat and logs raw output.
Toggle raw mode on and off and observe how Ctrl-C behaves.
Manually change the window size and observe how stty -a changes.

Solutions to the Homework/Exercises

Use the PTY skeleton above, exec /bin/cat, and pipe input.
Set ICANON and ECHO flags to see the effect of cooked mode.
Use ioctl(TIOCSWINSZ) and then check stty -a in the child shell.

Chapter 2: Client-Server Architecture and IPC

Fundamentals

tmux is a client-server system. The server owns all state: sessions, windows, panes, and PTYs. Clients are just views. This separation is why tmux can survive disconnects: the server continues running even if every client disappears. Communication between client and server happens through a Unix domain socket, not a TCP socket, because the clients are local and need low-latency access and filesystem permissions. The core idea is that the client sends input and commands to the server, and the server sends back screen updates and status data. Everything else is a consequence of this design: attaching, detaching, listing sessions, and even renaming windows are protocol messages.

Deep Dive into the Concept

The tmux server is effectively a single authoritative process. It owns a graph of data structures: a set of sessions, each session contains windows, and each window contains panes. The server tracks which client is attached to which session, which window is active, and which pane is focused. Each client is a thin event loop that reads keyboard input, sends messages to the server, and renders screen updates.

In a client-server architecture, the key is the boundary. The client does not parse escape sequences from the program. The server does, because it owns the PTYs and sees the raw stream. That means the server must maintain a full screen model for each pane so it can send deltas to each client. If multiple clients attach to the same session, they all receive updates from the same screen state.

Unix domain sockets are used because they are fast, local, and have filesystem permissions. The socket path is typically under /tmp or a per-user directory. Access control becomes a simple file permission check. This is also why tmux can support multiple independent servers: each server listens on its own socket path. Clients choose the server by connecting to the right socket.

Designing the IPC protocol is where most student implementations fail. The protocol needs framing: each message should have a header with type and length so the receiver can parse it from a byte stream. You need message types for input, resize, attach, detach, list sessions, and screen updates. For screen updates, you must decide whether you send full frames or diffs. Full frames are easier but heavy; diffs are efficient but more complex. tmux uses a mix of shared buffers and optimized drawing to avoid redrawing whole screens.

Another subtle detail is how to represent commands. tmux has a full command language. When a client sends a command like new-window, the server parses it and runs a command handler. Your minimal implementation can support a smaller set of commands, but you still need an extensible dispatch mechanism. A common pattern is to map command strings to function pointers with metadata about arguments and flags.

Detach and attach are just messages. A detach message tells the server to stop sending updates to that client and to close the client connection. The session state is unchanged. An attach message registers a new client with a session and requests the current full screen state. This is why the server must keep screen buffers even when no clients are attached.

Security and isolation matter. Unix sockets inherit filesystem permissions, so a typical approach is to create the socket directory with 0700 and the socket with 0600. This makes attach operations a filesystem permission check. You also need to consider path length limits (about 108 bytes on Linux) and cleanup on crash. tmux supports multiple servers by letting clients select a socket name; your design should also allow distinct servers to coexist. For robustness, add a versioned protocol header so incompatible clients can refuse to attach. Finally, distinguish between a full snapshot message for new attaches and incremental updates for live clients, so your protocol remains efficient while still supporting reconnects.

How This Fits in the Projects

Project 3 builds the Unix socket foundation.
Project 8 introduces detach/attach.
Projects 10-15 build the full session/window/pane command model.

Definitions and Key Terms

Client: A process that renders server state and captures user input.
Server: A daemon that owns all sessions and PTYs.
Session: A named collection of windows.
Window: A collection of panes sharing layout.
Pane: A single terminal running a program.
IPC: Interprocess communication; here via Unix sockets.

Mental Model Diagram

Client A  ----\
Client B  ----->  [Unix socket]  -->  [Server state + PTYs]
Client C  ----/                    <--  [Screen updates]

How It Works (Step-by-Step)

Server creates a Unix domain socket and listens.
Client connects and sends an IDENTIFY or ATTACH message.
Server registers the client and sends the initial screen state.
Client sends INPUT and RESIZE messages.
Server writes input to PTYs, updates screen buffers, and broadcasts updates.
Client renders updates to its terminal.

Minimal Concrete Example

struct msg_hdr { uint32_t type; uint32_t len; };

// client sends input
struct msg_hdr h = { MSG_INPUT, n };
write(fd, &h, sizeof(h));
write(fd, bytes, n);

Common Misconceptions

“The client can parse output.” It cannot; only the server sees the PTY stream.
“Detach means kill.” Detach is just disconnect; state remains.
“Multiple clients is easy.” It requires shared screen state and fan-out.

Check-Your-Understanding Questions

Why is a Unix domain socket used instead of TCP?
What happens to the PTYs when all clients detach?
Why must the server keep screen buffers even with zero clients?

Check-Your-Understanding Answers

Clients are local; Unix sockets are faster and can use filesystem permissions.
The PTYs remain open because the server keeps them alive.
New clients need the current screen state for attach.

Real-World Applications

Daemons with local control clients
Local database servers with CLI clients
Debugging tools that attach/detach

Where You’ll Apply It

Projects 3, 8, 10, 13, 15

References

https://man7.org/linux/man-pages/man7/unix.7.html
https://man.openbsd.org/tmux
https://github.com/tmux/tmux

Key Insight

The server is the source of truth; clients are replaceable views.

Summary

Understanding tmux means understanding its client-server boundary and message protocol. Everything else is built on that boundary.

Homework/Exercises

Design a message header with type, length, and checksum.
Write a tiny client-server echo over a Unix domain socket.
Add a LIST command that returns active sessions.

Solutions to the Homework/Exercises

Use a 12-byte header: type, length, crc32.
Use socket(AF_UNIX, SOCK_STREAM, 0) and accept().
Maintain a list of session structs and serialize names into a response.

Chapter 3: Event-Driven I/O and Process Supervision

Fundamentals

tmux is an event-driven program. It must listen to many file descriptors at once: client sockets, PTY masters, and sometimes timers. This is impossible to handle with blocking I/O and a single loop unless you use I/O multiplexing like select, poll, or epoll. Event-driven design means you react to readiness events instead of waiting on one file descriptor at a time. This is what allows tmux to scale to many panes and clients without threads. It also makes timers and periodic updates (like status bars) easy to implement.

In practice, tmux also needs timers for status updates and key sequence timeouts. That means the loop is not just about I/O; it is about scheduling. A clean event loop keeps the server responsive even when one pane is noisy or a client is slow.

Deep Dive into the Concept

I/O multiplexing starts with readiness APIs. select and poll let you wait on multiple descriptors and see which are readable or writable. epoll improves scalability by avoiding O(n) scanning for large descriptor sets. tmux uses libevent to hide these platform differences. libevent provides a unified event loop with callbacks for I/O readiness and timers.

At the server level, every PTY master is a data source. When a program in a pane writes output, that output appears on the PTY master. The server must read it promptly, parse escape sequences, update the screen buffer, and then notify clients. Meanwhile, clients may send input messages or resize events. An event loop ensures none of these sources starve each other.

Process supervision is another aspect of event-driven design. Each pane runs a child process. When that process exits, the server receives SIGCHLD. The server must reap the child with waitpid, update pane state, and maybe display “[exited]”. If you ignore SIGCHLD, you leak zombies. tmux also reacts to SIGHUP (client disconnects) and SIGWINCH (terminal resize). The trick is to handle signals safely without performing complex logic inside signal handlers. A common pattern is to write to a self-pipe or eventfd and let the main loop process the signal in a safe context.

Timers are required for features like status bars and activity alerts. libevent lets you schedule timers that fire every N milliseconds. This is how tmux updates its status line clock without blocking I/O. Timers also help implement key sequence timeouts and double-prefix keybindings.

Backpressure is another critical concept. If a pane outputs data faster than clients can render, the server should not block on writes. Instead, buffer and send in chunks. If buffers grow too large, you might drop frames or throttle output. This is where a structured event loop and good buffer management become essential. Even in a “toy” tmux, you should think about what happens if a pane outputs 10 MB per second.

Finally, debugging event loops is a skill. You will need to log event registration, track which FD triggered a callback, and trace the sequence of events. This is why a minimal logging system is often built early. tmux itself has verbose logging modes that show event flow. Your projects should include a similar mechanism.

Buffering and backpressure are the hidden challenges. If a pane produces output faster than clients render, you must avoid blocking writes in the event loop. The safest pattern is to accumulate output in a per-client buffer and register an EV_WRITE callback only when the buffer is non-empty. If buffers grow without bound, you need a policy: drop frames, collapse repeated updates, or temporarily throttle the pane by pausing reads from its PTY. Many real multiplexers implement flow control by disabling EV_READ on a noisy PTY until the output backlog shrinks. This keeps the server responsive and prevents memory blowups.

Another practical concern is event prioritization. If both a client socket and a PTY are readable, which do you process first? A common strategy is to drain PTY output before processing new input so the screen stays consistent. In a small implementation, simple ordering is enough, but you should at least document the policy and make it deterministic so bugs are reproducible.

How This Fits in the Projects

Project 5 focuses on a clean event loop.
Projects 7-15 all use multiplexed I/O across PTYs and clients.

Definitions and Key Terms

Event loop: A loop that waits for I/O readiness and dispatches callbacks.
Non-blocking I/O: I/O that returns immediately instead of waiting.
SIGCHLD: Signal delivered when a child process exits.
libevent: A library that abstracts select/poll/epoll and timers.

Mental Model Diagram

+-------------------+
| Event loop         |
| - socket readable  |
| - pty readable     |
| - timer fired      |
+---------+----------+
          |
          v
  dispatch callbacks

How It Works (Step-by-Step)

Register client sockets and PTY masters with the event loop.
Register timers for status updates.
Wait for events.
When a PTY is readable, parse output and update screens.
When a client is readable, parse messages and apply actions.
When SIGCHLD is detected, reap the child and mark panes.

Minimal Concrete Example

struct event *ev = event_new(base, fd, EV_READ|EV_PERSIST, on_read, NULL);
event_add(ev, NULL);

Common Misconceptions

“One thread per pane is easier.” It scales poorly and complicates synchronization.
“Signals can do anything.” Signal handlers must be minimal and async-safe.

Check-Your-Understanding Questions

Why does non-blocking I/O matter for multiplexing?
How do you handle SIGCHLD without doing too much in the handler?
What is the difference between level-triggered and edge-triggered events?

Check-Your-Understanding Answers

You cannot afford to block on any single FD.
Use a self-pipe or flag and handle in the main loop.
Level triggers fire while data exists; edge triggers fire on transitions.

Real-World Applications

Network servers and proxies
UI event loops in terminal apps
Real-time log streaming tools

Where You’ll Apply It

Projects 4, 5, 7, 8, 11, 15

References

https://man7.org/linux/man-pages/man2/select.2.html
https://man7.org/linux/man-pages/man2/poll.2.html
https://man7.org/linux/man-pages/man7/epoll.7.html
https://libevent.org/

Key Insight

Multiplexing is the only scalable way to handle many PTYs and clients in one process.

Summary

The tmux server is an event-driven program. Without a robust event loop and correct signal handling, the entire system collapses under load or subtle failures.

Homework/Exercises

Build a poll-based loop that reads from stdin and a pipe.
Add a timer that fires every second and logs a heartbeat.
Implement a SIGCHLD handler that wakes the event loop.

Solutions to the Homework/Exercises

Use poll() with two descriptors and print which fired.
Use timerfd or libevent timeout events.
Write a byte to a self-pipe in the handler and watch for it in the loop.

Chapter 4: Terminal Protocol and ANSI/VT Parsing

Fundamentals

Programs do not call a terminal API. They write bytes that include control sequences. The terminal interprets those sequences to move the cursor, set colors, clear the screen, and switch modes. tmux must parse these sequences because it sits between programs and the terminal. That means tmux implements a terminal state machine. It consumes a byte stream and updates a screen model. This is one of the most subtle parts of tmux and a frequent source of bugs.

The protocol is stateful: a single byte can switch modes that change how all future bytes are interpreted. This is why a renderer must track modes like insert, origin, and alternate screen, not just characters on a grid.

Deep Dive into the Concept

The ANSI/VT protocol is a set of escape sequences, typically starting with ESC (0x1b). For example, ESC [ 2 J clears the screen, and ESC [ 31 m sets red foreground color. There are multiple classes: CSI sequences (ESC [), OSC sequences (ESC ]), and more. Each class has parameters, optional intermediates, and a final byte. This makes parsing tricky. The correct approach is a state machine with states like “ground”, “escape”, “CSI”, and “OSC”.

Terminals also have modes. The alternate screen buffer is an important one: full-screen programs like vim switch to the alternate buffer and later restore the main buffer. If tmux fails to track this mode, your scrollback and copy mode will be broken. Another mode is bracketed paste, which changes how pasted input is delivered. tmux must pass these sequences correctly to avoid breaking editors.

The terminal does not know about colors as names; it uses numeric codes. There are 8 color, 16 color, 256 color, and true color modes. ESC [ 38;2;R;G;B m sets true color. tmux needs to track foreground and background color attributes in its screen buffer. It also needs to know which attributes are active (bold, underline, inverse, etc.).

Terminfo is the database that maps logical capabilities to escape sequences for a given terminal type. tmux itself sets TERM=screen or TERM=tmux for panes because it emulates a terminal. The client terminal might be xterm, iTerm2, or Linux console. tmux must translate between what programs output and what the client expects. If you mis-handle terminfo capabilities, output might look wrong on some terminals.

Parsing has to be robust in the face of partial sequences. Because the stream is buffered, you might read half of an escape sequence, then the rest later. Your state machine must carry state across reads. You also must consider that some sequences are vendor-specific and can be ignored or passed through. tmux uses a tolerant parser: it recognizes known sequences, and it safely discards unknown ones without corrupting the screen model.

There are also entire classes of sequences beyond CSI. OSC sequences can set window titles or copy data to the clipboard (OSC 52). DEC private modes toggle behaviors like cursor visibility and alternate screen usage. Some sequences are intentionally vendor-specific and should be passed through. A robust parser therefore needs both strictness and tolerance: strictly implement the sequences you support, but discard or forward unknown ones without corrupting state. Testing with recorded logs from different applications is essential because many programs emit unusual sequences.

Testing parsers is easier when you generate sequences with tools like tput or when you record output from real programs. You will quickly see that some applications emit sequences like DECSET and DECRST (private mode set/reset) for cursor visibility, keypad modes, or mouse reporting. You do not have to implement all of them, but you must ignore them safely. The safest rule is: if you do not understand a sequence, do not mutate the screen state; just drop it or pass it through to the client.

How This Fits in the Projects

Project 2 builds a minimal ANSI parser.
Projects 6, 7, 11, 12 depend on correct rendering.

Definitions and Key Terms

ANSI escape sequence: A control sequence starting with ESC.
CSI: Control Sequence Introducer (ESC [).
OSC: Operating System Command (ESC ]).
Alternate screen: A separate screen buffer used by full-screen apps.
Terminfo: Database of terminal capabilities.

Mental Model Diagram

[PTY output bytes]
        |
        v
  Parser state machine
        |
        v
  Screen buffer updates
        |
        v
  Rendered ANSI for client

How It Works (Step-by-Step)

Read bytes from PTY master.
Feed bytes into a parser state machine.
Update cursor position and cell attributes.
Handle control sequences (clear, move, color).
Update screen buffer and mark dirty regions.
Render changes as ANSI sequences for clients.

Minimal Concrete Example

if (state == CSI) {
    if (is_final_byte(ch)) apply_csi(params, ch);
    else accumulate_param(ch);
}

Common Misconceptions

“Escape sequences are always complete in one read.” They are not.
“You can ignore alternate screen.” It breaks full-screen apps.

Check-Your-Understanding Questions

Why does tmux need its own parser instead of forwarding bytes?
What is the role of terminfo in tmux?
How do you handle partial escape sequences?

Check-Your-Understanding Answers

tmux needs a screen model to support multiple clients and copy mode.
terminfo maps capabilities to sequences for different terminals.
Use a persistent parser state machine across reads.

Real-World Applications

Terminal emulators
Log viewers with colored output
CLI dashboards and TUI apps

Where You’ll Apply It

Projects 2, 6, 7, 11, 12, 15

References

https://invisible-island.net/xterm/ctlseqs/ctlseqs.html
https://man7.org/linux/man-pages/man5/terminfo.5.html
https://man.openbsd.org/tmux

Key Insight

Terminal output is a protocol. You must parse it like any other protocol.

Summary

Escape sequence parsing is where tmux turns bytes into state. If your parser is wrong, everything else is wrong.

Homework/Exercises

Implement a parser that handles ESC [ H, ESC [ J, and color sequences.
Feed it a recorded ls --color=always output and verify colors.
Add a unit test for partial sequences across buffer boundaries.

Solutions to the Homework/Exercises

Implement a CSI state with parameter parsing.
Compare expected colors with actual screen buffer attributes.
Split the sequence across two reads and ensure the parser completes.

Chapter 5: Screen Buffers, Scrollback, and Layouts

Fundamentals

A terminal is a grid of cells, each holding a character and attributes. tmux must maintain an internal representation of that grid for every pane, plus a scrollback history. It cannot just forward bytes, because multiple clients may view the same pane or because the user might enter copy mode and scroll back. Layouts and panes are implemented as a tree of rectangular regions that map onto the screen grid. Status bars are just rows rendered on top or bottom of that grid. Understanding this model is critical for building a multiplexer that feels stable and correct.

A screen buffer is the source of truth, not a cached view. Layout is geometry: you are mapping many buffers into one composite rectangle while keeping borders and status lines consistent.

Deep Dive into the Concept

The screen buffer is typically represented as a 2D array of cells: each cell stores a Unicode codepoint, foreground and background colors, and attributes. When the cursor moves or text is printed, tmux updates these cells. If you simply redraw the entire screen on every update, it will be slow and flickery. Instead, track dirty regions or lines and only redraw the changes. This is why a “diff” between the old and new screen is useful: it reduces output and improves performance.

Scrollback is a separate buffer that stores lines that have scrolled off the visible screen. The simplest implementation is a ring buffer of lines. Each line is an array of cells. When the screen scrolls, the top line is pushed into history. Copy mode uses this history buffer, letting the user navigate lines not currently visible. Without a history buffer, copy mode cannot work.

Layouts introduce a geometric problem. You need to partition a rectangular area into sub-rectangles. tmux uses a layout tree: each internal node represents a split (horizontal or vertical), and each leaf node is a pane. When you split a pane, you replace a leaf with an internal node and two children. Resizing works by adjusting weights or sizes along the path. You must enforce minimum sizes to avoid rendering glitches.

Status bars and mode lines are just additional rows that are rendered separately but obey the same rendering rules. The status line itself is not a separate terminal. It is a row of text with attributes that tmux draws after rendering panes. This means the status line must be accounted for in layout calculations, and resize operations must subtract its height from pane heights.

Copy mode is a special rendering mode. Instead of rendering the live screen buffer, you render a view into the scrollback buffer with its own cursor. When the user selects text, tmux tracks a selection range and can copy it into a buffer. Modern tmux can integrate with the system clipboard via OSC 52 sequences; implementing that is an advanced exercise but understanding the selection model is required even for a minimal tool.

Unicode complicates rendering. Not every character is one cell wide; CJK characters are often double-width, and combining characters occupy zero width. You need a width function (such as wcwidth) and a policy for how to store multi-cell glyphs so cursor motion stays correct. Wrapping is also tricky: when a line wraps, the logical line may span multiple physical rows. Scrollback should store logical lines plus wrap metadata so copy mode selections do not split words unexpectedly. These details are what make the difference between “works” and “feels like tmux”.

Resizing introduces reflow. When the terminal width changes, you may need to rewrap lines in the scrollback buffer so the visual history still makes sense. tmux does this carefully to avoid losing content. For a smaller tool, you can choose a simpler approach: keep raw lines and accept that reflow is imperfect. But you should still document the behavior and keep it consistent so copy mode does not surprise users.

How This Fits in the Projects

Project 6 creates a basic TUI and screen buffer.
Projects 7, 9, 11, 12, and 15 build layouts, status bars, and copy mode.

Definitions and Key Terms

Cell: A character plus attributes at a grid position.
Scrollback: History of lines that have scrolled off the screen.
Layout tree: A tree of split nodes and pane leaves.
Dirty region: A portion of the screen that needs redraw.
Status line: A fixed row with metadata like time and session.

Mental Model Diagram

Screen
+----------------------------------+
| Pane A              | Pane B     |
| (grid of cells)     | (cells)    |
+----------------------------------+
| Status line (1 row)              |
+----------------------------------+

How It Works (Step-by-Step)

Maintain a grid of cells per pane.
Track cursor position and attributes.
When output arrives, update cells and mark dirty lines.
Maintain a ring buffer for scrollback.
Render panes into a composite screen.
Render status line last.

Minimal Concrete Example

struct cell { uint32_t ch; uint16_t attr; uint8_t fg, bg; };
struct screen { struct cell *cells; int w, h; };
#define CELL(s, x, y) ((s)->cells[(y)*(s)->w + (x)])

Common Misconceptions

“A pane is a separate terminal.” It is just a view into a buffer.
“Scrollback can be ignored.” Copy mode depends on it.

Check-Your-Understanding Questions

Why track dirty regions instead of full redraws?
How does a layout tree represent splits?
Why must the status line be accounted for in layout calculations?

Check-Your-Understanding Answers

It reduces output and avoids flicker.
Internal nodes are splits; leaves are panes.
It consumes screen rows, reducing pane height.

Real-World Applications

Terminal UIs and dashboards
Log viewers with scrollback
Multiplexed development environments

Where You’ll Apply It

Projects 6, 7, 9, 11, 12, 15

References

https://man.openbsd.org/tmux
https://invisible-island.net/xterm/ctlseqs/ctlseqs.html

Key Insight

Rendering is not printing; it is maintaining and updating a structured screen model.

Summary

To build tmux you must build a screen model, a layout model, and a render pipeline. These are the UI foundations of multiplexing.

Homework/Exercises

Implement a 2D screen buffer and render it to stdout.
Add a ring buffer for scrollback and expose a scroll command.
Implement a layout tree that supports vertical and horizontal splits.

Solutions to the Homework/Exercises

Use the cell struct and render each line with ANSI color resets.
Store a fixed number of lines and index with a ring pointer.
Represent splits as nodes with direction and two children.

Chapter 6: Configuration, Extensibility, and Persistence

Fundamentals

tmux is more than a multiplexer; it is a programmable environment. Configuration files let users define key bindings, status formats, and default behaviors. Extensibility comes from a command system that can be triggered by keys, scripts, or hooks. Persistence comes from the server model: state stays alive even when clients disconnect. Understanding how configuration and persistence interact is essential if you want to build a usable multiplexer rather than a demo.

Configuration is the user-facing API of your multiplexer. Persistence is the promise that your environment survives mistakes and disconnects. If either is weak, the tool will feel unreliable regardless of technical elegance.

Deep Dive into the Concept

A configuration system starts with parsing. tmux uses a simple command language, with commands like set, bind-key, and new-window. Your implementation can start with a line-based parser that splits tokens and dispatches commands. The key is to treat configuration as a stream of commands, not a special case. That means the same command dispatch logic can be used for both config files and user key presses.

Key bindings are usually implemented with key tables. Each table maps a key sequence to a command. tmux has a default table and a prefix table. When you press the prefix key, tmux switches to a new key table for the next key. That is how C-b followed by c becomes “new window”. This design is simple but powerful and worth replicating.

Extensibility can be achieved with hooks or plugins. A hook is a command that runs when an event occurs, like “after-new-window” or “client-attached”. A plugin system can be as simple as a directory of scripts that receive environment variables. You do not need a complex shared library system to gain extensibility; just a clear event model and a way to run commands safely.

Persistence has two forms: runtime persistence and configuration persistence. Runtime persistence means the server holds state in memory and does not exit when clients disconnect. Configuration persistence means user preferences are applied on startup and can be reloaded at runtime. A good multiplexer allows source-file or reload commands so users can update configuration without restarting the server.

Resilience is the final piece. When the client disconnects unexpectedly (SIGHUP, network drop, terminal crash), the server should keep running. When the client reconnects, it should receive the current screen state. That implies that the server must store full screen buffers, cursor positions, and layout state for every pane even when no client is attached. It also implies that the server must be careful with cleanup: it should not kill panes just because a client disappears.

Configuration is often layered: a system config, a user config, and sometimes a session-specific config. Reloading must be atomic so a partially parsed file does not leave the server in a corrupted state. If you add plugins or hooks, you are executing external code, so you must define trust boundaries and timeouts. A safe design is to run hooks in child processes, enforce a time limit, and sanitize environment variables. Persistence can also be extended by saving session state to disk (window names, layouts, running commands). Even if you do not implement disk save, design your in-memory state so it could be serialized later.

Error reporting is part of configuration design. Users need to know which line failed and why. A good pattern is to store file name and line number with each parsed command and to log parse errors without crashing the server. When reloading, apply changes in a temporary state object, then swap it in only if parsing succeeds. This makes configuration changes safe and predictable.

How This Fits in the Projects

Project 13 focuses on config parsing and key tables.
Project 14 introduces hooks and plugins.
Project 15 integrates persistence and reloadable config.

Definitions and Key Terms

Key table: A mapping of keys to commands, depending on context.
Command dispatch: The mechanism that maps commands to functions.
Hook: A command that runs on a lifecycle event.
Persistence: Keeping state alive after client disconnects.

Mental Model Diagram

Config file --> parser --> command dispatch --> state change
Key press  --> key table --> command dispatch --> state change

How It Works (Step-by-Step)

Parse config lines into tokens and commands.
Dispatch commands to handlers that mutate server state.
Maintain key tables and prefix logic.
On events, run hook commands.
Keep server running regardless of client connections.
When a client attaches, send full state snapshot.

Minimal Concrete Example

if (strcmp(cmd, "bind-key") == 0) {
    bind_key(table, key, action);
}

Common Misconceptions

“Config is a separate system.” It should reuse the command system.
“Detach implies cleanup.” The server must retain state.

Check-Your-Understanding Questions

Why use key tables instead of hard-coded bindings?
How can hooks improve extensibility without plugins?
What state must be preserved for proper attach?

Check-Your-Understanding Answers

They allow context-sensitive bindings and prefix logic.
Hooks let you run commands on lifecycle events.
Screen buffers, layout state, and active pane info.

Real-World Applications

Custom CLI environments
Automation and workflow tooling
Persistent development sessions

Where You’ll Apply It

Projects 13, 14, 15

References

https://man.openbsd.org/tmux
https://github.com/tmux/tmux

Key Insight

A multiplexer becomes useful only when users can configure and persist it.

Summary

Configuration and persistence turn a technical demo into a tool you can live in. This chapter gives you the patterns you need to do that cleanly.

Homework/Exercises

Write a parser that reads bind-key and set commands.
Implement a simple hook system for client-attached.
Add a reload-config command.

Solutions to the Homework/Exercises

Tokenize by whitespace and dispatch on the first token.
Maintain a list of hook commands and run them on events.
Re-run your parser on the config file and apply updates.

Glossary (High-Signal)

PTY: A pseudo-terminal pair that emulates a real terminal device.
Termios: The API controlling terminal modes and special keys.
Session: A collection of windows managed by a tmux server.
Window: A container for one or more panes.
Pane: A single terminal running a program.
Alternate screen: A separate screen buffer used by full-screen apps.
Unix domain socket: A local IPC endpoint represented by a filesystem path.
Event loop: The main loop that waits for I/O readiness and timers.
Key table: Context-specific mapping of keys to commands.
Scrollback: Stored output lines that have scrolled off screen.

Why tmux Matters

The Modern Problem It Solves

Remote work and long-running terminal sessions are the norm in systems engineering. tmux solves the fundamental pain of losing sessions on disconnects and provides a structured, scriptable environment for terminal work.

Real-world impact (recent data):

Homebrew usage (2025-01-01 to 2026-01-01): 304,893 installs on request, 0.32% of all formula installs. Source: https://formulae.brew.sh/api/analytics/install-on-request/365d.json
Open source adoption (2026-01-01): The tmux GitHub repository has 40,481 stars and 2,348 forks. Source: https://api.github.com/repos/tmux/tmux

Old workflow                          tmux workflow
-------------------------             -----------------------------
SSH -> shell -> run jobs              SSH -> tmux client -> server
(network drop kills shell)            (server keeps jobs running)

Context and Evolution (Brief)

GNU Screen (1980s) pioneered terminal multiplexing.
tmux (2007) modernized it with a cleaner architecture and a BSD license.
Today, tmux is embedded in developer workflows via tooling and dotfiles.

Concept Summary Table

Concept Cluster	What You Need to Internalize
Unix Terminal Foundations	PTYs, termios, controlling terminals, and job control are the mechanical core of multiplexing.
Client-Server Architecture and IPC	The server owns state; clients attach/detach via a local socket protocol.
Event-Driven I/O	Multiplexing requires non-blocking I/O and a robust event loop.
Terminal Protocol Parsing	ANSI/VT sequences are a protocol that must be parsed and modeled.
Screen Buffers and Layouts	A pane is a screen model; layouts map panes into rectangles with status bars.
Configuration and Persistence	Key tables, command dispatch, hooks, and long-lived servers make the tool usable.

Project-to-Concept Map

Project	What It Builds	Primer Chapters It Uses
Project 1: PTY Echo Chamber	PTY proxy and logging	1
Project 2: ANSI Escape Renderer	Minimal parser	4
Project 3: Unix Socket Chat	IPC foundation	2
Project 4: Process Supervisor	Signals and job control	1, 3
Project 5: Event-Driven I/O Multiplexer	Event loop	3
Project 6: Terminal UI Library	Screen buffer	4, 5
Project 7: Mini-Screen	Multiplexed panes	1, 2, 4, 5
Project 8: Detach/Attach	Client-server persistence	2, 6
Project 9: Pane Splitting	Layout tree	5
Project 10: Session Hierarchy	Sessions/windows model	2
Project 11: Status Bar	UI composition	5
Project 12: Copy Mode	Scrollback and selection	4, 5
Project 13: Config and Key Bindings	Command system	6
Project 14: Plugins/Hooks	Extensibility	6
Project 15: Mini-tmux	Full integration	1-6

Deep Dive Reading by Concept

Unix Terminal Foundations

Concept	Book & Chapter	Why This Matters
PTYs and controlling terminals	The Linux Programming Interface by Kerrisk - Ch. 64	Core PTY mechanics
Job control and sessions	The Linux Programming Interface - Ch. 34	Foreground group behavior
Terminal I/O	Advanced Programming in the UNIX Environment - Ch. 18	termios and line discipline

Client-Server Architecture and IPC

Concept	Book & Chapter	Why This Matters
Unix domain sockets	The Linux Programming Interface - Ch. 57	IPC for tmux clients
Daemons	Advanced Programming in the UNIX Environment - Ch. 13	Server lifecycle
Command design	Design Patterns - Command Pattern	Clean command dispatch

Event-Driven I/O and Rendering

Concept	Book & Chapter	Why This Matters
I/O multiplexing	The Linux Programming Interface - Ch. 63	Event loop foundations
Terminal control	The Linux Programming Interface - Ch. 62	Terminal capabilities
tmux usage patterns	tmux 3 by Brian P. Hogan - Ch. 1-6	User-level behavior

Screen Buffers and Layouts

Concept	Book & Chapter	Why This Matters
Screen buffers and redraw	tmux 3 by Brian P. Hogan - Ch. 2-3	Mental model of panes
Layout trees	Algorithms by Sedgewick - Trees	Pane split algorithms
Copy mode and scrollback	tmux 3 - Ch. 7	Text history and selection

Configuration and Persistence

Concept	Book & Chapter	Why This Matters
Command parsing	Language Implementation Patterns - Ch. 2-4	Config parser structure
Command dispatch	Design Patterns - Command Pattern	Key binding architecture
Automation and hooks	The Pragmatic Programmer - Ch. 8	Extensible workflows

Quick Start: Your First 48 Hours

Day 1 (4 hours):

Read Chapter 1 and Chapter 2 in the primer.
Skim the PTY code example and draw the data flow.
Start Project 1 and make the PTY proxy work.
Do not chase perfect logging yet.

Day 2 (4 hours):

Add raw mode handling to Project 1.
Record a session with script and compare the log.
Skim Chapter 4 and start Project 2.
Render only cursor movements and color resets.

End of Weekend: You will understand how tmux gets bytes from a shell and how those bytes become screen updates. That is the core mental model.

Recommended Learning Paths

Path 1: Systems Programming Beginner

Project 1 (PTY Echo Chamber)
Project 3 (Unix Socket Chat)
Project 4 (Process Supervisor)
Project 5 (Event-Driven I/O)
Project 7 (Mini-Screen)

Path 2: Terminal Internals Focus

Project 1
Project 2
Project 6
Project 12
Project 15

Path 3: Full Mastery (Completionist)

Do all projects in order. Budget 3-5 months.

Success Metrics

You can explain PTY master/slave semantics without notes.
You can describe the tmux client-server protocol in message types.
You can implement a basic ANSI parser and pass test logs.
You can run a multiplexer that survives client disconnects.
You can debug rendering glitches by inspecting the screen buffer.

Project Overview Table

Project	Deliverable	Difficulty	Time
1. PTY Echo Chamber	PTY proxy logger	Advanced	1 week
2. ANSI Escape Renderer	Minimal terminal parser	Advanced	1-2 weeks
3. Unix Socket Chat	IPC protocol demo	Intermediate	3-5 days
4. Process Supervisor	Signal-aware supervisor	Advanced	1 week
5. Event-Driven I/O Multiplexer	poll/libevent demo	Advanced	1 week
6. Terminal UI Library	Mini-ncurses	Advanced	1-2 weeks
7. Mini-Screen	Single-window multiplexer	Expert	2-3 weeks
8. Detach/Attach	Persistent server	Expert	2-3 weeks
9. Pane Splitting	Layout tree	Expert	2-3 weeks
10. Session Hierarchy	Session/window model	Expert	2 weeks
11. Status Bar	Status line renderer	Advanced	1 week
12. Copy Mode	Scrollback and selection	Expert	2 weeks
13. Config and Key Bindings	Config parser + key tables	Advanced	1-2 weeks
14. Plugins/Hooks	Extensibility system	Expert	2 weeks
15. Mini-tmux	Integrated multiplexer	Master	1-2 months

Project List

Project 1: PTY Echo Chamber

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

What you’ll build: A PTY proxy that runs a shell on a slave PTY, forwards input/output, and logs every byte to disk.

Real World Outcome

You will be able to type in a shell that looks normal while your program logs the exact raw byte stream.

Command Line Outcome Example:

$ ./pty_echo --log /tmp/pty.log
[pty] master=/dev/pts/3 slave=/dev/pts/4
[pty] child shell pid=4123

$ ls --color=always
bin  src  README.md

$ exit
[pty] child exited with status 0

$ head -n 3 /tmp/pty.log
ESC[?2004hESC[01;34mbinESC[0m ...

The Core Question You’re Answering

“How can a program sit between a shell and a terminal without either one knowing?”

Concepts You Must Understand First

PTY master/slave semantics
- Book Reference: “The Linux Programming Interface” Ch. 64
Controlling terminals and sessions
- Book Reference: “The Linux Programming Interface” Ch. 34
Raw vs canonical mode
- Book Reference: “Advanced Programming in the UNIX Environment” Ch. 18

Questions to Guide Your Design

How will you handle partial reads and writes on the PTY master?
Where will you store and rotate the log file?
How will you forward SIGWINCH to the child?

Thinking Exercise

Trace the byte path for a single keypress and identify every syscall involved.

The Interview Questions They’ll Ask

Why do you need setsid() for PTY children?
How does raw mode change input handling?
What happens if the child closes the PTY?

Hints in Layers

Hint 1: Use posix_openpt, grantpt, and unlockpt. Hint 2: The child must open the slave PTY after setsid(). Hint 3: Use select to forward bytes both directions.

Books That Will Help

Topic	Book	Chapter
PTYs	“The Linux Programming Interface”	Ch. 64
Termios	“Advanced Programming in the UNIX Environment”	Ch. 18

Common Pitfalls & Debugging

Problem: “Ctrl-C kills the proxy instead of the child”

Why: You did not put the client terminal in raw mode.
Fix: Disable ISIG or forward signals manually.

Definition of Done

Shell runs inside PTY
Input/output forwarded correctly
Raw bytes logged to disk
SIGWINCH resize propagated

Project 2: ANSI Escape Sequence Renderer

Main Programming Language: C
Coolness Level: Level 3: Terminal Whisperer
Business Potential: 1. The “Developer Tooling”
Alternative Programming Languages: Rust, Go
Difficulty: Level 3: Advanced
Knowledge Area: Terminal Rendering
Software or Tool: ANSI/VT parser
Main Book: “The Linux Programming Interface” by Michael Kerrisk

What you’ll build: A parser that consumes a log of terminal output and renders a screen buffer.

Real World Outcome

$ ./ansi_render --input /tmp/pty.log --cols 80 --rows 24
[render] parsed 12,342 bytes
[render] screen snapshot written to /tmp/frame.txt

$ sed -n '1,5p' /tmp/frame.txt
user@host:~/proj$ ls
bin  src  README.md

The Core Question You’re Answering

“How does a terminal turn raw bytes into cursor movement, colors, and text?”

Concepts You Must Understand First

Escape sequence structure
- Book Reference: “The Linux Programming Interface” Ch. 62
Screen buffer model
- Book Reference: “tmux 3” Ch. 2
State machine parsing
- Book Reference: “Language Implementation Patterns” Ch. 2-3

Questions to Guide Your Design

How will you represent a cell and attributes?
Which CSI sequences are required for basic rendering?
How will you handle partial sequences across buffers?

Thinking Exercise

Given ESC[2JESC[HHello, describe the final screen state.

The Interview Questions They’ll Ask

How does your parser handle unknown sequences?
What is the alternate screen and why does it matter?

Hints in Layers

Hint 1: Implement a simple state machine (ground, ESC, CSI). Hint 2: Start with H, J, and m sequences only. Hint 3: Store the cursor position in the screen struct.

Books That Will Help

Topic	Book	Chapter
Terminal control	“The Linux Programming Interface”	Ch. 62
tmux usage	“tmux 3”	Ch. 1-2

Common Pitfalls & Debugging

Problem: “Colors are wrong”

Why: You ignored m parameters or reset codes.
Fix: Track attributes per cell and handle ESC[0m.

Definition of Done

Basic cursor movement works
Colors render correctly
Partial sequences handled
Output matches a recorded session

Project 3: Unix Domain Socket Chat

Main Programming Language: C
Coolness Level: Level 2: IPC Apprentice
Business Potential: 1. The “Local Utility”
Alternative Programming Languages: Rust, Go, Python
Difficulty: Level 2: Intermediate
Knowledge Area: IPC
Software or Tool: Unix domain sockets
Main Book: “The Linux Programming Interface” by Michael Kerrisk

What you’ll build: A local chat server and client using AF_UNIX sockets.

Real World Outcome

$ ./uds_chatd --socket /tmp/chat.sock
[server] listening on /tmp/chat.sock

$ ./uds_chat --socket /tmp/chat.sock
chat> hello
[server] user1: hello

The Core Question You’re Answering

“How can two local processes communicate reliably without TCP?”

Concepts You Must Understand First

AF_UNIX sockets
- Book Reference: “The Linux Programming Interface” Ch. 57
Message framing
- Book Reference: “UNIX Network Programming” Ch. 4
Socket filesystem permissions
- Book Reference: “The Linux Programming Interface” Ch. 57

Questions to Guide Your Design

Will you use stream or datagram sockets?
How will you frame messages in a stream?
How do you handle client disconnects?

Thinking Exercise

Design a message header for chat messages and explain how to parse it.

The Interview Questions They’ll Ask

Why prefer Unix sockets over TCP for tmux?
How do you authenticate local clients?

Hints in Layers

Hint 1: Use SOCK_STREAM for ordered, reliable delivery. Hint 2: Prefix messages with a length field. Hint 3: Use unlink() on the socket path before binding.

Books That Will Help

Topic	Book	Chapter
Unix sockets	“The Linux Programming Interface”	Ch. 57
TCP framing patterns	“UNIX Network Programming”	Ch. 4

Common Pitfalls & Debugging

Problem: “bind() fails”

Why: Socket path already exists.
Fix: unlink(path) before bind().

Definition of Done

Server accepts multiple clients
Messages are broadcast
Clean shutdown removes socket file

Project 4: Signal-Aware Process Supervisor

Main Programming Language: C
Alternative Programming Languages: Rust, Go
Coolness Level: Level 3: Systems Hardening
Business Potential: 2. The “Ops Utility”
Difficulty: Level 3: Advanced
Knowledge Area: Process control
Software or Tool: signals, waitpid
Main Book: “Advanced Programming in the UNIX Environment” by W. Richard Stevens

What you’ll build: A supervisor that launches a child process, forwards signals, and restarts it on failure.

Real World Outcome

$ ./proc_supervisor -- ./long_task
[supervisor] child pid=5012
^C
[supervisor] forwarding SIGINT
[supervisor] child exited status=130
[supervisor] restarting...

The Core Question You’re Answering

“How do you manage child lifecycles and signals in a long-lived server?”

Concepts You Must Understand First

Signals and handlers - APUE Ch. 10
Process lifecycle - APUE Ch. 8
Process groups and job control
- Book Reference: “The Linux Programming Interface” Ch. 34

Questions to Guide Your Design

How do you avoid zombie processes?
How do you forward SIGINT to the child only?
Should the supervisor exit if the child crashes repeatedly?

Thinking Exercise

Write a state machine for supervisor states: running, crashed, restarting.

The Interview Questions They’ll Ask

What is the difference between SIGTERM and SIGKILL?
How do you reap a zombie?

Hints in Layers

Hint 1: Use waitpid(pid, &status, WNOHANG) in a loop. Hint 2: Use a signal handler to set a flag and wake your loop.

Books That Will Help

Topic	Book	Chapter
Signals	“Advanced Programming in the UNIX Environment”	Ch. 10
Process control	“Advanced Programming in the UNIX Environment”	Ch. 8

Common Pitfalls & Debugging

Problem: “Zombie processes”

Why: You never called waitpid.
Fix: Reap children in the event loop.

Definition of Done

Child restarts on crash
Signals forwarded correctly
No zombies after exit

Project 5: Event-Driven I/O Multiplexer

Main Programming Language: C
Alternative Programming Languages: Rust, Go
Coolness Level: Level 3: Event Loop Wizardry
Business Potential: 2. The “Core Library”
Difficulty: Level 3: Advanced
Knowledge Area: Event loops
Software or Tool: poll/select/libevent
Main Book: “The Linux Programming Interface” by Michael Kerrisk

What you’ll build: A small server that multiplexes I/O between multiple pipes and sockets.

Real World Outcome

$ ./io_mux --listen /tmp/mux.sock
[event] client connected fd=5
[event] pipe readable fd=7
[event] timer tick

The Core Question You’re Answering

“How do you scale to many concurrent I/O sources without threads?”

Concepts You Must Understand First

I/O multiplexing - TLPI Ch. 63
Non-blocking I/O - APUE Ch. 14
Non-blocking I/O
- Book Reference: “Advanced Programming in the UNIX Environment” Ch. 14

Questions to Guide Your Design

How do you represent registered events?
How do you avoid starvation among sources?

Thinking Exercise

Draw the sequence of events when two FDs become readable at once.

The Interview Questions They’ll Ask

When would you use poll vs epoll?
How do you implement timers in an event loop?

Hints in Layers

Hint 1: Start with poll for simplicity. Hint 2: Add a timer with timerfd or libevent.

Books That Will Help

Topic	Book	Chapter
I/O models	“The Linux Programming Interface”	Ch. 63

Common Pitfalls & Debugging

Problem: “Busy loop”

Why: You call poll with timeout 0.
Fix: Use a blocking timeout or a timer event.

Definition of Done

Multiple FDs handled without blocking
Timers fire consistently
Clean shutdown closes all FDs

Project 6: Terminal UI Library (Mini-ncurses)

Main Programming Language: C
Alternative Programming Languages: Rust, Go
Coolness Level: Level 4: UI Engineer
Business Potential: 2. The “Terminal Toolkit”
Difficulty: Level 3: Advanced
Knowledge Area: Terminal rendering
Software or Tool: ANSI renderer
Main Book: “The Linux Programming Interface” by Michael Kerrisk

What you’ll build: A tiny TUI library that draws boxes, text, and a status line.

Real World Outcome

$ ./tui_demo
+----------------------------+
|  CPU: 12%   MEM: 1.2G      |
|  Jobs: 3   Status: OK      |
+----------------------------+

The Core Question You’re Answering

“How do TUIs render consistently using only ANSI sequences?”

Concepts You Must Understand First

ANSI control sequences - TLPI Ch. 62
Screen buffer model - tmux 3 Ch. 2
Screen diffing and double buffering
- Book Reference: “tmux 3” Ch. 3

Questions to Guide Your Design

How do you avoid flicker?
How do you clear only dirty regions?

Thinking Exercise

Design a cell struct and draw a bordered box in your screen buffer.

The Interview Questions They’ll Ask

Why keep an off-screen buffer?
How do you handle resizing?

Hints in Layers

Hint 1: Maintain a buffer and diff before drawing. Hint 2: Use ESC[H and ESC[2J for full redraws at first.

Books That Will Help

Topic	Book	Chapter
Terminals	“The Linux Programming Interface”	Ch. 62
tmux usage	“tmux 3”	Ch. 3

Common Pitfalls & Debugging

Problem: “Screen flickers”

Why: Full redraw on every update.
Fix: Track dirty lines and redraw only them.

Definition of Done

Draw boxes and text
Status line updates
Resizes handled correctly

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

Main Programming Language: C
Alternative Programming Languages: Rust
Coolness Level: Level 5: Terminal Sorcery
Business Potential: 2. The “Power Tool”
Difficulty: Level 4: Expert
Knowledge Area: Multiplexing
Software or Tool: PTYs + screen buffer
Main Book: “The Linux Programming Interface” by Michael Kerrisk

What you’ll build: A minimal multiplexer with one window and multiple panes.

Real World Outcome

$ ./mini_screen
[mini] 2 panes running
pane0> htop
pane1> tail -f /var/log/syslog

The Core Question You’re Answering

“How do you multiplex multiple PTYs into one terminal?”

Concepts You Must Understand First

PTY I/O forwarding - TLPI Ch. 64
Screen buffer model - tmux 3 Ch. 2
Event loop design - TLPI Ch. 63

Questions to Guide Your Design

How will you merge two pane buffers into one screen?
How do you choose the focused pane for input?

Thinking Exercise

Draw the buffer layout for a split screen with two panes.

The Interview Questions They’ll Ask

How do you route input to the active pane?
How do you render two buffers into one terminal?

Hints in Layers

Hint 1: Start with fixed-size panes. Hint 2: Render each pane into a composite buffer.

Books That Will Help

Topic	Book	Chapter
PTYs	“The Linux Programming Interface”	Ch. 64
I/O multiplexing	“The Linux Programming Interface”	Ch. 63

Common Pitfalls & Debugging

Problem: “Pane output overlaps”

Why: You did not offset pane coordinates.
Fix: Add x/y offsets during render.

Definition of Done

Two panes render correctly
Input routes to active pane
Both panes run shells

Project 8: Detach/Attach Server Architecture

Main Programming Language: C
Alternative Programming Languages: Rust
Coolness Level: Level 5: Persistence Architect
Business Potential: 3. The “Infra Tool”
Difficulty: Level 4: Expert
Knowledge Area: Client-server
Software or Tool: Unix sockets
Main Book: “The Linux Programming Interface” by Michael Kerrisk

What you’ll build: A server that keeps panes alive while clients attach and detach.

Real World Outcome

$ ./mytmux-server --socket /tmp/mytmux.sock
[server] session created

$ ./mytmux attach -S /tmp/mytmux.sock
[client] attached
# detach with Ctrl-b d
[client] detached

$ ./mytmux attach -S /tmp/mytmux.sock
[client] reattached

The Core Question You’re Answering

“What state must survive when the client disappears?”

Concepts You Must Understand First

Unix sockets - TLPI Ch. 57
Client-server model - tmux 3 Ch. 1
Session state snapshots
- Book Reference: “tmux 3” Ch. 4

Questions to Guide Your Design

How will you serialize screen state to a new client?
How will you authenticate local clients?

Thinking Exercise

List all state that must persist across detach.

The Interview Questions They’ll Ask

What happens to the PTYs when no clients are attached?
How do you avoid losing screen state?

Hints in Layers

Hint 1: Keep the server running as a daemon. Hint 2: Store screen buffers in memory and re-send on attach.

Books That Will Help

Topic	Book	Chapter
Unix sockets	“The Linux Programming Interface”	Ch. 57
tmux usage	“tmux 3”	Ch. 4

Common Pitfalls & Debugging

Problem: “Attach shows blank screen”

Why: You did not store the screen buffer.
Fix: Keep the last frame per pane and send it on attach.

Definition of Done

Server keeps panes running
Attach shows current output
Multiple clients can attach

Project 9: Pane Splitting and Layouts

Main Programming Language: C
Alternative Programming Languages: Rust
Coolness Level: Level 4: Geometry Hacker
Business Potential: 2. The “Window Manager”
Difficulty: Level 4: Expert
Knowledge Area: Layout algorithms
Software or Tool: layout tree
Main Book: “The Linux Programming Interface” by Michael Kerrisk

What you’ll build: A layout tree that supports horizontal/vertical splits.

Real World Outcome

$ ./mytmux split -h
[layout] split pane 0 into panes 0 and 1

The Core Question You’re Answering

“How do you partition a rectangle into panes and keep it consistent on resize?”

Concepts You Must Understand First

Layout trees - design concept
Screen buffer composition - tmux 3 Ch. 3
Tree data structures
- Book Reference: “Algorithms” by Sedgewick - Trees

Questions to Guide Your Design

How do you store split ratios?
What is the minimum pane size?

Thinking Exercise

Draw a layout tree for three panes with one vertical split then one horizontal split.

The Interview Questions They’ll Ask

How do you resize all panes when the terminal resizes?
How do you represent splits in code?

Hints in Layers

Hint 1: Use a binary tree node with direction and two children. Hint 2: Store size ratios for each child.

Books That Will Help

Topic	Book	Chapter
Data structures	“Algorithms” by Sedgewick	Trees

Common Pitfalls & Debugging

Problem: “Pane size collapses”

Why: You did not enforce minimum sizes.
Fix: Clamp sizes and adjust sibling.

Definition of Done

Split and resize operations work
Layout persists across redraws

Project 10: Session and Window Hierarchy

Main Programming Language: C
Alternative Programming Languages: Rust
Coolness Level: Level 4: State Wrangler
Business Potential: 2. The “Session Manager”
Difficulty: Level 4: Expert
Knowledge Area: State management
Software or Tool: session model
Main Book: “tmux 3” by Brian P. Hogan

What you’ll build: A hierarchy of sessions and windows with basic commands.

Real World Outcome

$ ./mytmux new-session -s work
$ ./mytmux new-window -n logs
$ ./mytmux list-sessions
work: 2 windows

The Core Question You’re Answering

“How do you model sessions, windows, and panes as data?”

Concepts You Must Understand First

Client-server state model - tmux 3 Ch. 1
Data structures - linked lists or trees
List and map data structures
- Book Reference: “Algorithms” by Sedgewick - Lists and symbol tables

Questions to Guide Your Design

How do you index sessions and windows?
How do you choose the active window?

Thinking Exercise

Design the structs for Session, Window, and Pane.

The Interview Questions They’ll Ask

How do you handle deleting a window?
How do you keep multiple clients in sync?

Hints in Layers

Hint 1: Use a list of windows per session. Hint 2: Store a pointer to the active window.

Books That Will Help

Topic	Book	Chapter
tmux architecture	“tmux 3”	Ch. 1

Common Pitfalls & Debugging

Problem: “Active window lost”

Why: You removed it without updating active pointer.
Fix: Always update active window on deletion.

Definition of Done

Create/list/rename sessions
Create/switch windows
State consistent across clients

Project 11: Status Bar and Mode Rendering

Main Programming Language: C
Alternative Programming Languages: Rust, Go
Coolness Level: Level 3: UI Polish
Business Potential: 1. The “Quality of Life”
Difficulty: Level 3: Advanced
Knowledge Area: UI composition
Software or Tool: status line
Main Book: “tmux 3” by Brian P. Hogan

What you’ll build: A status bar that shows session name, time, and pane title.

Real World Outcome

$ ./mytmux
[status] [work] [pane:vim] [12:34]

The Core Question You’re Answering

“How do you render UI chrome without breaking pane content?”

Concepts You Must Understand First

Screen composition - tmux 3 Ch. 3
ANSI color rendering - TLPI Ch. 62
Timers in event loops
- Book Reference: “The Linux Programming Interface” Ch. 63

Questions to Guide Your Design

Where does the status line live in the screen grid?
How do you update it without flicker?

Thinking Exercise

Design a formatter for #{session_name} style tokens.

The Interview Questions They’ll Ask

How do you update the clock without redrawing panes?
How do you handle long status strings?

Hints in Layers

Hint 1: Render status into a single row buffer. Hint 2: Truncate or pad to terminal width.

Books That Will Help

Topic	Book	Chapter
tmux usage	“tmux 3”	Ch. 5

Common Pitfalls & Debugging

Problem: “Status overlaps panes”

Why: Layout height does not reserve row.
Fix: Subtract status height from pane layout.

Definition of Done

Status line renders consistently
Updates on timer
No flicker on updates

Project 12: Copy Mode and Scrollback

Main Programming Language: C
Alternative Programming Languages: Rust
Coolness Level: Level 4: Text Mechanic
Business Potential: 2. The “Power User Feature”
Difficulty: Level 4: Expert
Knowledge Area: Text handling
Software or Tool: scrollback buffer
Main Book: “tmux 3” by Brian P. Hogan

What you’ll build: A copy mode that navigates history and selects text.

Real World Outcome

$ ./mytmux copy-mode
[copy] cursor at line 1200
[copy] selection saved to buffer

The Core Question You’re Answering

“How do you let users navigate text that is no longer on screen?”

Concepts You Must Understand First

Scrollback buffers
Screen buffer diffing
Text selection and buffers
- Book Reference: “tmux 3” Ch. 7

Questions to Guide Your Design

How do you store history lines?
How do you map selection to copied text?

Thinking Exercise

Design a data structure for scrollback with fixed memory usage.

The Interview Questions They’ll Ask

How does copy mode differ from normal rendering?
How do you ensure selection across wrapped lines?

Hints in Layers

Hint 1: Use a ring buffer of line structs. Hint 2: Use a separate cursor for copy mode.

Books That Will Help

Topic	Book	Chapter
tmux usage	“tmux 3”	Ch. 7

Common Pitfalls & Debugging

Problem: “Selection jumps”

Why: Wrap handling inconsistent.
Fix: Store line wrap metadata.

Definition of Done

Scrollback persists
Copy mode cursor works
Text copied accurately

Project 13: Configuration and Key Bindings

Main Programming Language: C
Alternative Programming Languages: Rust, Go
Coolness Level: Level 3: Config Wizardry
Business Potential: 2. The “Workflow Booster”
Difficulty: Level 3: Advanced
Knowledge Area: Parsing and command dispatch
Software or Tool: config parser
Main Book: “tmux 3” by Brian P. Hogan

What you’ll build: A config file parser and key table system.

Real World Outcome

$ cat mytmux.conf
set -g prefix C-a
bind-key C-a send-prefix

$ ./mytmux -f mytmux.conf
[config] loaded 2 commands

The Core Question You’re Answering

“How can configuration reuse the same command system as interactive input?”

Concepts You Must Understand First

Command parsing
Key tables
Tokenization and quoting
- Book Reference: “Language Implementation Patterns” Ch. 2-4

Questions to Guide Your Design

How do you tokenize commands with quoted args?
How do you map key sequences to actions?

Thinking Exercise

Write a grammar for bind-key and set commands.

The Interview Questions They’ll Ask

How do you reload config safely?
How do you handle invalid commands?

Hints in Layers

Hint 1: Split by whitespace for v1, add quoting later. Hint 2: Store key bindings in a hash map.

Books That Will Help

Topic	Book	Chapter
Parsing patterns	“Language Implementation Patterns”	Ch. 2-4

Common Pitfalls & Debugging

Problem: “Bindings do nothing”

Why: You registered keys in the wrong table.
Fix: Verify prefix table vs root table.

Definition of Done

Config loads on startup
Key bindings trigger commands
Reload works without restart

Project 14: Plugin System or Hooks

Main Programming Language: C
Alternative Programming Languages: Rust, Go
Coolness Level: Level 4: Extensibility Architect
Business Potential: 2. The “Ecosystem Play”
Difficulty: Level 4: Expert
Knowledge Area: Extensibility
Software or Tool: hooks
Main Book: “The Pragmatic Programmer” by Thomas and Hunt

What you’ll build: A hook system that runs scripts on events.

Real World Outcome

$ ./mytmux hook add client-attached ./hooks/notify.sh
[hook] registered client-attached

The Core Question You’re Answering

“How do you let users extend behavior without modifying core code?”

Concepts You Must Understand First

Command dispatch
Process execution
Process execution and environment
- Book Reference: “Advanced Programming in the UNIX Environment” Ch. 8

Questions to Guide Your Design

How will hooks receive context (env vars)?
How do you avoid blocking the server when a hook runs?

Thinking Exercise

Design an event list and decide which events should be hookable.

The Interview Questions They’ll Ask

How do you sandbox hook execution?
What happens if a hook hangs?

Hints in Layers

Hint 1: Run hooks asynchronously. Hint 2: Use a timeout for hook processes.

Books That Will Help

Topic	Book	Chapter
Pragmatic automation	“The Pragmatic Programmer”	Ch. 8

Common Pitfalls & Debugging

Problem: “Hook blocks server”

Why: Hook runs in the main loop.
Fix: Fork and exec the hook process.

Definition of Done

Hooks trigger on events
Hooks run asynchronously
Server remains responsive

Project 15: Mini-tmux from Scratch (Capstone)

Main Programming Language: C
Alternative Programming Languages: Rust
Coolness Level: Level 5: Pure Multiplexing Magic
Business Potential: 3. The “Pro Tool”
Difficulty: Level 5: Master
Knowledge Area: Terminal multiplexing
Software or Tool: All components
Main Book: “Advanced Programming in the UNIX Environment” by W. Richard Stevens

What you’ll build: A usable minimal tmux clone with sessions, panes, status bar, detach/attach, and config.

Real World Outcome

$ ./mytmux new-session -s demo
# create panes, detach, reattach
$ ./mytmux attach -t demo
[client] attached to demo

The Core Question You’re Answering

“Can I integrate all primitives into a stable multiplexer?”

Concepts You Must Understand First

Everything from Chapters 1-6
tmux usage patterns
Debugging systems code
- Book Reference: “The Art of Debugging with GDB, DDD, and Eclipse” Ch. 1-3

Questions to Guide Your Design

What is the minimal set of features for daily use?
How will you test correctness under load?

Thinking Exercise

Write a staged roadmap from MVP to daily-driver quality.

The Interview Questions They’ll Ask

What was your hardest bug and how did you debug it?
How does your design differ from tmux?

Hints in Layers

Hint 1: Build a single-pane version first. Hint 2: Add panes, then status bar, then config. Hint 3: Use AddressSanitizer for every build.

Books That Will Help

Topic	Book	Chapter
Unix API	“The Linux Programming Interface”	Ch. 34, 57, 63, 64
tmux usage	“tmux 3”	Ch. 1-8

Common Pitfalls & Debugging

Problem: “Random hangs”

Why: Deadlock in event loop or blocking write.
Fix: Make all FDs non-blocking and log event flow.