flow

README

flow

A terminal dashboard for real-time network throughput.

Featured on  

Fast • Beautiful • Cross-Platform • Open Source

Contents

• Install
• Rationale
• Philosophy
• Modes
• Features
• Usage
• Configuration
• Architecture
• Development
• Star History
• License

Install

Arch Linux (AUR)

yay -S flow-network-monitor-bin

💝 Thanks to @Dominiquini for helping bring Flow to the AUR!

Homebrew:

brew install programmersd21/flow/flow

Go:

go install github.com/programmersd21/flow/cmd/flow@latest

From source:

git clone https://github.com/programmersd21/flow
cd flow
make install

Pre-built binaries for Linux, macOS, and Windows (amd64 and arm64) are available on the releases page.

Rationale

Most network monitors display CPU usage, per-process breakdowns, packet counts, and connection tables. flow displays throughput only.

btop	flow
CPU, memory, disks, processes, network	throughput only

Every feature decision is evaluated against a single question: does this help the user understand their network within one second. If not, it is not included.

The result is a small, deliberately scoped tool. There are no additional panels, no required configuration, and no unnecessary complexity in either the interface or the underlying implementation.

Philosophy

flowchart LR
    Input["Network throughput"] --> Q{"Understood within<br/>one second?"}
    Q -->|Yes| Keep["Retain feature"]
    Q -->|No| Cut["Remove feature"]
    Keep --> Result["Calm, minimal interface"]
    Cut --> Result

Every feature is evaluated against one question: does this help a user understand their network within one second. If not, it is removed.

flow does not include CPU panels, packet counters, or multi-pane layouts. It reports download and upload throughput, in real time, and nothing else.

The interface is built for restraint rather than density: large typography, controlled color, and spring-based motion in place of decoration.

Modes

flow adjusts its display according to terminal width and height.

hero	compact	mini	tiny
Full dashboard with logo branding, waveforms, peaks, and daily totals	Cleaner, numbers-only layout with title row, peaks, and daily totals	Graphs-only layout showing waveforms and titles, hiding header logo, daily totals, and footers	Single-line output, intended for status bars; centered when toggled inside the TUI with m

Features

• Live latency (ping) indicator with color-coded ↔ display and configurable target
• Spring-smoothed throughput animation for premium visual feel
• Network processes panel — press n to view active processes sorted by connection count
• Interface details overlay — press I (capital i) to view IP addresses, MAC, link status, MTU
• Theme selector with 8 built-in themes plus custom user themes — press t to browse and select
• Reset confirmation — press r twice to confirm, preventing accidental data loss
• Real-time download and upload throughput
• Interpolated display values using spring-based animation
• Braille-grid waveform rendering at 30 frames per second
• Border color reflects current transfer speed with sleek, modern rounded outlines
• Live peak pulsing white-flash animations when a new session peak is reached
• Minimalist, high-end unicode today statistics and keybinding footer
• Directional indicators for traffic trend
• Automatic unit scaling from B/s to GB/s
• Session peak tracking and daily traffic totals (persisted across restarts)
• Streaming JSON output (--json-stream) for real-time data pipelines
• Custom theme files in ~/.config/flow/themes/
• Four display modes with automatic responsive switching on both width and height resize
• No required configuration; optional TOML configuration file
• Non-interactive output modes for use in scripts
• Supported on Linux, macOS, and Windows
• Display throughput in bits per second instead of bytes per second by toggling with the b key
• Adjust the sampling and refresh interval interactively using the + and - keys

Network Processes

Press n to view active network processes sorted by connection count.

Theme Selector

Press t to open the theme browser with j/k navigation, enter to confirm, esc to cancel. 8 themes included.

Interface Info

Press I (capital i) to view IP addresses, MAC address, link status, and MTU for the current network interface.

Usage

flow                        # hero view, auto interface
flow --tiny                 # single-line mode for status bars
flow --mini                 # graphs-only mode, no headers/footers
flow --compact              # compact layout with title row and waveforms
flow --json                  # single JSON output, then exit
flow --json-stream           # continuous JSON lines output
flow --once                  # single plain-text output, then exit
flow --interface wlan0       # specify network interface
flow --ping 8.8.8.8          # ping target for latency measurement
flow --refresh 500ms         # adjust sampling interval (default 100ms)
flow --bits                 # display in bits/sec instead of bytes/sec
flow --no-color
flow --version
flow --help

Keybindings

Key	Action
q / ^C	Quit
m	Cycle display/view modes
n	Open network processes
t	Choose theme
r	Reset session peaks (twice)
i	Cycle network interfaces
I	Show interface info
c	Cycle display units
b	Toggle bits/bytes mode
+ / -	Adjust refresh interval
p	Pause or resume
?	Open help
esc	Back / close overlay

JSON output

{
  "download_bps": 124300000,
  "upload_bps": 18400000,
  "peak_down_bps": 320000000,
  "peak_up_bps": 48000000,
  "interface": "wlan0",
  "unit_display": "MB/s"
}

tmux integration

# ~/.tmux.conf
set -g status-right "#(flow --tiny --no-color)"
set -g status-interval 1

