DEV Community: Rodrigo Mello

Three Threads, One Terminal: Concurrency in Rust with Channels and Atomics

Rodrigo Mello — Mon, 30 Mar 2026 18:24:23 +0000

This is part of a series of posts about building b.roll, a terminal session recorder and search tool written in Rust. If you're just joining, here are the previous posts:

Building a 12-Command CLI in 120 Lines with clap Derive Macros

Spawning a PTY in Rust: How broll Captures Your Terminal Without You Noticing

When broll records a terminal session, three things need to happen at the same time: keystrokes must flow into the shell, the shell's output must appear on screen, and that output must be processed and stored in a database. Doing all three sequentially would mean dropped keystrokes and laggy rendering. So broll uses three threads, coordinated through channels and atomics.

This post walks through the concurrency architecture of broll's recorder, explaining each primitive: std::thread::spawn, mpsc channels, Arc, AtomicBool, AtomicU16, Ordering, move closures, and signal_hook for terminal resize handling. All code is from src/recorder/mod.rs.

The Three-Thread Architecture

Here is the layout:

                    +------------------+
 Real stdin ------> | Thread 1 (stdin) | ------> PTY master (writer)
                    +------------------+

                    +------------------+
 PTY master ------> | Main thread      | ------> Real stdout
   (reader)         | (PTY -> stdout)  | ------> mpsc channel (tx)
                    +------------------+

                    +------------------+
 mpsc channel ----> | Thread 2         | ------> SQLite (via Database)
   (rx)             | (storage)        |
                    +------------------+

Thread 1 (stdin) reads from the real terminal and writes to the PTY master, forwarding your keystrokes to the sub-shell.

Main thread reads from the PTY master and writes to the real terminal, displaying the shell's output. It also sends a copy of every chunk through an mpsc channel.

Thread 2 (storage) receives data from the channel, parses OSC markers, renders output through a VT100 virtual terminal, and stores the result in SQLite.

Spawning Threads with move Closures

Rust's std::thread::spawn takes a closure and runs it on a new OS thread. The catch: the closure must own everything it uses. Rust enforces this because threads can outlive the scope that created them, and borrowing data across thread boundaries would create data races.

The move keyword transfers ownership of captured variables into the closure. Here is the stdin thread:

let mut pty_writer = writer;
let _stdin_handle = std::thread::spawn(move || {
    let mut stdin = std::io::stdin();
    let mut buf = [0u8; 1024];
    loop {
        match stdin.read(&mut buf) {
            Ok(0) | Err(_) => break,
            Ok(n) => {
                if pty_writer.write_all(&buf[..n]).is_err() {
                    break;
                }
            }
        }
    }
});

Without move, the compiler would reject this code. The closure captures pty_writer, and Rust cannot guarantee the closure will not outlive the variable. With move, ownership of pty_writer transfers into the closure. The original scope can no longer access it, which eliminates any possibility of concurrent access.

The pattern Ok(0) | Err(_) => break handles both clean EOF and I/O errors in one arm. When stdin closes or the PTY writer breaks, the thread exits cleanly.

mpsc Channels: One Producer, One Consumer

The main thread and the storage thread communicate through an mpsc (multiple-producer, single-consumer) channel:

let (tx, rx) = mpsc::channel::<Vec<u8>>();

The main thread holds tx (the sender). The storage thread holds rx (the receiver). Each time the main thread reads a chunk from the PTY, it sends a copy through the channel:

// Main thread: PTY -> stdout + channel
match reader.read(&mut buf) {
    Ok(0) => break,
    Ok(n) => {
        let raw = &buf[..n];
        stdout.write_all(raw)?;
        stdout.flush()?;
        let _ = tx.send(raw.to_vec());
    }
    Err(_) => break,
}

The raw.to_vec() call creates an owned copy of the bytes. The main thread cannot send a reference because the buffer will be reused on the next read. The let _ = discards any send error, which only occurs if the receiver has been dropped (meaning the storage thread has exited).

On the receiving side, the storage thread uses recv_timeout instead of a blocking recv:

match rx.recv_timeout(INCOMPLETE_LINE_TIMEOUT) {
    Ok(data) => {
        // Process the data, parse markers, store chunks
    }
    Err(mpsc::RecvTimeoutError::Timeout) => {
        // Flush accumulated output that has not been terminated by a marker
    }
    Err(mpsc::RecvTimeoutError::Disconnected) => {
        // Channel closed, flush remaining data and exit
        break;
    }
}

