Add synchronized TUI mode

Author: LyleMi

README.md

@@ -15,7 +15,11 @@ AgentMeter is a local-first dashboard for understanding coding-agent session usa
 tokens, estimated cost, timing, session history, and tool-call behavior.
 
 It reads local agent JSONL session files, indexes them into SQLite, and shows the data
-in a private local browser UI. No proxy, no cloud service, no telemetry.
+in private local Web and terminal interfaces. No proxy, no cloud service, no telemetry.
+
+The Web UI is the default MVP interface. The TUI is available as a terminal MVP
+over the same local database, indexing pipeline, pricing rules, and query
+semantics.
 
 ## Why AgentMeter
 
@@ -41,6 +45,8 @@ can actually use:
 - Incremental indexing based on path, size, modified time, and content hash.
 - Built-in pricing registry with unknown models clearly marked as `unpriced`.
 - Local Go HTTP server with a Vue 3 + Vite frontend.
+- TUI mode for terminal workflows, kept in sync with the Web UI through shared
+  backend/query behavior.
 
 ## Privacy Model
 
@@ -110,6 +116,43 @@ Open:
 http://127.0.0.1:34115
 ```
 
+### UI Modes
+
+Web mode remains the default:
+
+```powershell
+go run . -http 127.0.0.1:34115
+```
+
+You can select a mode explicitly:
+
+```powershell
+go run . -ui web -http 127.0.0.1:34115
+go run . -ui web -static frontend/dist
+go run . -ui tui
+```
+
+Behavior:
+
+- `-ui web` starts the local HTTP API and browser dashboard.
+- `-ui tui` starts the terminal UI without opening a browser or HTTP listener.
+- Web remains the default for compatibility with the MVP.
+- `-http` and `-static` apply to Web mode.
+- Both modes must use the same SQLite data, pricing rules, filters, and usage
+  calculations.
+
+TUI keys:
+
+```text
+1-4 / tab  switch screens
+up/down    select or scroll
+enter      open selected session detail
+b / esc    back from detail
+r          refresh current screen
+i / I      index now / rebuild index
+q          quit
+```
+
 For frontend development with Vite hot module reload, run the backend and
 frontend dev server in separate terminals:
 
@@ -152,21 +195,39 @@ already includes:
 - Normalized sessions, events, token usage, model calls, and tool calls.
 - Vue 3 + TypeScript frontend using Ant Design Vue and ECharts.
 - MVP screens for Overview, Sessions, Session Detail, Tools, and Settings.
+- TUI mode with Overview, Sessions, Session Detail, Tools, Settings, refresh,
+  and index actions over the same application services.
 
 ## Development Checks
 
+Run the shared backend checks:
+
+```powershell
+go test ./...
+```
+
+Run the Web build check:
+
 ```powershell
 cd frontend
 npm ci
 npm run build
 cd ..
-
-go test ./...
 ```
 
+For TUI changes, run the backend tests and a terminal smoke check covering
+startup, keyboard navigation, resize behavior, indexing, and parity for Overview
+totals, Session Detail values, and Tools aggregates against Web mode for the
+same database.
+
+When shared query behavior changes, update both UI expectations in the same
+change: Web views, TUI screens, README command examples, and
+`docs/ui-modes.md`.
+
 ## Roadmap
 
-Planned directions include packaged builds, more coding-agent adapters, export formats, project grouping, custom pricing, and
+Planned directions include richer TUI filters, packaged builds, more
+coding-agent adapters, export formats, project grouping, custom pricing, and
 richer timeline views.
 
 See [Roadmap](docs/roadmap.md) for details.
@@ -175,6 +236,7 @@ See [Roadmap](docs/roadmap.md) for details.
 
 - [Project Brief](docs/project-brief.md)
 - [Architecture](docs/architecture.md)
+- [UI Modes](docs/ui-modes.md)
 - [Data Model](docs/data-model.md)
 - [Codex Session Format](docs/codex-session-format.md)
 - [Roadmap](docs/roadmap.md)

docs/architecture.md

@@ -2,7 +2,13 @@
 
 ## Decision
 
-Use a Go HTTP backend, SQLite storage, and a Vue 3 + Vite + TypeScript frontend.
+Use a Go application core with SQLite storage, shared query services, and two
+local interfaces:
+
+- Web UI: the current Vue 3 + Vite + TypeScript browser dashboard served by the
+  Go HTTP backend.
+- TUI: a terminal interface over the same app services, database, pricing rules,
+  and query semantics.
 
 ## Why Go HTTP + Vite
 
@@ -17,10 +23,17 @@ During development, Vite serves the frontend and proxies `/api` to the Go
 backend. For local production use, the Go server can serve the built
 `frontend/dist` assets from disk.
 
+The HTTP API remains the Web mode boundary. TUI mode should not require a
+separate ingestion path or a second persistence layer.
+
 ## High-level Components
 
 ```text
 AgentMeter
