From 3e139b12b0d65956e861c0966d5594ffea63901f Mon Sep 17 00:00:00 2001 From: Piotr Migdal Date: Tue, 9 Sep 2025 17:15:50 +0200 Subject: [PATCH 1/4] readme improved --- README.md | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 573b0f6..7c2097f 100644 --- a/README.md +++ b/README.md @@ -7,9 +7,11 @@ Run the classic [“60‑second Linux Performance Analysis”](https://netflixtechblog.com/linux-performance-analysis-in-60-000-milliseconds-accc10403c55) checklist in one command. A portable Nix toolbox is downloaded on the fly, diagnostics run in parallel with a simple TUI, and an optional AI summary is shown at the end. - One command to run it all -- Fast and portable -- No Docker, no system‑wide installs -- Optional AI summary +- Fast – do the 60 seconds analysis in around 6 seconds +- Just works – no sudo, no Docker, no installation of system-wide packages +- An optional AI summary at the end – no need to read walls of command outputs + +More details in a blog post [60-Second Linux Analysis with Nix and LLMs](https://quesma.com/blog/60s-linux-analysis-nix-llms/). > [!NOTE] > This project is an early experiment. @@ -17,14 +19,17 @@ Run the classic [“60‑second Linux Performance Analysis”](https://netflixte ## Quick Start ```bash -# Any provider works; set one of these env vars to enable AI summary -export ANTHROPIC_API_KEY="" # Anthropic -export OPENAI_API_KEY="" # OpenAI -export OPENROUTER_API_KEY="" # OpenRouter - curl -fsSL https://gradient.engineer/60-second-linux.sh | sh ``` +Optionally, before running the script, set an API key for an LLM provider: + +```bash +export ANTHROPIC_API_KEY="" # OR +export OPENAI_API_KEY="" # OR +export OPENROUTER_API_KEY="" +``` + Notes: - If no key is set, diagnostics still run; only the AI summary is skipped. @@ -36,10 +41,13 @@ Notes: ## Build from Source +Requires [Go 1.25 or newer](https://go.dev/). + ```bash cd app go build -o gradient-engineer-go -./gradient-engineer-go 60-second-linux +./gradient-engineer-go 60-second-linux # for Linux +./gradient-engineer-go 60-second-darwin # for macOS ``` ## Advanced From 49b88581ae0f343ed83e498a192da83cf4bced18 Mon Sep 17 00:00:00 2001 From: Piotr Migdal Date: Tue, 9 Sep 2025 17:26:16 +0200 Subject: [PATCH 2/4] readme more --- README.md | 38 +++++++++++++++++++++++++++----------- 1 file changed, 27 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 7c2097f..b4e6bcb 100644 --- a/README.md +++ b/README.md @@ -4,25 +4,33 @@ # `gradient-engineer` — 60‑Second Linux Analysis (Nix + LLM) -Run the classic [“60‑second Linux Performance Analysis”](https://netflixtechblog.com/linux-performance-analysis-in-60-000-milliseconds-accc10403c55) checklist in one command. A portable Nix toolbox is downloaded on the fly, diagnostics run in parallel with a simple TUI, and an optional AI summary is shown at the end. +Run the classic [60‑second Linux Performance Analysis](https://netflixtechblog.com/linux-performance-analysis-in-60-000-milliseconds-accc10403c55) checklist in one command on Linux (or macOS). It solves the `command not found` problem on minimal systems by downloading a portable [Nix](https://nixos.org/) toolbox on the fly. Diagnostics run in parallel with a simple TUI, and an optional AI summary is shown at the end. -- One command to run it all -- Fast – do the 60 seconds analysis in around 6 seconds -- Just works – no sudo, no Docker, no installation of system-wide packages -- An optional AI summary at the end – no need to read walls of command outputs +- **One command**: Run the entire analysis with a single line. +- **Fast**: Get a full system snapshot in about 6 seconds. +- **Just works**: No sudo, no Docker, and no permanent installation. +- **AI-powered summary**: Let an LLM explain the raw command outputs. -More details in a blog post [60-Second Linux Analysis with Nix and LLMs](https://quesma.com/blog/60s-linux-analysis-nix-llms/). +More details in the blog post: [60-Second Linux Analysis with Nix and LLMs](https://quesma.com/blog/60s-linux-analysis-nix-llms/). > [!NOTE] > This project is an early experiment. +## Why? The `command not found` Nightmare + +You SSH into a server to troubleshoot an issue, run a standard tool like `iostat`, and are greeted with `command not found`. Minimal container images and server installations often lack essential diagnostic tools. Installing them during an outage is a waste of precious time and can be blocked by firewalls, package manager issues, or immutable filesystems. + +`gradient-engineer` solves this by providing a portable, on-demand toolbox with all the necessary utilities, powered by [Nix](https://nixos.org/). It runs the tools you need without requiring root access or permanent changes to the system. + ## Quick Start +Run the following command in your terminal. It works on both Linux and macOS. + ```bash curl -fsSL https://gradient.engineer/60-second-linux.sh | sh ``` -Optionally, before running the script, set an API key for an LLM provider: +To enable the optional AI summary, set an API key from a supported provider _before_ running the script: ```bash export ANTHROPIC_API_KEY="" # OR @@ -30,12 +38,13 @@ export OPENAI_API_KEY="" # OR export OPENROUTER_API_KEY="" ``` -Notes: +**Notes:** - If no key is set, diagnostics still run; only the AI summary is skipped. -- TUI controls: Tab toggles details; q / Esc / Ctrl+C quits. +- You can override the API base URL via `OPENAI_BASE_URL` (for OpenAI/OpenRouter). +- TUI controls: `Tab` toggles details; `q` / `Esc` / `Ctrl+C` quits. -## Demo - See It in Action! +## Demo [![asciicast](https://asciinema.org/a/738144.svg)](https://asciinema.org/a/738144) @@ -44,8 +53,11 @@ Notes: Requires [Go 1.25 or newer](https://go.dev/). ```bash -cd app +git clone https://github.com/QuesmaOrg/gradient-engineer.git +cd gradient-engineer/app go build -o gradient-engineer-go + +# Run for your platform: ./gradient-engineer-go 60-second-linux # for Linux ./gradient-engineer-go 60-second-darwin # for macOS ``` @@ -54,6 +66,10 @@ go build -o gradient-engineer-go - You can override the API base URL via `OPENAI_BASE_URL` (for OpenAI/OpenRouter) if needed. +## Contributing + +This is an early prototype, and we're just getting started. The repository is open-source, and we're excited to explore what's possible. Have a look at the current [playbooks](./playbook/). We started with the classic, but we bet you have your own favorite commands—feel free to contribute them! + ## License This project is licensed under the MIT License. See the `LICENSE` file for details. From d4197bc57c0d3894fef4442f395d1d0a6abc1860 Mon Sep 17 00:00:00 2001 From: Piotr Migdal Date: Tue, 9 Sep 2025 17:36:12 +0200 Subject: [PATCH 3/4] readme further --- README.md | 22 ++++++++-------------- 1 file changed, 8 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index b4e6bcb..020116f 100644 --- a/README.md +++ b/README.md @@ -4,24 +4,19 @@ # `gradient-engineer` — 60‑Second Linux Analysis (Nix + LLM) -Run the classic [60‑second Linux Performance Analysis](https://netflixtechblog.com/linux-performance-analysis-in-60-000-milliseconds-accc10403c55) checklist in one command on Linux (or macOS). It solves the `command not found` problem on minimal systems by downloading a portable [Nix](https://nixos.org/) toolbox on the fly. Diagnostics run in parallel with a simple TUI, and an optional AI summary is shown at the end. +Run the classic [60‑second Linux Performance Analysis](https://netflixtechblog.com/linux-performance-analysis-in-60-000-milliseconds-accc10403c55) checklist on Linux or macOS. This tool enhances the original playbook with a few key improvements: - **One command**: Run the entire analysis with a single line. -- **Fast**: Get a full system snapshot in about 6 seconds. -- **Just works**: No sudo, no Docker, and no permanent installation. -- **AI-powered summary**: Let an LLM explain the raw command outputs. +- **Fast**: Completes the analysis in about 6 seconds. +- **Solves `command not found`**: Downloads a portable [Nix](https://nixos.org/) toolbox on the fly, so you don't need to install missing tools like `iostat` during a crisis. +- **No dependencies**: Requires no `sudo`, Docker, or permanent installation. +- **AI Summary**: Provides an optional, human-readable summary of the results. More details in the blog post: [60-Second Linux Analysis with Nix and LLMs](https://quesma.com/blog/60s-linux-analysis-nix-llms/). > [!NOTE] > This project is an early experiment. -## Why? The `command not found` Nightmare - -You SSH into a server to troubleshoot an issue, run a standard tool like `iostat`, and are greeted with `command not found`. Minimal container images and server installations often lack essential diagnostic tools. Installing them during an outage is a waste of precious time and can be blocked by firewalls, package manager issues, or immutable filesystems. - -`gradient-engineer` solves this by providing a portable, on-demand toolbox with all the necessary utilities, powered by [Nix](https://nixos.org/). It runs the tools you need without requiring root access or permanent changes to the system. - ## Quick Start Run the following command in your terminal. It works on both Linux and macOS. @@ -30,7 +25,7 @@ Run the following command in your terminal. It works on both Linux and macOS. curl -fsSL https://gradient.engineer/60-second-linux.sh | sh ``` -To enable the optional AI summary, set an API key from a supported provider _before_ running the script: +To enable the optional AI summary, set an API key _before_ running the script: ```bash export ANTHROPIC_API_KEY="" # OR @@ -40,9 +35,8 @@ export OPENROUTER_API_KEY="" **Notes:** -- If no key is set, diagnostics still run; only the AI summary is skipped. -- You can override the API base URL via `OPENAI_BASE_URL` (for OpenAI/OpenRouter). -- TUI controls: `Tab` toggles details; `q` / `Esc` / `Ctrl+C` quits. +- If no key is set, the AI summary is skipped. +- Use `Tab` to toggle details in the TUI; `q` / `Esc` / `Ctrl+C` quits. ## Demo From b1ced07b54e592ce1eee4716cda8165bdaaa8969 Mon Sep 17 00:00:00 2001 From: Piotr Grabowski Date: Tue, 9 Sep 2025 17:40:17 +0200 Subject: [PATCH 4/4] Update README.md --- README.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/README.md b/README.md index 020116f..4e696af 100644 --- a/README.md +++ b/README.md @@ -50,10 +50,7 @@ Requires [Go 1.25 or newer](https://go.dev/). git clone https://github.com/QuesmaOrg/gradient-engineer.git cd gradient-engineer/app go build -o gradient-engineer-go - -# Run for your platform: -./gradient-engineer-go 60-second-linux # for Linux -./gradient-engineer-go 60-second-darwin # for macOS +./gradient-engineer-go ``` ## Advanced