The timeout (2 seconds) serves a practical purpose. Some commands produce output without a trailing newline or marker. Without a timeout, that partial output would sit in the buffer indefinitely. The timeout flushes it to the database so it does not get lost.

When the main thread finishes its loop, it drops tx:

drop(tx);

This causes the storage thread's next recv_timeout to return Disconnected, triggering a clean shutdown. This is the graceful teardown pattern for channel-based architectures: dropping the sender signals the receiver.

Arc: Shared Ownership Across Threads

Some state needs to be read by multiple threads. Rust's ownership model does not allow two threads to own the same value. Arc (Atomic Reference Counting) provides a solution: it wraps a value in a heap-allocated container with a thread-safe reference count. Cloning an Arc increments the count; dropping one decrements it. The inner value is freed when the count hits zero.

broll uses Arc for two things: the resize flag and the terminal column width.

let resize_flag = Arc::new(AtomicBool::new(false));
signal_hook::flag::register(signal_hook::consts::SIGWINCH, Arc::clone(&resize_flag))?;

let term_cols = Arc::new(AtomicU16::new(cols));
let term_cols_storage = Arc::clone(&term_cols);

Arc::clone does not clone the inner data. It creates a new pointer to the same allocation and increments the reference count. This is cheap: just an atomic increment.

Why Arc and Not Rc?

Rust has Rc (Reference Counting) for single-threaded shared ownership. It is slightly faster because it uses non-atomic operations. But Rc is not Send, meaning Rust will refuse to compile any code that tries to move an Rc to another thread. Arc uses atomic operations for its reference count, making it safe to share across threads. The compiler enforces this distinction at the type level.

Atomics: Lock-Free Shared State

Inside each Arc, broll uses atomic types rather than a Mutex. Atomics provide lock-free reads and writes for primitive values. No thread ever blocks waiting for another thread to release a lock.

AtomicBool for the Resize Flag

Terminal resize events arrive as SIGWINCH signals. The signal_hook crate registers a handler that sets an AtomicBool to true when the signal fires:

let resize_flag = Arc::new(AtomicBool::new(false));
signal_hook::flag::register(signal_hook::consts::SIGWINCH, Arc::clone(&resize_flag))?;

The main thread checks the flag on every loop iteration using swap:

if resize_flag.swap(false, Ordering::Relaxed)
    && let Ok((cols, rows)) = crossterm::terminal::size()
{
    term_cols.store(cols, Ordering::Relaxed);
    let _ = pair.master.resize(PtySize {
        rows,
        cols,
        pixel_width: 0,
        pixel_height: 0,
    });
}

swap(false, Ordering::Relaxed) atomically reads the current value and replaces it with false, returning the old value. If it was true, a resize happened. This pattern ensures that even if multiple SIGWINCH signals arrive between checks, the resize logic runs exactly once per check.

AtomicU16 for Terminal Width

The storage thread needs the current terminal width to render output correctly through its VT100 parser. The main thread updates this value on resize:

term_cols.store(cols, Ordering::Relaxed);

The storage thread reads it when rendering:

let rendered = render_vt(&cmd_output_bytes, term_cols_storage.load(Ordering::Relaxed));

What Does Ordering::Relaxed Mean?

Atomic operations take a memory ordering parameter that controls how they interact with surrounding memory operations. Ordering::Relaxed provides the weakest guarantee: the atomic operation itself is atomic, but it places no constraints on the ordering of other reads and writes.

For broll's use case, this is sufficient. The resize flag is a simple boolean signal where a missed update just means the resize happens on the next loop iteration. The column width is a hint for rendering, where using a slightly stale value produces output that is one render cycle behind. Neither case requires the stronger guarantees of Ordering::SeqCst or Ordering::Acquire/Release.

Signal Handling with signal_hook

Unix signals are tricky in any language. Signal handlers run in an interrupt context with severe restrictions on what they can do. The signal_hook crate provides a safe interface: instead of running arbitrary code in the handler, it simply sets an atomic flag.

signal_hook::flag::register(signal_hook::consts::SIGWINCH, Arc::clone(&resize_flag))?;

This registers a handler for SIGWINCH (window size change) that atomically sets resize_flag to true. The main thread polls this flag in its event loop. This is safe because the signal handler only performs a single atomic store, which is async-signal-safe.

Shutdown Sequence

The cleanup order matters:

drop(tx);                         // 1. Close the channel
let _ = child.wait();             // 2. Wait for the shell to exit
drop(_raw_guard);                 // 3. Restore terminal mode
let _ = storage_handle.join();    // 4. Wait for storage to finish
db.end_session(&session_id)?;     // 5. Mark session as ended

