---
title: Monitor
description: Reading and using the live TUI dashboard.
---
# Monitor
Running `kache` with no arguments (or `kache monitor`) opens a live TUI dashboard that shows what's happening in your cache in real time. It refreshes automatically and doesn't require the daemon to be running: the monitor makes a best-effort attempt to start one in the background for richer stats, but still works via direct store and event-log reads if the daemon is unavailable (the Transfer line then reads `n/a (daemon offline)`).
Static layout for reference:
```text
[1] Build [2] Projects [3] Store [4] Transfer [5] Passthrough
┌ kache monitor ────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Store: 45.0 GiB / 50.0 GiB [ 90.1%] 11004 entries │
│ Hit rate: 61% count | 42% weighted | 79% miss-time Remote: not configured │
│ Dedup: 8.2 GiB saved (18.1%) Blobs: 36.9 GiB physical Hardlinks: 4.9 GiB via 7023 hardlinks Scan: idle │
│ Transfer: ↑ 0 uploading ↓ 0 downloading │
│ rustc-wrapper=kache via ~/.cargo/config.toml ✓ unknown │
│ kache vX.Y.Z (epoch 1777305862) daemon: vX.Y.Z (epoch 1777305862) Cache: ~/Library/Caches/kache │
│ │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
┌ Live Build ───────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
┌ Hit Rate (recent) ────────────────────────────────────────────────────────────────────────────────────────────────┐
│ No data yet │
│ │
│ │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
q: quit f: filter ↑↓: scroll Tab: next c: clear 1-5: tabs
```
## Header
The header line at the top of the monitor shows the current state of your local store and remote:
| Field | What it means |
|---|---|
| `Store` | Bytes used vs. the configured maximum (`KACHE_MAX_SIZE`) |
| `Hit rate` | Three headline rates over the window: `count` (% of builds served from cache), `weighted` (% of compile-time saved), and `miss-time` (% of wall-time spent in misses). Falls back to `local \| remote \| miss` percentages when compile-time data is unavailable |
| `Dedup` | Logical bytes saved by storing shared blobs once |
| `Blobs` | Physical bytes used by blob files in the local store |
| `Hardlinks` | Unix-only inode-link scan: extra bytes saved because store blobs are hardlinked into `target/` instead of copied. Reads `none — restores prefer reflink/CoW` on copy-on-write filesystems (APFS, btrfs, XFS-with-reflink), where restores are reflinks (independent inodes) and the real savings show up under `Dedup` instead — a zero here is not a problem |
| `Scan` | Whether the background hardlink scan is still calculating, scanning, or idle |
| `Transfer` | Number of uploads and downloads currently in-flight via the daemon |
## Tabs
### 1 — Build
A live event stream showing every rustc invocation kache handled, as a table with Status (outcome glyph + word), Crate, Action (what kache actually did — built+cached / restored / downloaded), Compile (compile-phase time, shown only for misses and dups), Total (wall time), and Size. New events appear at the bottom.
`dup` means the cache key missed and the compiler ran, but every unique output
blob already existed in the local store before the store step. It is a
diagnostic signal for over-specific keys or noisy inputs, but it still counts as
compiled work rather than a cache hit.
This is separate from the `Dedup` storage metric. `Dedup` estimates hardlink and
content-addressed storage savings; `dup` identifies compiles that produced
already-known bytes under a different cache key.
The `--since` flag controls how far back the event log is read when the monitor opens:
```sh
kache monitor --since 1h # show last hour
kache monitor --since 7d # show last 7 days
```
Press `f` to filter the event list by crate name. Press `c` to clear it.
### 2 — Projects
A list of `target/` directories kache has linked artifacts into, with their total disk usage and link status. This gives you a quick view of which projects are using disk space.
Press `r` to refresh the project list (it doesn't auto-refresh because scanning target directories is expensive).
### 3 — Store
A table of all cached crate entries, sortable by name, size, hits, or age. Use this to see what's actually in the cache and identify large or stale entries before running GC.
Press `s` to cycle the sort order (size → hits → age → name). Press `f` to filter by crate name or cache key.
### 4 — Transfer
A log of recent S3 uploads and downloads, with transfer rates and artifact sizes. Useful for verifying that the daemon is uploading new artifacts and that remote hits are flowing in correctly.
### 5 — Passthrough
A table of invocations kache passed through instead of caching. Each row shows the time, crate, route (`fallback` if a configured fallback wrapper handled it, else `direct`), exit code, and the reason kache declined to cache it.
## Keyboard shortcuts
```
q quit
Tab next tab
1 / 2 / 3 / 4 / 5 switch to tab by number
↑ / ↓ scroll
f filter (Build, Store, and Passthrough tabs)
s cycle sort order (Store tab)
c clear build event list (Build tab)
r refresh project list (Projects tab)
```
## Quick triage
**High miss rate when the daemon is offline.**
The remote cache isn't being checked. Start the daemon (`kache daemon start`) and verify it can reach the S3 bucket. Check `kache daemon log` for errors.
**Store usage is near the maximum.**
Run `kache gc` to evict the least-recently-used entries, or `kache gc --max-age 7d` to remove anything older than a week. You can also raise `KACHE_MAX_SIZE` if disk space allows.
**Remote is configured but Transfer tab shows no activity.**
The daemon may not be running, or credentials may be wrong. Check `kache daemon` status and verify the remote config with `kache doctor`.
**A specific crate keeps missing.**
Run `kache why-miss <crate-name>` to see which input to the cache key changed since the last recorded entry.