Nex: Terminal Recording and Sharing in Rust

Built Nex in September 2025 as a terminal session recorder and sharing tool. The idea came from wanting to record terminal sessions for tutorials, debugging help, and collaborative work without relying on external services or heavy tools.

What It Does

NEX records everything that happens in your terminal session. Commands you run, output you see, errors you encounter. All captured and saved to a .nex file that can be replayed later.

But it's not just recording. You can also share your terminal in real-time over the network. Someone else can connect and watch what you're doing live. Useful for debugging sessions, teaching, or collaborative work.

Recording Sessions

Start recording with nex start. Opens a new shell session that's being recorded. Everything you type and see gets captured. When you're done, exit the shell and run nex stop. Gets saved to a timestamped .nex file.

The recording includes raw terminal bytes plus command lifecycle markers. When a command starts, that gets logged. When it finishes, that gets logged. You know exactly what commands were run, when they started, what their working directory was.

This metadata comes from zsh hooks that inject markers into the recording stream. Not just a dumb screen recording, it's structured data about what actually happened.

Replay and Export

Replay a recording with nex play filename.nex. Plays back the terminal session in real-time. See exactly what happened, timing and all.

Export to different formats for analysis. nex csv for CSV output, nex json for JSON. Timestamps, command data, output bytes, all exportable for processing with other tools.

Collaborative Sessions

The sharing feature is where it gets interesting. Run nex serve 3000 to host a shared terminal session on port 3000. Other people connect with nex catch hostname 3000 and they see your terminal in real-time.

Everything you type, they see. Every output, they see. It's like screen sharing but just for the terminal. And it saves their session to a .nex file automatically so they have a recording of what happened.

Silent by default. Add --verbose flag if you want to see connection and disconnect messages. Otherwise it just works in the background.

You can also use the nex web mode to get a xterm.js based web display for the terminal session

There's also a web UI mode with nex serve 3000 --web. Opens a web interface for watching the session in a browser instead of another terminal. More accessible for people who aren't terminal users.

Technical Implementation

Built in Rust using Tokio for async runtime and Warp for the web server. PTY (pseudo-terminal) handling for capturing the shell session. WebSocket for real-time streaming to connected clients.

Recording Format

A .nex file is a ZIP archive. Inside is manifest.json with metadata and session.json with newline-delimited JSON events.

Events come in two types. Raw terminal data events with timestamp and base64-encoded bytes. Command lifecycle events with type, phase (start or end), timestamp, working directory, and command.

The format is simple and parseable. ZIP makes it portable. JSON makes it easy to process. Base64 encoding handles binary terminal output safely.

PTY Integration

The recording works by spawning a shell in a PTY. PTY master process reads everything that goes through the terminal. Output from commands, input from keyboard, control sequences, everything.

This raw data gets timestamped and written to the session.json file. Simultaneously, zsh hooks detect command boundaries and inject structured events.

When you replay, the player reads these events and outputs them with proper timing. Seeks through the recording, speed control, all possible because the format is timestamped events.

Network Architecture

The serve mode opens a TCP server. When someone connects with catch, they establish a connection and start receiving the terminal stream.

Server broadcasts PTY output to all connected clients. Clients render it in their terminal. Simple hub-and-spoke model.

WebSocket mode is similar but uses WebSocket protocol for browser compatibility. Xterm.js on the frontend renders the terminal in the browser.

Compression

Terminal sessions compress well. Lots of repeated text, ANSI escape sequences, command output patterns. The .nex files achieve about 75% compression.

ZIP compression on the JSON events shrinks file sizes significantly. A long session might be several megabytes uncompressed but under a megabyte compressed.

Use Cases

Recording debugging sessions to share with colleagues. Instead of trying to screenshot or describe what happened, just send the .nex file. They can replay it and see exactly what you saw.

Creating terminal-based tutorials. Record the session once, share the file. People can replay it at their own pace, pause, rewind, see every command and its output.

Remote help and support. Start a shared session, have someone connect, show them what's happening in real-time. They see your terminal, can guide you through fixes.

Documentation for complex setup processes. Record the installation and configuration steps. Replay shows every command, every output, every error encountered and fixed.

What I Learned

PTY programming taught me how terminal emulators actually work. The escape sequences, control characters, ANSI codes. All the stuff that happens below the shell.

Async Rust with Tokio is powerful for I/O-heavy applications. Reading from PTY, writing to files, streaming to network clients, all concurrent without threads.

Binary data handling in Rust requires care. Raw terminal bytes aren't always valid UTF-8. Base64 encoding solves it but adds overhead.

WebSocket integration for terminal streaming is interesting. Xterm.js makes browser-based terminals practical. Bridging the PTY to WebSocket required protocol translation.

Current State

Nex works for basic recording, replay, export, and sharing. The core functionality is solid. CLI is simple, file format is stable.

Some features are marked TBD in the code. More export formats, better replay controls, additional shell support. But what exists is functional.

Open source on GitHub. Rust crate that can be installed with cargo install. Single binary, no runtime dependencies beyond what Rust provides.

Why It Matters

Terminal workflows are common in development but hard to share effectively. Screenshots don't capture the flow. Copy-paste loses context. Screen recordings are huge files.

Nex provides structured recording that's lightweight, replayable, and shareable. The .nex format preserves timing and commands while staying compact.

The collaborative sharing aspect makes remote debugging and teaching easier. Real-time terminal sharing without screen sharing overhead.

Built in Rust means it's fast and portable. No runtime dependencies. Single binary deployment. Works the same everywhere.

Check it out at nex-terminal.netlify.app for the web interface. Code on GitHub at github.com/aryansrao/nex. Install with cargo install --path . and start recording your terminal sessions.