Dropping tx signals the storage thread to flush and exit. The RawModeGuard is dropped before the final message so that eprintln! renders correctly. The storage thread is joined to ensure all data reaches SQLite before the session is marked as ended.

Note that the stdin thread is deliberately not joined. It blocks on stdin.read(), which cannot be interrupted on all platforms. Since the process is about to exit anyway, the OS will clean it up.

A Standalone Example

Here is a minimal program that demonstrates two threads sharing an Arc<AtomicBool>:

use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::Arc;
use std::thread;
use std::time::Duration;

fn main() {
    let flag = Arc::new(AtomicBool::new(false));

    // Spawn a worker thread that checks the flag
    let worker_flag = Arc::clone(&flag);
    let handle = thread::spawn(move || {
        println!("Worker: waiting for signal...");
        loop {
            if worker_flag.load(Ordering::Relaxed) {
                println!("Worker: signal received, shutting down.");
                break;
            }
            thread::sleep(Duration::from_millis(100));
        }
    });

    // Main thread does some work, then signals the worker
    thread::sleep(Duration::from_secs(1));
    println!("Main: sending signal.");
    flag.store(true, Ordering::Relaxed);

    handle.join().unwrap();
    println!("Main: worker exited cleanly.");
}

This is the same pattern broll uses for SIGWINCH. Replace thread::sleep with a signal handler, and you have the real architecture.

Why Not async/await?

broll uses OS threads rather than async runtimes like Tokio. The reasons are practical:

Blocking I/O is unavoidable. stdin.read() and the PTY reader are blocking calls. An async runtime would need spawn_blocking for these, adding complexity without benefit.
Three threads is a fixed, small number. There is no need for the thousands-of-tasks scalability that async provides.
No additional dependencies. std::thread and std::sync are in the standard library. No runtime, no executor, no pinning.

When your concurrency model is "a few long-lived threads passing messages," the standard library gives you everything you need.

Key Takeaways

move closures transfer ownership into threads. This is not optional: the compiler requires it to prevent data races.
mpsc channels provide typed, safe communication. Dropping the sender signals the receiver, enabling clean shutdown.
Arc enables shared ownership across threads. It is Rc with atomic reference counting, and the compiler enforces that you use the right one.
Atomics provide lock-free access to simple values. Ordering::Relaxed is often sufficient for flags and counters where eventual consistency is acceptable.
signal_hook makes Unix signals safe. Instead of running complex code in a signal handler, set a flag and check it in your event loop.
Explicit drop ordering controls shutdown. Channel close, child wait, guard drop, thread join: the sequence determines correctness.

broll's entire concurrency model fits in one file, uses no external runtime, and relies on the compiler to verify thread safety at compile time. That is the Rust value proposition for systems programming: fearless concurrency is not a slogan, it is enforced by the type system.

Try it out:

Spawning a PTY in Rust: How broll Captures Your Terminal Without You Noticing

Rodrigo Mello — Thu, 26 Mar 2026 12:09:35 +0000

When you run broll start, something subtle happens. A new shell opens, and it looks exactly like your normal terminal. Your prompt, aliases, keybindings, colors: everything works. But behind the scenes, every byte of output flows through broll's recording pipeline before it reaches your screen.

The trick that makes this possible is a pseudo-terminal (PTY). This post explains what PTYs are, how broll spawns one in Rust, how it injects shell hooks using OSC escape sequences to distinguish commands from output, and how it uses the Drop trait to guarantee safe cleanup.

What Is a PTY and Why Do You Need One?

A PTY is a pair of virtual devices: a "master" side and a "slave" side. The slave side looks like a real terminal to any program connected to it. The master side gives you programmatic access to everything the program writes, and lets you send input as if a human were typing.

Without a PTY, you could try capturing output by piping stdout. But that breaks interactive programs. Tools like vim, less, and htop need a real terminal to query its size, move the cursor, and read keypresses. They detect when they are connected to a pipe and either refuse to run or fall back to a degraded mode.

A PTY solves this because the child process sees a genuine terminal device. It can call ioctl to get the terminal size, switch to raw mode, and use escape sequences. Meanwhile, the parent process reads and writes through the master side, acting as an invisible intermediary.

Spawning the PTY with portable-pty

broll uses the portable-pty crate (version 0.8) to abstract over platform differences. Here is the setup from src/recorder/mod.rs:

