RunGlass

Run a command. Get a receipt for what changed.

RunGlass is a Linux-first CLI for commands where terminal history is not enough: AI agents, install scripts, package managers, Docker Compose, deploy scripts, and anything else you want an audit trail for.

runglass run --deep codex exec "fix this failing test"

Terminal history shows what you ran. RunGlass shows what happened:

• files created, modified, and deleted
• stdout, stderr, exit code, duration, and timeline
• child processes and process tree
• outbound network hosts and listening ports
• Docker containers, images, volumes, networks, and published ports
• risk notes for changes worth reviewing
• HTML, Markdown, JSON, bundle, and reverse-patch exports

Example CI/PR use case:

runglass ci --provider github --deep --out runglass-receipt -- codex exec "fix this failing test"

What You Get

RunGlass turns one command boundary into a local receipt:

Command: codex exec "fix this failing test"
Files:   3 created, 2 modified, 0 deleted
Runtime: 7 child processes, 2 outbound hosts, 0 listening ports
Docker:  0 containers, 0 images, 0 volumes
Risk:    low
Exports: receipt.html, receipt.md, receipt.json

Supported receipts can also preview and apply file reverts when RunGlass has stored the needed before-run snapshots.

Example Receipt

MP4 version

Example receipts:

• AI/code-change flow: GIF, MP4
• Docker Compose flow: GIF, MP4
• Full-stack flow: GIF, MP4

Install

RunGlass is Linux-first in this release. normal mode uses Linux process and socket sources, and deep mode uses strace when available. macOS and Windows command observation is not supported yet.

Build locally:

source "$HOME/.cargo/env"
cargo build

Install the CLI into your Cargo bin directory:

source "$HOME/.cargo/env"
cargo install --path crates/runglass-cli

normal mode is a single-binary experience. The embedded web UI, local server, collectors, exports, and revert flow ship inside the Rust runglass binary.

deep mode is still the same binary, but on Linux it uses strace when available for better short-lived process and socket visibility.

Quick Start

Run a command:

runglass run npm install

Open the receipt:

runglass open

Use deep mode when you want stronger process and network fidelity:

runglass run --deep docker compose up -d

Wrap an AI agent command:

runglass run --deep codex exec "fix this failing test"

Why It Exists

Terminal history shows what you ran.

RunGlass shows what happened.

That matters when a command can create files, edit config, pull images, open ports, phone home, spawn child processes, or leave behind state that is easy to miss.

Common Workflows

RunGlass is strongest when one command has one clear boundary:

• runglass run -- codex exec "fix this failing test"
• runglass run codex exec "fix this failing test"
• runglass run -- docker compose up -d
• runglass run docker compose up -d
• runglass run -- npm install
• runglass run -- ./install.sh
• runglass run -- ./deploy-preview.sh

The repository includes repeatable workloads under examples, but they are support material. RunGlass itself is meant to wrap your real commands.

Revert And Export

Export the latest receipt:

runglass export latest --html
runglass export latest --markdown
runglass export latest --json
runglass export latest --reverse-patch
runglass export latest --bundle

Inspect and revert file changes:

runglass open

The web UI can preview file reverts, warn when files changed after the receipt ended, and apply supported reversions.

CI Receipts

Use runglass ci when an agent, install script, or remote runner should leave reviewable artifacts behind:

runglass ci --provider github --deep --out runglass-receipt -- codex exec "fix this failing test"

The command writes receipt.html, receipt.md, receipt.json, and summary.md to the output directory. In CI mode, RunGlass returns the wrapped command's exit code after artifacts are written, so failing commands still fail the job while keeping the receipt available.

Starter workflows are included for GitHub Actions and GitLab CI.

Observation Modes

RunGlass currently supports two Linux observation modes:

• normal: adaptive /proc polling plus ss sampling. Fast, lightweight, and dependency-light.
• deep: normal mode plus strace-based exec and socket tracing for better short-lived process and outbound network visibility.

Docker changes are captured from Docker Engine before/after state. File changes are captured from a scoped working-directory snapshot and diff.

How It Works

RunGlass keeps one command as the unit of review:

• snapshots the working directory before and after the command
• samples Linux process and socket state while the command runs
• uses strace in deep mode when available for better short-lived exec and socket visibility
• compares Docker Engine state before and after the command
• stores stdout, stderr, JSON receipt data, export artifacts, and reversible file snapshots locally

The result is intentionally best-effort rather than magic. RunGlass is designed to answer "what changed because I ran this command?" with useful evidence, while still being clear about snapshot caps, ignored paths, platform support, and tracing limitations.

Snapshot Controls

RunGlass defaults to a 10 MiB per-file snapshot cap so one large artifact does not turn a receipt into a heavy crawl.

Override the cap:

RUNGLASS_MAX_SNAPSHOT_BYTES=26214400 runglass run -- ./install.sh

Ignore local paths with .runglassignore:

dist/
node_modules/
*.sqlite
tmp/
secret.env

See .runglassignore.example and .env.example for starter settings.

CLI Helpers

runglass list --query docker --risk medium --mode deep
runglass open latest
runglass open <receipt-id> --port 0
runglass prune --keep 50 --dry-run
runglass delete latest
runglass doctor
runglass snapshot --dry-run

Scope

RunGlass is for one command, one boundary, one receipt.

It is not trying to be:

• a full terminal replacement
• a multi-command shell session recorder
• perfect system-wide tracing for every event on the machine

It is a pragmatic local receipt for commands you want to understand before you trust.