grainx

grainx shows live computer and process activity in a terminal and can share those readings over a local web connection.

Note

Status: Experimental CLI tool (v0.1.3, pre-1.0); CI checks Linux and macOS.

• Shows CPU, memory, disk, network, and process activity in an interactive dashboard.
• Serves host readings through a local HTTP service.
• Saves local or remote readings as JSON and CSV files.
• Adjusts dashboard refresh and rendering under high system load.

Quick start

Try the released CLI (macOS or Linux)

The prebuilt CLI does not require Rust. The installer downloads a release, checks its SHA-256 checksum, and installs to ~/.local/bin:

curl -fsSL https://raw.githubusercontent.com/rustfuture/grainx/main/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
grainx --version
grainx            # dashboard; press q to quit
grainx export --json /tmp/grainx-stats.json --csv /tmp/grainx-stats.csv

Prebuilt Linux binaries require glibc; unsupported platforms can build from source. On Windows, use the PowerShell installer.

Build from source

You need Git and stable Rust 1.88 or newer with Cargo (rustup), plus an interactive terminal for the dashboard. The first build downloads Cargo dependencies. The crate uses Rust edition 2024; the minimum version is checked against the committed dependency lockfile.

git clone https://github.com/rustfuture/grainx.git
cd grainx
cargo run --locked

Hide the process table when screen sharing or recording with --hide-processes:

cargo run --locked -- --hide-processes

The default command opens the dashboard; press q to quit. For a first check without an interactive terminal, export local readings instead:

cargo run --locked -- export --json /tmp/grainx-stats.json --csv /tmp/grainx-stats.csv

The command prints the two output paths. Open the JSON or CSV file to inspect the readings; no HTTP agent or external service is needed. On Windows, choose local output paths instead of /tmp/...; Windows is not covered by CI.

See usage and project details for configuration, commands, controls, metric definitions, demos, benchmarks, and compatibility notes.

Architecture

The CLI starts the interactive dashboard by default, or runs the HTTP service, exports readings, or generates shell completions. The monitor collects system and process readings into a shared snapshot. The dashboard displays that snapshot, while the --remote <url> option of the dashboard and export commands fetches the snapshot from a running agent instead. The agent serves health and metrics endpoints over HTTP and only binds to a loopback address, so reaching it from another machine needs a tunnel or authenticated proxy that grainx does not provide. Export writes snapshots as JSON and CSV.

Tests

The CI workflow runs these commands:

cargo fmt --check
cargo check --locked --all-targets
cargo clippy --locked --all-targets -- -D warnings
cargo test --locked
cargo bench --locked --no-run

The tests cover command parsing, system sampling, dashboard layout, HTTP responses, and JSON/CSV export behavior.

Limitations

• The HTTP agent has no TLS, authentication, or rate limiting. It rejects non-loopback bind addresses; loopback does not isolate users or processes on the same machine.
• Network and disk readings are aggregates, without per-socket or per-file detail.
• The formula evaluator accepts whitespace-separated operations from left to right, without operator precedence or parentheses.
• The dashboard requires an interactive terminal. Windows is not covered by the CI matrix.

License

grainx is released under the MIT License. See LICENSE.