let (cols, rows) = crossterm::terminal::size().unwrap_or((80, 24));

let pty_system = NativePtySystem::default();
let pair = pty_system
    .openpty(PtySize {
        rows,
        cols,
        pixel_width: 0,
        pixel_height: 0,
    })
    .context("Failed to open PTY")?;

openpty returns a PtyPair containing the master and slave ends. The size is initialized from the real terminal's dimensions so the child shell renders correctly from the start.

Next, broll builds the command to spawn in the PTY:

let mut cmd = CommandBuilder::new(&shell);
cmd.env(SESSION_ENV_VAR, &session_id);
cmd.env("BROLL_SESSION", session_label);
cmd.cwd(&work_dir);

let mut child = pair.slave.spawn_command(cmd)?;
drop(pair.slave);

Two details matter here. First, SESSION_ENV_VAR (BROLL_SESSION_ID) is injected so broll can detect nested sessions and prevent recording inside a recording. Second, pair.slave is dropped immediately after spawning. The slave side is only needed to create the child process. Keeping it open would prevent the master from receiving EOF when the child exits.

After spawning, broll obtains a reader and writer for the master side:

let mut reader = pair.master.try_clone_reader()?;
let writer = pair.master.take_writer()?;

The reader is used by the main thread to consume PTY output. The writer is moved into a separate thread that forwards stdin. This separation is the foundation of broll's three-thread architecture, which the next post in this series covers in detail.

Shell Hook Injection with OSC Sequences

Recording raw terminal output is useful, but broll wants to do more: it needs to know which bytes are part of a command you typed and which bytes are that command's output. To do this, it injects shell hooks that emit invisible markers.

What Are OSC Sequences?

OSC stands for Operating System Command. These are escape sequences in the format \x1b]<code>;<data>\x07 that terminals use for metadata like setting the window title. Terminals silently ignore OSC codes they do not recognize, which makes them perfect for embedding custom signals in the byte stream.

broll uses private OSC code 777 (a convention for application-specific extensions):

const PREEXEC_MARKER_PREFIX: &str = "\x1b]777;broll-exec;";
const PREEXEC_MARKER_END: char = '\x07';
const PRECMD_MARKER: &str = "\x1b]777;broll-cmd\x07";

The preexec marker fires just before a command runs and includes the command text. The precmd marker fires when the command finishes and the prompt is about to appear.

Injecting the Hooks

broll cannot modify the user's shell configuration permanently. Instead, it creates a temporary rc file that first sources the user's existing config, then appends the hook functions:

fn create_hook_rc(shell_name: &str) -> Option<tempfile::TempDir> {
    let broll_data = dirs::data_dir()?.join("broll");
    std::fs::create_dir_all(&broll_data).ok()?;
    let tmp_dir = tempfile::Builder::new()
        .prefix("broll-")
        .tempdir_in(&broll_data)
        .ok()?;

    let hook_code = match shell_name {
        "zsh" => {
            let user_zshrc = dirs::home_dir()
                .map(|h| h.join(".zshrc"))
                .filter(|p| p.exists());
            let source_line = user_zshrc
                .map(|p| format!("[[ -f \"{}\" ]] && source \"{0}\"\n", p.display()))
                .unwrap_or_default();

            let rc_path = tmp_dir.path().join(".zshrc");
            let content = format!(
                concat!(
                    "{}",
                    "_broll_preexec() {{\n",
                    "  local cmd=\"${{1//$'\\a'/}}\"\n",
                    "  printf '\\e]777;broll-exec;%s\\a' \"$cmd\"\n",
                    "}}\n",
                    "_broll_precmd() {{ printf '\\e]777;broll-cmd\\a'; }}\n",
                    "autoload -Uz add-zsh-hook\n",
                    "add-zsh-hook preexec _broll_preexec\n",
                    "add-zsh-hook precmd _broll_precmd\n",
                ),
                source_line,
            );
            std::fs::write(&rc_path, content).ok()?;
            Some(())
        }
        // bash variant uses PROMPT_COMMAND similarly
        _ => None,
    };
    hook_code.map(|_| tmp_dir)
}

For zsh, the trick is setting the ZDOTDIR environment variable to point at the temp directory. zsh loads $ZDOTDIR/.zshrc on startup instead of ~/.zshrc:

match shell_name.as_str() {
    "zsh" => {
        cmd.env("ZDOTDIR", tmp.path().to_str().unwrap_or("/tmp"));
    }
    "bash" => {
        let rc_path = tmp.path().join(".bashrc");
        cmd.args(["--rcfile", rc_path.to_str().unwrap_or("/tmp/.bashrc")]);
    }
    _ => {}
}

