---
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.
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 v0.1.0 (epoch 1777305862) daemon: v0.1.0 (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` | Breakdown of cache outcomes over the displayed window: local / prefetch / remote / miss |
| `Dedup` | Logical bytes saved by storing shared blobs once |
| `Blobs` | Physical bytes used by blob files in the local store |
| `Hardlinks` | Estimated bytes saved by hardlink sharing across project `target/` directories |
| `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, with outcome, crate name, elapsed time, and artifact size. New events appear at the bottom.
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 `f` to filter by crate name.
### 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 crate or source, whether the generic fallback path handled it, the 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)
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.