Overview

statline is a small CLI that takes a TOML config and a shell hint and prints a status line. That's really all it does. Everything else — caching, async probing, theming, integration with tmux/neovim — is built on top of that single contract.

If you're new, start with getting started. It walks you through installation, a minimal config, and hooking it into your shell in under two minutes.

How it works

On every prompt draw your shell invokes statline render. statline:

  • Loads ~/.config/statline/statline.toml (cached in memory for the lifetime of the process).
  • For each segment, reads the segment's current value from the TTL cache.
  • If the value is stale, kicks off a background refresh (returning the stale value immediately).
  • Renders the bar and writes it to stdout in one write(2).

The key property: render time is bounded. A probe that takes 3 seconds (kubectl config current-context on a laggy VPN) never stalls your prompt. You see the previous value, and the bar updates itself the next time you type a key.

A minimal config

# ~/.config/statline/statline.toml
theme = "tokyonight"

[[segment]]
type = "cwd"

[[segment]]
type = "git"

[[segment]]
type = "time"

Philosophy

Do the boring thing. Do it fast. Never, ever block the user's prompt.

This is why statline doesn't ship with a scripting language, doesn't autoload plugins, and doesn't try to be a general-purpose prompt framework. Those features are useful, but they cost you predictability — and a prompt that occasionally freezes for two seconds is worse than one that's slightly less clever.

Where to next