For bash, the --rcfile argument serves the same purpose.

The State Machine

On the storage thread, a simple two-state machine processes the markers:

#[derive(PartialEq)]
enum CaptureState {
    /// Between precmd and preexec. Prompt + user typing. Skip this.
    Idle,
    /// Between preexec and precmd. Real command output. Capture this.
    Capturing,
}

When the storage thread sees a preexec marker, it extracts the command text, stores it as an input chunk, and transitions to Capturing. When it sees a precmd marker, it renders the accumulated output through a VT100 virtual terminal and stores the result. Then it transitions back to Idle.

The tempfile::TempDir return value is important. TempDir implements Drop, so when the variable holding it goes out of scope (when the session ends), the temporary directory and its contents are automatically deleted. The caller stores it in _tmp_dir, where the underscore prefix tells the reader (and the compiler) that the binding exists solely for its destructor.

The RAII RawModeGuard

When the PTY is active, broll puts the real terminal into raw mode so that every keystroke reaches the child process immediately (instead of being line-buffered). But if the program panics or returns early, the terminal must be restored. Leaving a terminal in raw mode is a miserable user experience: no echo, no line editing, no Ctrl+C.

broll uses the RAII (Resource Acquisition Is Initialization) pattern to guarantee cleanup:

struct RawModeGuard;

impl RawModeGuard {
    fn enable() -> Result<Self> {
        crossterm::terminal::enable_raw_mode()?;
        Ok(Self)
    }
}

impl Drop for RawModeGuard {
    fn drop(&mut self) {
        let _ = crossterm::terminal::disable_raw_mode();
    }
}

The Drop trait is Rust's destructor. When a RawModeGuard goes out of scope, whether through normal return, early ? propagation, or a panic, disable_raw_mode() runs automatically. The let _ = discards any error from the cleanup call, because there is nothing useful to do if disabling raw mode fails during stack unwinding.

In start_session, the guard is created right before the I/O loop:

let _raw_guard = RawModeGuard::enable()?;

And explicitly dropped before printing exit messages:

drop(_raw_guard);
eprintln!("broll: session {} ended", &session_id[..8]);

This explicit drop call ensures raw mode is disabled before the final message, so \n works correctly in the output.

A Minimal PTY Example

Here is a standalone example that spawns a PTY, runs ls, and captures the output. Add portable-pty = "0.8" to your dependencies:

use portable_pty::{CommandBuilder, NativePtySystem, PtySize, PtySystem};
use std::io::Read;

fn main() -> anyhow::Result<()> {
    let pty_system = NativePtySystem::default();
    let pair = pty_system.openpty(PtySize {
        rows: 24,
        cols: 80,
        pixel_width: 0,
        pixel_height: 0,
    })?;

    let mut cmd = CommandBuilder::new("ls");
    cmd.arg("-la");

    let mut child = pair.slave.spawn_command(cmd)?;
    drop(pair.slave); // Must drop so master gets EOF

    let mut reader = pair.master.try_clone_reader()?;
    let mut output = String::new();
    reader.read_to_string(&mut output)?;

    child.wait()?;
    println!("Captured output:\n{}", output);

    Ok(())
}

The key insight: after drop(pair.slave), the master reader will receive EOF when the child exits. Without that drop, read_to_string would block forever.

Putting It Together

The flow when a user runs broll start looks like this:

Create a PTY pair sized to match the real terminal.
Build a temporary rc file with OSC-emitting hooks.
Spawn the user's shell in the PTY slave with ZDOTDIR (or --rcfile) pointing to the temp rc.
Drop the slave side.
Enable raw mode with a RawModeGuard.
Start I/O threads (covered in the next post).
The shell loads the hooks. Every command triggers preexec/precmd markers.
The storage thread parses markers, renders output through VT100, and stores chunks in SQLite.
When the shell exits, the master reader gets EOF, the channel closes, and cleanup runs in reverse order.

The user sees a normal shell. The hooks are invisible. The temp files clean themselves up. And every command, along with its output, ends up in a searchable database.

Try it out:

Building a 12-Command CLI in 120 Lines with clap Derive Macros

Rodrigo Mello — Sat, 21 Mar 2026 11:31:06 +0000

Most CLI tools start life as a tangle of if statements and hand-rolled argument parsing. In Rust, you can define your entire command structure as a type-safe enum and let the compiler generate everything else. This post walks through how broll, a terminal session recorder, defines 12 subcommands in about 120 lines of declarative code using clap's derive macros.

