Skip to main content

beachcomber

A single daemon that caches your shell environment. Every prompt, status bar, and editor reads from one shared cache instead of recomputing everything independently.

GitHub Starscrates.io downloadsnpm downloadsPyPI downloads
Without beachcomberWith beachcomber
960
threads
30
watchers
312
handles
30.9ms
latency
4
threads
1
watcher
12
handles
15µs
latency
The problem

Your terminal is doing insane amounts of duplicate work

Open Activity Monitor on a typical dev machine and look at what's running. Every shell prompt has its own git status daemon. Your tmux status bar forks a shell process for every pane on a timer. Your editor has its own file watchers. Your prompt framework has another set. Each one independently computing the same answer to the same question: "what branch am I on?"

Scale it up: 30 terminal panes means 30 git daemons, each with a thread pool — that's hundreds of threads. fseventsd is dispatching every filesystem change to 30 separate watchers all monitoring the same .git directory. Hundreds of open file handles, constant CPU churn, and every single one of them returns the same answer.

Nothing talks to anything else. Every consumer — prompts, status bars, editors, scripts — operates in total isolation, duplicating work that only needs to happen once.

beachcomber is a local memoization cache for shell environment state. One daemon watches your filesystem, computes state once, and serves it from memory. Providers automatically back off when not queried, and warm up again on demand. One watcher. One computation. Infinite readers.

Performance

The speed difference is absurd

gitstatus daemon
30.9ms
raw git status
5.6ms
beachcomber
15µs
Without beachcomber
960 threads
30 shells running gitstatusd, all computing the same answer
500 forks / 10s
tmux status bars forking processes to collect battery, hostname, and git data
2.5s CPU
wasted every minute on duplicate environment queries across tools
With beachcomber
1 daemon
one beachcomber process serves every shell, editor, and status bar on the machine
15µs queries
cached reads over a Unix socket — faster than a syscall to disk
45k req/sec
sustained throughput on a single socket with zero coordination overhead
0

queries served by beachcomber in the time it takes gitstatus to return one result

How it works

How it works

beachcomber is a single async daemon. It watches directories using native OS APIs, runs providers when files change or timers fire, and caches results in a shared in-memory map. Every consumer reads from the same cache via a Unix socket.

$ comb get git.branch . -f text
main← 15µs
$ comb get battery.percent -f text
85
$ comb status
{"cache_entries": 12, "active_watchers": 3, "demand": 8}
Built-in

16 built-in providers

Plus a script backend for anything else

git
~5.6ms
branchdirtystagedunstagedaheadbehindstash
hostname
~400ns
user
~650ns
load
~550ns
uptime
~660ns
kubecontext
<1µs
gcloud
<1µs
aws
<1µs
conda
<1µs
terraform
<1µs
python
<1µs
asdf
<1µs
direnv
varies
mise
varies
network
~2ms
battery
~6ms
Ecosystem

Ecosystem

beachcomber is infrastructure, not a prompt theme

Integrations
zshbashfishtmuxneovimstarshippolybarwaybarsketchybaroh-my-posh
Client SDKs

All stdlib-only. Published to their native registries.

Get started

Get started

The daemon starts automatically on first query. Integrate with your prompt, status bar, or editor to start seeing the benefits.

$ brew install beachcomber