Skip to content

v0.3.0 — engram tui (interactive multi-tab dashboard)

Choose a tag to compare

View all tags
@kooroot kooroot released this 15 Apr 05:05
· 52 commits to main since this release
v0.3.0
f08b1b3

The static `engram usage` view from v0.2.x grows up into a full interactive dashboard.

Try it

bun install -g @kooroot/engram@latest
engram tui

What's new

`engram tui` — full-screen multi-tab UI built with ink + react. The static `engram usage` / `engram doctor` / `engram status` commands still work unchanged for scripting.

Tabs

1. Stats — the marquee tab

  • 14-week activity heatmap (orange gradient, GitHub-style)
  • Period pills: `Last 24h · Last 7d · Last 30d · All time` (cycle with `r`)
  • Stats grid: total tokens, calls, sessions, active days, longest session, longest streak, current streak, most active day, favorite tool
  • `t` toggles a per-tool mini bar chart

2. Usage — every existing breakdown made interactive

  • Period pills (`r` to cycle) + breakdown pills (`b` to cycle: by tool / by day / by namespace) + `a` to toggle all-namespaces
  • Bar chart that swaps content as you flip switches

3. Browse — first browse UI for the memory graph

  • Lists active nodes with arrow-key cursor
  • `t` cycles type filter (all → person → project → … → all)
  • `enter` opens a detail view with properties + outgoing/incoming edges
  • `esc` / `q` / `enter` from detail returns to list

4. Status — the parts of `engram doctor` that change frequently

  • Active/archived nodes, edges, events
  • Current namespace + data dir + embedding provider
  • Provider-specific config (Ollama URL/model/dim, shell command)

Global keys

  • `tab` / `shift-tab` — next / prev tab
  • `1`-`4` — jump directly to a tab
  • `?` — toggle help panel
  • `q` or `ctrl-c` — quit

Implementation

  • ink ^7 + react ^19 added as runtime deps; @types/react as dev dep
  • tsconfig: `jsx: react-jsx`, `jsxImportSource: react`
  • `src/tui/index.tsx` hosts the App + global TabBar + Footer
  • Each tab is its own `.tsx` file, takes `core: EngramCore` as the only prop
  • Auto-refresh tick every 5 s so heatmap/stats stay live with another shell still actively writing to the engram db
  • TTY guard in `src/cli/tui.ts` — non-TTY exits cleanly with a message pointing at `engram usage --plain` for scripts

Compatibility

  • Node.js ≥ 20
  • macOS, Linux (Windows via WSL2)
  • Existing data unchanged — uses the same `usage_log` table from v0.2.0
  • Install size grows ~400KB (ink + react)
Assets 2
Loading