What Are Derive Macros?

Rust's procedural macros can inspect your struct or enum at compile time and generate additional code. When you write #[derive(Parser)] on a struct, clap's macro reads your field names, types, and attributes, then generates a full argument parser: help text, flag handling, validation, and type conversion.

You never see the generated code in your source files. But at compile time, your simple struct becomes a complete CLI parser with --help output, error messages, and shell completions.

The Top-Level Parser

broll's entire CLI definition lives in src/cli/mod.rs. The entry point is a two-field struct:

use clap::{Parser, Subcommand};

#[derive(Parser)]
#[command(name = "broll", about = "Terminal session recorder with searchable output")]
pub struct Cli {
    #[command(subcommand)]
    pub command: Command,
}

#[derive(Parser)] generates the Cli::parse() method, which reads std::env::args(), validates them, and returns a populated Cli instance or exits with an error. The #[command(subcommand)] attribute tells clap that the command field is dispatched as a subcommand (like broll start, broll search, etc.).

Enums with Data: The Command Type

Here is where things get interesting. Each variant of the Command enum is a subcommand, and its fields become that subcommand's arguments:

#[derive(Subcommand)]
pub enum Command {
    /// Start recording a new session (spawns a sub-shell)
    Start {
        /// Give the session a name for easier identification and lookup
        #[arg(short, long)]
        name: Option<String>,

        /// Tag the session for easier lookup
        #[arg(short, long)]
        tag: Option<String>,

        /// Disable sensitive content filtering
        #[arg(long, default_value_t = false)]
        no_filter: bool,

        /// Working directory for the session (defaults to current directory)
        #[arg(short, long)]
        dir: Option<PathBuf>,
    },

    /// Stop the current recording session
    Stop,

    /// Delete one or more recorded sessions and all their data
    Delete {
        /// Session IDs, prefixes, or names
        #[arg(required = true)]
        ids: Vec<String>,

        /// Skip confirmation prompt
        #[arg(short, long, default_value_t = false)]
        force: bool,
    },

    /// View a recorded session (opens TUI)
    View {
        /// Session ID, prefix, or name
        id: String,
    },

    // ... 8 more variants
}

Several Rust concepts work together here:

Option<T> vs T for required vs. optional. A field typed Option<String> becomes an optional flag. A field typed String is required. clap infers this from the type alone. In View, the id: String field is a required positional argument. In Start, name: Option<String> becomes --name <VALUE> which can be omitted.

Vec<T> for variadic arguments. The Delete variant accepts ids: Vec<String>, meaning the user can pass one or more session IDs: broll delete abc123 def456. The #[arg(required = true)] attribute ensures at least one value is provided.

PathBuf for file paths. clap automatically converts string arguments into PathBuf values, giving you a typed path without manual conversion.

Doc comments as help text. Every /// comment becomes the description shown in --help. No separate help strings to maintain.

Pattern Matching for Routing

The entire main.rs is a match expression that dispatches each variant to the right module:

use anyhow::Result;
use clap::Parser;
use cli::{Cli, Command};

fn main() -> Result<()> {
    let cli = Cli::parse();

    match cli.command {
        Command::Start { name, tag, group, no_filter, dir } => {
            recorder::start_session(name, tag, group, no_filter, dir)?;
        }
        Command::Stop => {
            recorder::stop_session()?;
        }
        Command::List { group } => {
            storage::list_sessions(group)?;
        }
        Command::Search { query, group, terminal } => {
            tui::search::run(query, group, terminal)?;
        }
        Command::View { id } => {
            tui::view::run(&id)?;
        }
        Command::Delete { ids, force } => {
            storage::delete_sessions(&ids, force)?;
        }
        Command::Stats => {
            storage::show_stats()?;
        }
        // ... remaining variants
    }

    Ok(())
}

Rust's match is exhaustive: the compiler will refuse to compile if you add a new Command variant without handling it here. This is a powerful guarantee. You cannot add a subcommand and forget to wire it up.

Notice how the match arms destructure each variant. Command::Start { name, tag, group, no_filter, dir } extracts all five fields directly into local variables. No .name() getters, no downcasting.

Error Handling with `?` and `anyhow`

The return type Result<()> uses anyhow::Result, which wraps any error type into a single anyhow::Error. The ? operator at the end of each function call does two things:

If the call returns Ok(value), it unwraps the value and continues.
If it returns Err(e), it immediately returns from main with that error.

This replaces what would otherwise be nested match statements or .unwrap() calls. The anyhow crate adds context methods too. In the recorder module, you will find patterns like:

let pair = pty_system
    .openpty(PtySize { rows, cols, pixel_width: 0, pixel_height: 0 })
    .context("Failed to open PTY")?;

The .context() method wraps the underlying error with a human-readable message, so if PTY creation fails, the user sees "Failed to open PTY" followed by the lower-level cause.

A Standalone Example

Here is a minimal but working CLI using the same patterns. You can try this with cargo new mycli and adding clap = { version = "4", features = ["derive"] } and anyhow = "1" to your Cargo.toml:

use anyhow::Result;
use clap::{Parser, Subcommand};

#[derive(Parser)]
#[command(name = "tasks", about = "A tiny task manager")]
struct Cli {
    #[command(subcommand)]
    command: Command,
}

#[derive(Subcommand)]
enum Command {
    /// Add a new task
    Add {
        /// Task description
        description: String,

        /// Priority level (1-5)
        #[arg(short, long, default_value_t = 3)]
        priority: u8,
    },

    /// List all tasks
    List {
        /// Show only high-priority tasks
        #[arg(short, long)]
        important: bool,
    },

    /// Remove tasks by ID
    Remove {
        #[arg(required = true)]
        ids: Vec<u32>,
    },
}

fn main() -> Result<()> {
    let cli = Cli::parse();

    match cli.command {
        Command::Add { description, priority } => {
            println!("Added task (priority {}): {}", priority, description);
        }
        Command::List { important } => {
            if important {
                println!("Showing high-priority tasks only");
            } else {
                println!("Showing all tasks");
            }
        }
        Command::Remove { ids } => {
            println!("Removing {} task(s)", ids.len());
        }
    }

    Ok(())
}

Running cargo run -- add "Write blog post" --priority 5 prints Added task (priority 5): Write blog post. Running cargo run -- --help gives you auto-generated help for every subcommand.

What clap Generates Behind the Scenes

When you write #[derive(Parser)] on Cli, clap generates an implementation that:

Creates a clap::Command with the name "broll" and the about text.
Iterates over each enum variant to register subcommands.
Maps Option<String> fields to optional flags, String to required positional arguments, bool to boolean flags, and Vec<String> to variadic positionals.
Extracts short and long flag names from the attribute or field name.
Uses doc comments as the help description.

All of this happens at compile time. There is no runtime reflection, no dynamic dispatch, and no allocation for the parser itself. The resulting binary parses arguments as fast as hand-written code would.

Key Takeaways

Derive macros turn data definitions into behavior. Your enum is both the type system representation and the CLI specification.
Option<T> models optionality at the type level. No null checks, no sentinel values.
Exhaustive match forces you to handle every case. Adding a variant without a handler is a compile error.
The ? operator keeps error handling concise. Combined with anyhow, you get rich error context without boilerplate.
You get help text, validation, and shell completions for free. The doc comments you write for your own understanding become user-facing documentation.

broll's 12 subcommands, each with their own flags and positional arguments, fit in 123 lines of declarative Rust. The routing logic in main.rs is another 55. No framework, no code generation step, no runtime overhead.

Try it out:

Stop Losing Terminal Output: I Built a CLI That Records and Searches Your Shell Sessions

Rodrigo Mello — Fri, 20 Mar 2026 14:08:18 +0000

If you spend most of your day in the terminal, you've probably been here: you're debugging a service, tailing logs across three terminal tabs, hot-reloading a dev server, and then you need that one stack trace from twenty minutes ago. It's gone. Scrollback cleared, terminal closed, or simply buried under a wall of newer output.

I got tired of this. So I built broll, a Rust CLI that records your terminal sessions, stores them in SQLite with full-text search, and lets you browse everything later in a TUI.

The name comes from B-roll, the background footage in film that captures everything happening behind the main scene. That's exactly what your terminal output is: the unscripted, behind-the-scenes footage of your development work. You never think about it while it's rolling, but when something goes wrong, it's the first thing you wish you had.

cargo install broll

The Problem

Terminal emulators give you a scrollback buffer. That buffer is finite, session-scoped, and unsearchable. If you're running a hot-reloading dev server, every restart wipes previous output. If you're working across multiple terminals, say one for your API, one for a worker, one for ad-hoc commands, correlating what happened across them later is basically impossible.

You can pipe things to files, sure. But that means knowing in advance which output you'll need later, and you lose the interactivity of your shell.

