beachcomber 0.2.0

A centralized daemon that caches shell state (git, battery, hostname, etc.) so every consumer reads from one fast cache instead of independently forking shells
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

---
sidebar_position: 3
---

# How It Works

beachcomber is a single async daemon that:

1. Serves queries from consumers (prompts, status bars, editors) via a Unix socket
2. Watches filesystem directories using native FSEvents (macOS) or inotify (Linux)
3. Executes providers when files change or poll timers fire — not on every query
4. Caches results in a shared in-memory map (157ns reads)
5. Returns cached data instantly to any number of concurrent readers

The daemon is socket-activated: it starts automatically when any client connects, and shuts down after an idle period when all connections drop.

```
                    ┌─────────────────────────────────────┐
                    │          beachcomber daemon           │
                    │                                       │
  filesystem ──────►│  FSEvents/inotify                     │
  changes           │       │                               │
                    │       ▼                               │
                    │  Scheduler ──► Providers ──► Cache   │
                    │                  git          157ns   │
                    │                  battery      reads   │
                    │                  network              │
                    │                  hostname             │
                    │                  ...                  │
                    │                  scripts              │
                    │                  (your own)           │
                    │                                       │
                    │  Unix Socket Server                   │
                    └──────────────┬──────────────────────-┘
                                   │
                    ┌──────────────┼────────────────────┐
                    │              │                     │
               zsh prompt     tmux status           neovim
               bash prompt    polybar/waybar         lualine
               fish prompt    sketchybar             scripts
               starship       oh-my-posh             CI/automation
```

**Providers are never re-executed on every query.** A git status is computed once when `.git` changes, then served from cache to every reader — whether that's one prompt or a hundred tmux panes. The filesystem watcher is registered once for all concurrent readers.

**Connection context** means consumers can set a working directory once on connect. `comb get git.branch` without an explicit path uses the connection's context directory, making prompt integration natural.

**Demand-driven lifecycle:** the daemon watches nothing until queried. Each `get` request signals demand, keeping the provider warm automatically. Resource usage scales with actual query patterns. Entries enter a backoff/drain sequence after queries stop — staying warm for a grace period (30s default) in case a new shell opens, then progressively slowing and eventually evicting.