+  interfaces
+    web dashboard
+    terminal UI
+
   frontend
     Vue views
     charts
@@ -34,7 +47,7 @@ AgentMeter
     ingestion pipeline
     SQLite repository
     pricing service
-    query service
+    shared query service
     export service
 
   storage
@@ -68,6 +81,8 @@ internal/
   model/
   pricing/
   query/
+  tui/
+  viewmodel/
   export/
   platform/
 ```
@@ -81,12 +96,14 @@ Responsibilities:
 - `model`: normalized domain structs.
 - `pricing`: model aliases, pricing table, cost calculation.
 - `query`: read models for UI screens.
+- `viewmodel`: shared display formatting and presenter helpers for UI parity.
+- `tui`: terminal UI mode over `app.App`.
 - `export`: JSON and CSV export.
 - `platform`: OS-specific database and default source path discovery.
 
 ## UI Shape
 
-MVP screens:
+The Web and TUI interfaces should cover the same product areas:
 
 - Overview
 - Sessions
@@ -114,6 +131,48 @@ Session Detail should show:
 - tool calls;
 - raw source path.
 
+The Web UI can use charts, wide layouts, and browser affordances. The TUI can
+use tables, panes, keyboard navigation, and compact summaries. Differences in
+presentation are acceptable; differences in totals, filters, status labels, or
+drill-down semantics are not.
+
+## Interface Synchronization
+
+Web and TUI modes should stay synchronized by design:
+
+- Token totals, cost estimates, durations, model normalization, and status
+  labels come from shared backend logic.
+- Overview, Sessions, Session Detail, Tools, Settings, and Pricing data use
+  shared query semantics.
+- Filtering and sorting rules should not be reimplemented with different
+  behavior in each UI.
+- New shared user-visible behavior should update both interface expectations in
+  the same change.
+- Documentation for command examples and UI capabilities should be updated with
+  the implementation state.
+
+## Command Line
+
+Default Web command:
+
+```powershell
+go run . -http 127.0.0.1:34115
+```
+
+Interface selector:
+
+```powershell
+go run . -ui web -http 127.0.0.1:34115
+go run . -ui web -static frontend/dist
+go run . -ui tui
+```
+
+Behavior:
+
+- `web` is the default mode for MVP compatibility.
+- `-http` and `-static` apply to Web mode.
+- TUI mode runs in the terminal and does not start an HTTP listener.
+
 ## Runtime Rules
 
 - AgentMeter must not modify source session files.

docs/project-brief.md

@@ -33,7 +33,20 @@ The current version supports:
 - session duration from local JSONL timestamps;
 - tool-call statistics from local session events;
 - SQLite indexing;
-- local browser UI.
+- local browser UI;
+- synchronized terminal UI MVP.
+
+## Interface Direction
+
+AgentMeter should support two local interfaces over one shared application core:
+
+- Web UI for the current dashboard-oriented experience.
+- TUI for terminal-first workflows, SSH sessions, and users who prefer staying
+  inside a shell.
+
+The two interfaces should share the same database, indexing pipeline, pricing
+rules, query semantics, and user-visible definitions for tokens, cost, duration,
+status, filters, and session identity.
 
 ## Non-goals For MVP
 
@@ -44,6 +57,7 @@ The current version supports:
 - Remote database.
 - Automatic uploads or telemetry.
 - Complex eval workflows.
+- Divergent Web-only and TUI-only business logic for the same usage concepts.
 
 ## User
 
@@ -68,7 +82,7 @@ The first user is a developer who uses local coding agents and wants to understa
 
 ## First Usable Version
 
-The first useful build should let a user open AgentMeter, point it at one or
+The first useful Web build should let a user open AgentMeter, point it at one or
 more local agent data directories if needed, index sessions, and inspect:
 
 - overview totals;
@@ -77,3 +91,7 @@ more local agent data directories if needed, index sessions, and inspect:
 - session detail timeline;
 - model usage;
 - tool-call counts and durations.
+
+The first useful TUI build exposes the same core data in a terminal: Overview
+totals, session list, session detail, tool aggregates, settings, index trigger,
+and clear parse/pricing status labels.

docs/roadmap.md

@@ -60,9 +60,9 @@ Deliverables:
 - session rows in SQLite;
 - parser test coverage.
 
-## Phase 3: MVP UI
+## Phase 3: MVP Web UI
 
-Goal: make the indexed data useful.
+Goal: make the indexed data useful in the browser.
 
 Screens:
 
@@ -83,9 +83,47 @@ Tasks:
 
 Deliverables:
 
-- usable local dashboard for local coding-agent sessions.
+- usable local Web dashboard for local coding-agent sessions.
 
-## Phase 4: Packaging
+## Phase 4: TUI Mode
+
+Goal: keep the terminal interface useful without splitting AgentMeter into two
+products.
+
+Interface contract:
+
+- Web mode remains the default MVP path.
+- TUI mode uses the same SQLite database, pricing rules, indexing pipeline, and
+  query semantics as Web mode.
+- UI differences are presentational only: terminal tables and panes can replace
+  charts, but totals, filters, statuses, and drill-down meaning must match Web.
+
+Implemented command line:
+
+```text
+go run . -ui web -http 127.0.0.1:34115
+go run . -ui web -static frontend/dist
+go run . -ui tui
+```
+
+Delivered:
+
+- Add `-ui web|tui` mode selection while keeping Web as the default.
+- Define shared display helpers for formatting, status classification, Overview
+  derived metrics, and Tools summary.
+- Implement TUI navigation, table browsing, and session detail panes.
+- Support an index trigger and visible indexing/parse status in TUI mode.
+- Add terminal resize and narrow-width behavior.
+- Document TUI keyboard behavior and README examples.
+
+Remaining:
+
+- Add search/filter entry in TUI Sessions.
+- Add parity checks comparing Web and TUI values for the same database.
+- Improve compact visual treatment for pricing, parse status, and long paths.
+- Add terminal smoke checks to release validation.
+
+## Phase 5: Packaging
 
 Goal: make cross-platform usage easy.
 
@@ -95,6 +133,7 @@ Tasks:
 - macOS portable build.
 - Linux portable build.
 - Installer or portable zip.
+- Package both Web and TUI modes from the same binary when TUI mode is ready.
 - Local database path decision.
 - Log file location.
 - Basic crash/error reporting to local logs only.
@@ -103,7 +142,7 @@ Deliverables:
 
 - Windows release artifact.
 
-## Phase 5: Beyond MVP
+## Phase 6: Beyond MVP
 
 Possible additions:
 
@@ -116,4 +155,5 @@ Possible additions:
 - richer model-call timeline.
 - project grouping.
 - custom pricing UI.
+- TUI command palette and saved filter shortcuts.
 - dark/light theme.