How broll Works

You wrap your shell session with broll start and work normally. When you're done, exit or broll stop. Everything in between, every command you typed and every byte of output, is captured, timestamped, and stored.

$ broll start --name "debugging-auth-issue"
# ... work normally, run commands, tail logs ...
$ exit

Under the hood, broll spawns a PTY sub-shell and installs lightweight shell hooks (zsh preexec/precmd, bash PROMPT_COMMAND) that emit OSC escape sequences. These markers let broll's recorder distinguish what you typed from what the shell printed back, without interfering with your workflow. Your shell behaves exactly as it normally does. broll is invisible until you need it.

Captured output goes into SQLite with FTS5 full-text indexing. That means you can search across all your sessions later:

$ broll search "connection refused"

This opens a two-panel TUI with live search: results update as you type with debounced input. Select a match and press Enter to jump into a full session viewer, scrolled right to the relevant line.

The TUI

The viewer and search panels are built with ratatui. A few things I'm particularly happy with:

Syntax highlighting for JSON, log levels (ERROR/WARN/INFO/DEBUG), URLs, and file:line references in output
Vim-style yank (yy, Y, V for visual line mode) to copy lines straight to your clipboard
Mouse support for scrolling and clicking through results
In-session search with / in the viewer, just like less/vim

The viewer preserves terminal formatting. broll uses a virtual terminal (vt100 crate) to render the raw captured bytes, so colored output, progress bars, and column alignment all look correct when you review them later.

Automatic Secret Redaction

Since terminal sessions can contain sensitive content like environment variables with tokens, API keys, database URLs, or JWTs, broll runs all captured output through a redaction filter before storing it. Regex patterns match seven categories of secrets (AWS keys, bearer tokens, private key blocks, connection strings, etc.) and replace the sensitive values with [REDACTED] while preserving the surrounding context.

This is on by default. You can disable it with --no-filter if you need raw output for a specific session.

Other Features

Session management: name, rename, annotate, tag, group, delete, and view stats
Export/import: share sessions as portable JSON files with teammates
Command extraction: pull just the commands from a session (no output) for documentation or scripting
Prefix matching: broll view abc matches session ID abc123... so you don't need to type full UUIDs

What's Next

I'm planning a series of detailed, deep dive videos walking through how broll's features work under the hood, going line by line through the Rust code. There's a lot of interesting stuff in here: PTY spawning, OSC escape sequence parsing, state machines for command/output delimiting, multi-threaded I/O with channels, terminal resize handling with atomics, and FTS5 full-text search integration. These won't be quick overviews. Each video will be a real deep dive into the internals, so if you're into Rust or systems programming, I think you'll get a lot out of them.

Some features on the roadmap: regex search, cross-session timelines, collapsible output chunks, and auto-start via shell integration so you don't even need broll start.

broll is MIT-licensed and available on crates.io and GitHub.

If you try it out, I'd love to hear your feedback. And if terminal tooling or Rust internals are your thing, follow along. More content is coming.

DEV Community: Rodrigo Mello

Three Threads, One Terminal: Concurrency in Rust with Channels and Atomics

The Three-Thread Architecture

Spawning Threads with move Closures

mpsc Channels: One Producer, One Consumer

Arc: Shared Ownership Across Threads

Why Arc and Not Rc?

Atomics: Lock-Free Shared State

AtomicBool for the Resize Flag

AtomicU16 for Terminal Width

What Does Ordering::Relaxed Mean?

Signal Handling with signal_hook

Shutdown Sequence

A Standalone Example

Why Not async/await?

Key Takeaways

Spawning a PTY in Rust: How broll Captures Your Terminal Without You Noticing

What Is a PTY and Why Do You Need One?

Spawning the PTY with portable-pty

Shell Hook Injection with OSC Sequences

What Are OSC Sequences?

Injecting the Hooks

The State Machine

The RAII RawModeGuard

A Minimal PTY Example

Putting It Together

Building a 12-Command CLI in 120 Lines with clap Derive Macros

What Are Derive Macros?

The Top-Level Parser

Enums with Data: The Command Type

Pattern Matching for Routing

Error Handling with ? and anyhow

A Standalone Example

What clap Generates Behind the Scenes

Key Takeaways

Stop Losing Terminal Output: I Built a CLI That Records and Searches Your Shell Sessions

The Problem

How broll Works

The TUI

Automatic Secret Redaction

Other Features

What's Next

Error Handling with `?` and `anyhow`