{"id":13898025,"url":"https://github.com/samoshkin/tmux-plugin-sysstat","last_synced_at":"2025-08-08T02:10:09.439Z","repository":{"id":47429515,"uuid":"111296882","full_name":"samoshkin/tmux-plugin-sysstat","owner":"samoshkin","description":"Prints CPU usage, memory \u0026 swap, load average, net I/O metrics in Tmux status bar","archived":false,"fork":false,"pushed_at":"2021-04-23T03:00:41.000Z","size":75,"stargazers_count":165,"open_issues_count":16,"forks_count":48,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-08T20:44:20.964Z","etag":null,"topics":["shell","tmux","tmux-plugin","tmux-plugin-sysstat","tmux-plugins"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/samoshkin.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-11-19T13:18:36.000Z","updated_at":"2025-03-22T19:36:33.000Z","dependencies_parsed_at":"2022-08-23T07:30:30.355Z","dependency_job_id":null,"html_url":"https://github.com/samoshkin/tmux-plugin-sysstat","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/samoshkin/tmux-plugin-sysstat","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samoshkin%2Ftmux-plugin-sysstat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samoshkin%2Ftmux-plugin-sysstat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samoshkin%2Ftmux-plugin-sysstat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samoshkin%2Ftmux-plugin-sysstat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/samoshkin","download_url":"https://codeload.github.com/samoshkin/tmux-plugin-sysstat/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samoshkin%2Ftmux-plugin-sysstat/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269351910,"owners_count":24402678,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-08T02:00:09.200Z","response_time":72,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["shell","tmux","tmux-plugin","tmux-plugin-sysstat","tmux-plugins"],"created_at":"2024-08-06T18:04:01.218Z","updated_at":"2025-08-08T02:10:09.381Z","avatar_url":"https://github.com/samoshkin.png","language":"Shell","readme":"\nTmux sysstat plugin\n===================\nAllow to print CPU usage, memory \u0026 swap, load average, net I/O metrics in Tmux status bar\n\n![intro](/screenshots/intro.png)\n\nYou might checkout [tmux-config](https://github.com/samoshkin/tmux-config) repo to see this plugin in action.\n\nFeatures\n--------\n- CPU usage\n- Memory available/free, used, total (KiB,MiB,GiB), free/used %\n- Swap used, free, total, free/used %\n- load average for last 1,5,15 minutes\n- configurable thresholds (low, medium, stress) with custom colors\n- tweak each metric output using templates (e.g, 'used 10% out of 16G')\n- configurable size scale (K,M,G)\n- OSX, Linux support\n- [ ] **TODO:** network I/O metric support\n\nTested on: OS X El Capitan 10.11.5, Ubuntu 14 LTS, CentOS 7, FreeBSD 11.1.\n\n\nInstallation\n------------\nBest installed through [Tmux Plugin Manager](https://github.com/tmux-plugins/tpm) (TMP). Add following line to your `.tmux.conf` file:\n\n```\nset -g @plugin 'samoshkin/tmux-plugin-sysstat'\n```\n\nUse `prefix + I` from inside tmux to install all plugins and source them. If you prefer, same effect can be achieved from [command line](https://github.com/tmux-plugins/tpm/blob/master/docs/managing_plugins_via_cmd_line.md):\n\n```\n$ ~.tmux/plugins/tpm/bin/install_plugins\n```\n\nBasic usage\n-----------\n\nOnce plugged in, tmux `status-left` or `status-right` options can be configured with following placeholders. Each placeholder will be expanded to metric's default output.\n\n- `#{sysstat_cpu}`, CPU usage - `CPU:40.2%`\n- `#{sysstat_mem}`, memory usage - `MEM:73%`\n- `#{sysstat_swap}`, swap usage - `SW:66%`\n- `#{sysstat_loadavg}`, system load average - `0.25 0.04 0.34`\n\nFor example:\n```\nset -g status-right \"#{sysstat_cpu} | #{sysstat_mem} | #{sysstat_swap} | #{sysstat_loadavg} | #[fg=cyan]#(echo $USER)#[default]@#H\"\n```\n\nChanging default output\n------------------------\n\nYou can change default output for CPU and memory metrics, if you need more fields to show, or you want to provide custom template. In your `.tmux.conf`:\n\nFor example, to get `Used 4.5G out of 16G` output for memory metric:\n\n```\nset -g @sysstat_mem_view_tmpl '#Used [fg=#{mem.color}]#{mem.used}#[default] out of #{mem.total}'\n```\n\nIf you don't want `CPU:` prefix and don't like colored output for CPU metric:\n\n```\nset -g @sysstat_cpu_view_tmpl '#{cpu.pused}'\n```\n\n### Supported fields\n\nAs you can see, each metric can be configured with template, containing fixed text (`CPU:`), color placeholder (`#[fg=#{mem.color}]`) and field placeholder (`#{mem.used}`). This approach gives you the ultimate control over the output for each metric. Following field placeholders are supported:\n\n\u003ctable\u003e\n    \u003cth\u003eCPU\u003c/th\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e#{cpu.color}\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003emain metric color\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e#{cpu.pused}\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eCPU usage percentage\u003c/td\u003e\n    \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003ctable\u003e\n    \u003cth\u003eMemory\u003c/th\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e#{mem.color}\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003emain metric color\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e#{mem.free}\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003efree/available memory\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e#{mem.pfree}\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003efree memory percentage against total\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e#{mem.used}\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eused memory\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e#{mem.pused}\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eused memory percentage against total\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e#{mem.total}\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003etotal installed memory\u003c/td\u003e\n    \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003ctable\u003e\n    \u003cth\u003eSwap\u003c/th\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e#{swap.color}\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003emain swap metric color\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e#{swap.free}\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003efree swap memory\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e#{swap.pfree}\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003efree swap memory percentage against total swap space\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e#{swap.used}\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eused swap memory\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e#{swap.pused}\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eused swap memory percentage against total swap space\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e#{swap.total}\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003etotal swap space\u003c/td\u003e\n    \u003c/tr\u003e\n\u003c/table\u003e\n\n### Change size scale\n\nfree/used/total memory can be shown both in absolute and relative units. When it comes to absolute units, you can choose *size scale factor* to choose between GiB, MiB, KiB. Default is GiB. If you have less than 3-4G memory installed, it makes sense to use MiB. KiB option is less practical, because it yields pretty lengthy output, which does not fit status bar limited estate.\n\n```\nset -g @sysstat_mem_size_unit \"G\"\n```\n\nIf you choose `G` for size scale, output will have `%.1f` (1 digit after floating point), otherwise size is integer (4.5G, 1024M, 1232345K).\n\nThresholds and colored output\n---------------\nEach metric output is colored by default. Colors vary depending on metric value.\n\n\u003ctable\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e\u003cb\u003eThreshold\u003c/b\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cb\u003eCPU\u003c/b\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cb\u003eMemory\u003c/b\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cb\u003eSwap\u003c/b\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cb\u003eDefault color\u003c/b\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003elow\u003c/td\u003e\n        \u003ctd\u003ex \u0026lt; 30%\u003c/td\u003e\n        \u003ctd\u003ex \u0026lt; 75%\u003c/td\u003e\n        \u003ctd\u003ex \u0026lt; 25%\u003c/td\u003e\n        \u003ctd\u003egreen\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003emedium\u003c/td\u003e\n        \u003ctd\u003e30% \u0026lt; x \u0026lt; 80%\u003c/td\u003e\n        \u003ctd\u003e75% \u0026lt; x \u0026lt; 90%\u003c/td\u003e\n        \u003ctd\u003e25% \u0026lt; x \u0026lt; 75%\u003c/td\u003e\n        \u003ctd\u003eyellow\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003ehigh\u003c/td\u003e\n        \u003ctd\u003ex \u0026gt; 80%\u003c/td\u003e\n        \u003ctd\u003ex \u0026gt; 90%\u003c/td\u003e\n        \u003ctd\u003ex \u0026gt; 75%\u003c/td\u003e\n        \u003ctd\u003ered\u003c/td\u003e\n    \u003c/tr\u003e\n\u003c/table\u003e\n\nYou can change thresholds in your `.tmux.conf`:\n\n```\nset -g @sysstat_cpu_medium_threshold \"75\"\nset -g @sysstat_cpu_stress_threshold \"95\"\n\nset -g @sysstat_mem_medium_threshold \"85\"\nset -g @sysstat_mem_stress_threshold \"95\"\n\nset -g @sysstat_swap_medium_threshold \"80\"\nset -g @sysstat_swap_stress_threshold \"90\"\n```\n\nYou can change colors for each threshold individually. You can use ANSI basic colors (red, cyan, green) or if your terminal supports 256 colors (and most do nowadays), use `colourXXX` format.\n\n```\nset -g @sysstat_cpu_color_low \"colour076\"\nset -g @sysstat_cpu_color_medium \"colour220\"\nset -g @sysstat_cpu_color_stress \"colour160\"\nset -g @sysstat_mem_color_low \"green\"\nset -g @sysstat_mem_color_medium \"blue\"\nset -g @sysstat_mem_color_stress \"cyan\"\n```\n\n`#{(mem|cpu|swap).color}` placeholder in your `@sysstat_(mem|cpu|swap)_view_tmpl` would be replaced by corresponding color, depending on whether metric value falls in particular threshold.\n\n### 256 color palette support\n\nFor 256 color palette support, make sure that `tmux` and parent terminal are configured with correct terminal type. See [here](https://unix.stackexchange.com/questions/1045/getting-256-colors-to-work-in-tmux) and [there](https://github.com/tmux/tmux/wiki/FAQ)\n\n```\n# ~/.tmux.conf\nset -g default-terminal \"screen-256color\"\n```\n\n```\n# parent terminal\n$ echo $TERM\nxterm-256color\n\n# jump into a tmux session\n$ tmux new\n$ echo $TERM\nscreen-256color\n```\n\n\n\n### Multiple colors for each threshold\n\nYou can have up to *3* colors configured for each threshold. To understand why you might need this, let tackle this task. Note, this is rather advanced use case.\n\n\u003e I want `CPU: #{cpu.pused}` metric output, have green and yellow text colors at \"low\" and \"medium\" threshold, and finally, for \"high\" threshold, I want to use red color, but reverse foreground and background, that is use red for background, and white for text. More over I want \"CPU:\" text colored apart in red\n\nLike this:\n\n![cpu threshold with custom colors](/screenshots/cpu_thresholds.png)\n\nYou can achieve the result using following configuration:\n\n```\nset -g @sysstat_cpu_view_tmpl '#[fg=#{cpu.color3}]CPU:#[default] #[fg=#{cpu.color},bg=#{cpu.color2}]#{cpu.pused}#[default]'\n\nset -g @sysstat_cpu_color_low \"$color_level_ok default default\"\nset -g @sysstat_cpu_color_medium \"$color_level_warn default default\"\nset -g @sysstat_cpu_color_stress \"white,bold $color_level_stress $color_level_stress\"\n```\n\nTmux status-interval setting\n-----------------------------\nYou can configure status refresh interval, increasing or reducing frequency of `tmux-plugin-sysstat` command invocations.\n\n```\nset -g status-interval 5\n```\n\nIt's adviced to set `status-interval` to some reasonable value, like 5-10 seconds. More frequent updates (1 second) are useless, because they distract, and results in extra resource stress spent on metrics calculation itself.\n\n\n\nInternals: CPU calculation\n--------------------------------------------------\n\u003cspan style=\"color: blue\"\u003e**NOTE:** Stop here if you want to just use this plugin without making your feet wet. If you're hardcore tmux user and are curious about internals, keep reading\u003c/span\u003e\n\nInternally, we use `iostat` and `top` on OSX, and `vmstat` and `top` on Linux to collect metric value. Neither requires you to install extra packages. These commands are run in sampling mode to report stats every N seconds M times. First sample include average values since the system start. Second one is the average CPU per second for last N seconds (exactly what we need)\n\nFor example:\n\n```\n$ iostat -c 2 -w 5\n          disk0       cpu     load average\n    KB/t tps  MB/s  us sy id   1m   5m   15m\n   44.22   6  0.26   3  2 95  1.74 1.90 2.15\n    5.47   8  0.04   4  5 91  1.84 1.92 2.16  \u003c\u003c use this row, 2nd sample\n```\n\nWe align CPU calculation intervals (`-w`) with tmux status bar refresh interval (`status-interval` setting).\n\nInternals: memory calculation\n----------------------------\nYou might ask what we treat as `free` memory and how it's calculated.\n\n### OSX\nLet's start with OSX. We use `vm_stat` command (not same as `vmstat` on Linux), which reports following data (number of memory pages, not KB):\n\n```\n$ vm_stat\nPages free:                               37279\nPages active:                           1514200\nPages inactive:                         1152997\nPages speculative:                         6214\nPages throttled:                              0\nPages wired down:                       1174408\nPages purgeable:                          15405\nPages stored in compressor:             1615663\nPages occupied by compressor:            306717\n```\n\nTotal installed memory formula is:\n```\nTotal = free + active + inactive + speculative + occupied by compressor + wired\n```\n\nwhere\n- `free`, completely unused memory by the system\n- `wired`, critical information stored in RAM by system, kernel and key applications. Never swapped to the hard drive, never replaced with user-level data.\n- `active`, information currently in use or very recently used by applications. When this kind of memory is not used for long (or application is closed), it's move to inactive memory.\n- `inactive`, like buffers/cached memory in Linux. Memory for applications, which recently exited, retained for faster start-up of same application in future.\n\nSo the question what constitutes `free` and `used` memory. It turns out, that various monitoring and system statistics tools on OSX each calculate it differently.\n\n- htop: `used = active + wired`, `free` = `total - used`\n- top. Used = `used = active + inactive + occupied by compressor + wired`; Free = `free + speculative` Resident set size (RSS) = `active`\n- OSX activity Monitor. Used = `app memory + wired + compressor`. Note, it's not clear what is app memory.\n\nIn general, they either treat currently used memory, which can be reclaimed in case of need (cached, inactive, occupied by compressor), as `used` or `free`. \n\nIt makes sense to talk about `available` memory rather than `free` one. Available memory is unused memory + any used memory which can be reclaimed for application needs.\n\nSo, `tmux-plugin-sysstat`, uses following formula:\n\n```\nused = active + wired\navailable/free = free/unused + inactive + speculative + occupied by compressor\n```\n\n### Linux\n\nSame thinking can be applied to Linux systems.\n\nUsually commands like `free` report free/unused, used, buffers, cache memory kinds.\n\n```\n$ free\n             total       used       free     shared    buffers     cached\nMem:       1016464     900236     116228      21048      93448     241544\n-/+ buffers/cache:     565244     451220\nSwap:      1046524     141712     904812\n```\n\nSecond line indicates available memory (free + buffers + cache), with an assumption that buffers and cache can be 100% reclaimed in case of need.\n\nHowever, we're not using free, because its output varies per system. For example on RHEL7, there is no `-/+ buffers/cache`, and `available` memory is reported in different way. We read directly from `/proc/meminfo`\n\n```\n$ cat /proc/meminfo\n\nMemTotal:        1016232 kB\nMemFree:          152672 kB\nMemAvailable:     637832 kB\nBuffers:               0 kB\nCached:           529040 kB\n```\n\n`tmux-plugin-sysstat` uses following formula:\n\n```\nfree/available = MemAvailable;  // if MemAvailable present\nfree/available = MemFree + Buffers + Cached;\nused = MemTotal - free/avaialble \n```\n\nUsing `MemAvailable` is more accurate way of getting available memory, rather than manual calculation `free + buffers + cache`, because the assumption that `buffers + cache` can be 100% reclaimed for new application needs might be wrong. When using `MemAvailable`, OS calculates available memory for you, which is apparently better and accurate approach.\n\nSee [this topic](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=34e431b0ae398fc54ea69ff85ec700722c9da773) on more reasoning about `MemAvailable` field.\n","funding_links":[],"categories":["Shell"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamoshkin%2Ftmux-plugin-sysstat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamoshkin%2Ftmux-plugin-sysstat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamoshkin%2Ftmux-plugin-sysstat/lists"}