v1.0.0

gcscope v1.0.0

gcscope is a terminal UI for exploring Go garbage collector behavior in real time.

It helps you see what the garbage collector is doing while a Go program is running: when GC cycles happen, how memory changes over time, where stop-the-world pauses appear, and how behavior differs between runs.

What gcscope shows

• GC cycles as they happen
• Stop-the-world pause statistics
• Heap live / heap goal dynamics
• GC frequency over a recent observation window
• Per-cycle GC details
• Selected pacing-related signals when available
• Snapshots for saving an observation window
• Snapshot diffs for comparing two runs

Main modes

• run: start a compiled Go binary and observe its GC behavior through runtime GC output
• lab: try built-in demo workloads (alloc, churn, idle, spike)
• attach: connect to a running service that exposes runtime metrics
• diff: compare two saved snapshots side by side

Why use it

gcscope is useful when you want a quick visual answer to questions like:

• What is the garbage collector doing while my program runs?
• How often does GC happen?
• How does memory usage change over time?
• Are there pauses worth paying attention to?
• Did a code change or runtime setting change GC behavior?
• Can I quickly demonstrate GC behavior without setting up dashboards?

Install

Go (recommended):

go install github.com/timur-developer/gcscope/cmd/gcscope@latest

Prebuilt binaries:

• Download the archive for your OS/arch from Assets
• Extract and run:
  • Windows: .\gcscope.exe ...
  • macOS/Linux: ./gcscope ...
• Optionally move it into a directory in your PATH

Quickstart

Run a built-in workload:

gcscope lab churn

Observe your own compiled Go binary:

gcscope run ./your-binary

Attach to a running service:

gcscope attach http://127.0.0.1:8080/gcscope/metrics

Docs

See README for usage, controls, configuration, snapshots, and examples.

v0.0.5

Changes

• Docs: edited gif launch.

Docs

See README.md for usage, modes (run / attach / lab / diff), configuration (flags + env), snapshots, controls, and Makefile commands.

v0.0.4

Changes

• Lab: refreshed embedded testbin binaries (used by make testbin).

Docs

See README.md for usage, modes (run / attach / lab / diff), configuration (flags + env), snapshots, controls, and Makefile commands.

v0.0.3

Changes

• Docs: added UI overview screenshot to README (EN/RU).

Docs

See README.md for usage, modes (run / attach / lab / diff), configuration (flags + env), snapshots, controls, and Makefile commands.

v0.0.2

Changes

• --version: gcscope --version now shows the module version when installed via go install ...@latest (fallback to Go build info).
• Docs: refreshed README wording and examples.
• Demos: optimized README GIFs (smaller size / faster load).

Docs

See README.md for usage, modes (run / attach / lab / diff), configuration (flags + env), snapshots, controls, and Makefile commands.

v0.0.1

gcscope — Go Garbage Collector Visualizer

gcscope is a terminal UI (TUI) for visualizing Go GC behavior in real time: GC cycles, STW pauses, heap live/goal dynamics, and GC pacer signals.

Highlights

• Interactive TUI with in-app Help (? / h / f1) and hotkeys
• run: observe GC behavior of your compiled Go binary
• lab: built-in demo workloads (alloc, churn, idle, spike)
• attach: connect to a runtime/metrics HTTP endpoint (via pkg/reporter)
• Snapshots + diff: save runs as JSON and compare two snapshots

Install

Go (recommended):

go install github.com/timur-developer/gcscope/cmd/gcscope@latest

Prebuilt binaries:

• Download the archive for your OS/arch from Assets
• Extract and run:
  • Windows: .\gcscope.exe ...
  • macOS/Linux: ./gcscope ...
• Optionally move it into a directory in your PATH

Quickstart

gcscope lab churn

Docs

See README for usage, metrics/panels, configuration (flags + env), snapshots, and controls.