Configuration

A configuration file is created automatically on first run:

Platform	Path
Linux	~/.config/flow/config.toml
macOS	~/Library/Application Support/flow/config.toml
Windows	%APPDATA%\flow\config.toml

The XDG_CONFIG_HOME environment variable is respected on Linux if set.

refresh     = "100ms"   # sampling interval
history     = 60        # seconds of retained sparkline history
theme       = "default"
unit        = "auto"    # auto, kb, mb, or gb
interface   = "auto"    # auto, or a specific interface name (e.g. eth0, wlan0)
no_color    = false
bits        = false     # display throughput in bits/sec
ping_target = "1.1.1.1" # host for latency measurement

Interface layout

flowchart TD
    Title["flow"]
    Download["DOWNLOAD panel: current speed, peak, waveform"]
    Upload["UPLOAD panel: current speed, peak, waveform"]
    Info["Daily totals and active interface"]
    Footer["Keybinding reference"]

    Title --> Download
    Download --> Upload
    Upload --> Info
    Info --> Footer

All elements are centered on both axes. Panel border color changes according to current transfer speed.

Custom themes

Place .toml files in ~/.config/flow/themes/ to define user themes:

name = "my-theme"
text_dim    = "#64748b"
text_muted  = "#94a3b8"
text_soft   = "#cbd5e1"
text_base   = "#e2e8f0"
text_bright = "#f8fafc"
text_pure   = "#ffffff"
border      = "#334155"
accent      = "#6366f1"
download    = ["#3b82f6", "#6366f1", "#06b6d4", "#00f5d4", "#ffffff"]
upload      = ["#10b981", "#22c55e", "#84cc16", "#a3e635", "#ffffff"]

Architecture

flow runs two independent loops connected by a channel.

flowchart LR
    subgraph Sampling["Sampling loop, approximately 10 Hz"]
        OS["Network counters via gopsutil"] --> SlidingWindow["Sliding-window average"]
        SlidingWindow --> Channel["Sample channel"]
    end

    subgraph Rendering["Render loop, approximately 30 fps"]
        Channel --> Spring["Spring interpolation"]
        Spring --> Display["Dashboard render (Bubble Tea)"]
        Theme["Theme configuration"] -.-> Display
        InterfaceInfo["Interface details (IP, MAC)"] -.-> Display
    end

• The sampling loop reads network counters from the operating system, computes a sliding-window average, and emits a sample on a channel.
• The render loop interpolates display values toward the latest sample and renders the dashboard.
• Interface details (IP addresses, MAC, link status) are fetched on demand via I using both gopsutil and the Go standard library.

Internal package structure

cmd/flow/main.go
    |
    ├── internal/config       ← TOML config management
    ├── internal/collector    ← OS-level network I/O counters + interface details
    ├── internal/sampler      ← Sliding-window sampling loop
    |
    └── internal/ui           ← Bubble Tea Model + views
         ├── model.go         ← State, update loop, key handling
         ├── views.go         ← Dashboard layout and mode selection
         ├── panels.go        ← Download/upload panel rendering
         ├── overlays.go      ← Help, processes, themes, interface info
         ├── layout.go        ← Layout utilities (centering, formatting)
         ├── keys.go          ← Key binding definitions
         ├── internal/history    ← Ring buffer + tracker (peaks/totals)
         ├── internal/sparkline  ← Braille/block graph rendering
         ├── internal/theme      ← 8 colour themes + lipgloss styles
         ├── internal/animate    ← Spring physics, easing, colour lerps
         ├── internal/ping       ← TCP ping measurement
         └── internal/processes  ← Network process enumeration

Separating collection from rendering keeps the interface responsive without adding load to the sampler. Idle CPU usage remains below one percent.

Platform notes: Linux reads /proc/net/dev via gopsutil. macOS uses sysctl and getifaddrs. Windows uses GetIfTable2. No elevated privileges are required on any platform.

Development

make check       # format check, vet, lint, and test
make build       # build ./bin/flow
make test        # go test ./... -race -cover
make release-dry # goreleaser snapshot build, no publish

See CONTRIBUTING.md for contribution guidelines.

Star History

💙 Community & Support

Thank you to everyone who has supported flow. Whether you've starred the repository, reported an issue, submitted a pull request, shared the project, or simply use it every day - your support is what keeps the project growing.

⭐ Stargazers

❤️ Sponsor

If flow has made your terminal a little better, please consider sponsoring its development on GitHub.

Your sponsorship helps support:

• 🚀 New features
• 🐛 Bug fixes
• ⚡ Performance improvements
• 📖 Better documentation
• 🛠️ Long-term maintenance

If you're unable to sponsor, you can still make a huge difference by:

• ⭐ Starring the repository
• 📢 Sharing flow with others
• 💬 Recommending it to friends and colleagues
• 🐞 Reporting bugs or suggesting improvements
• 🤝 Contributing code or documentation

Every contribution, no matter how small, helps flow continue to grow.

Thank you for supporting open source. ❤️

License

MIT. See LICENSE.