# neokn/session-lens architecture

> Architecture diagram of the GitHub repository neokn/session-lens, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/neokn/session-lens
- Repository: https://github.com/neokn/session-lens

## Overview

session-lens is a Claude Code mod that opens a live terminal pane for session usage, cost, context, agents, and activity. The `/session-lens` command enters through the registration layer; refresh and transcript-reading code gather session data, digest modules derive figures, and view templates render the pane. README capabilities also include event, effort, history, and design-token/component pages. The graph combines excerpted relationships, SOURCE INDEX references, and documented behavior; some README-described subsystems have only directory-level paths because their implementation was not sampled.

Main entry points: [`hooks/register.tsx`](https://github.com/neokn/session-lens/blob/main/hooks/register.tsx) (Command registration), [`hooks/record/transcript.ts`](https://github.com/neokn/session-lens/blob/main/hooks/record/transcript.ts) (Transcript reader), [`hooks/digest/record.ts`](https://github.com/neokn/session-lens/blob/main/hooks/digest/record.ts) (Record digest), [`hooks/digest/session.ts`](https://github.com/neokn/session-lens/blob/main/hooks/digest/session.ts) (Session digest)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Session collection"]
  node_transcript["Transcript reader<br/>[transcript.ts]"]
  node_children["Child discovery<br/>[children.ts]"]
end

subgraph group_analysis["Session analysis"]
  node_record["Record digest<br/>[record.ts]"]
  node_session["Session digest<br/>[session.ts]"]
  node_turns["Turn analysis<br/>[turns.ts]"]
  node_cost["Cost analysis<br/>[cost.ts]"]
  node_context["Context analysis<br/>[context.ts]"]
  node_autocompact["Compaction analysis<br/>[autocompact.ts]"]
  node_timeline["Timeline and events"]
  node_effort["Effort and forecast"]
end

subgraph group_pane["Pane orchestration"]
  node_registration["Command registration<br/>[register.tsx]"]
  node_refresh["Live refresh<br/>[refresh.ts]"]
  node_state["Pane state<br/>[state.ts]"]
end

subgraph group_presentation["Terminal presentation"]
  node_mainview["Session pane"]
  node_contextview["Context display<br/>[ContextGrid.tsx]"]
  node_costview["Cost tables<br/>[CostTable.tsx]"]
  node_waterfall["Turn waterfall<br/>[Waterfall.tsx]"]
  node_design["Design tokens<br/>[palette.ts]"]
  node_layout["Terminal layout<br/>[layout.ts]"]
  node_themes["Theme selection<br/>[theme.ts]"]
end

node_user(("Claude Code user"))
node_command(("/session-lens"))
node_report["Session report plugin"]

node_user -->|"runs"| node_command
node_command -->|"opens pane"| node_registration
node_registration -->|"starts refresh"| node_refresh
node_refresh -->|"reads transcript"| node_transcript
node_transcript -->|"discovers children"| node_children
node_transcript -->|"digests rows"| node_record
node_transcript -->|"builds session"| node_session
node_session -->|"uses record digest"| node_record
node_session -->|"uses turn analysis"| node_turns
node_turns -->|"scans records"| node_record
node_turns -->|"prices requests"| node_cost
node_record -->|"uses pricing"| node_cost
node_refresh -->|"updates state"| node_state
node_registration -->|"loads digest"| node_context
node_registration -->|"loads digest"| node_cost
node_registration -->|"loads digest"| node_autocompact
node_registration -->|"loads activity data"| node_timeline
node_registration -->|"loads effort data"| node_effort
node_registration -->|"renders pane"| node_mainview
node_registration -->|"renders context"| node_contextview
node_registration -->|"renders cost"| node_costview
node_registration -->|"renders turns"| node_waterfall
node_registration -->|"uses palette"| node_design
node_registration -->|"uses layout"| node_layout
node_registration -->|"selects theme"| node_themes
node_user -.->|"opens report"| node_report

click node_registration "https://github.com/neokn/session-lens/blob/main/hooks/register.tsx"
click node_refresh "https://github.com/neokn/session-lens/blob/main/hooks/refresh.ts"
click node_state "https://github.com/neokn/session-lens/blob/main/hooks/state.ts"
click node_transcript "https://github.com/neokn/session-lens/blob/main/hooks/record/transcript.ts"
click node_children "https://github.com/neokn/session-lens/blob/main/hooks/record/children.ts"
click node_record "https://github.com/neokn/session-lens/blob/main/hooks/digest/record.ts"
click node_session "https://github.com/neokn/session-lens/blob/main/hooks/digest/session.ts"
click node_turns "https://github.com/neokn/session-lens/blob/main/hooks/digest/turns.ts"
click node_cost "https://github.com/neokn/session-lens/blob/main/hooks/digest/cost.ts"
click node_context "https://github.com/neokn/session-lens/blob/main/hooks/digest/context.ts"
click node_autocompact "https://github.com/neokn/session-lens/blob/main/hooks/digest/autocompact.ts"
click node_timeline "https://github.com/neokn/session-lens/tree/main/hooks/digest"
click node_effort "https://github.com/neokn/session-lens/tree/main/hooks/digest"
click node_mainview "https://github.com/neokn/session-lens/tree/main/hooks/views/templates"
click node_contextview "https://github.com/neokn/session-lens/blob/main/hooks/views/organisms/ContextGrid.tsx"
click node_costview "https://github.com/neokn/session-lens/blob/main/hooks/views/organisms/CostTable.tsx"
click node_waterfall "https://github.com/neokn/session-lens/blob/main/hooks/views/organisms/Waterfall.tsx"
click node_design "https://github.com/neokn/session-lens/blob/main/hooks/views/palette.ts"
click node_layout "https://github.com/neokn/session-lens/blob/main/hooks/views/layout.ts"
click node_themes "https://github.com/neokn/session-lens/blob/main/hooks/theme.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_transcript,node_children,node_user toneBlue
class node_record,node_session,node_turns,node_cost,node_context,node_autocompact,node_timeline,node_effort toneAmber
class node_registration,node_refresh,node_state toneMint
class node_mainview,node_contextview,node_costview,node_waterfall,node_design,node_layout,node_themes toneRose
class node_command,node_report toneIndigo
```

## Components

### Session collection

- [Transcript reader](https://github.com/neokn/session-lens/blob/main/hooks/record/transcript.ts): `hooks/record/transcript.ts`
- [Child discovery](https://github.com/neokn/session-lens/blob/main/hooks/record/children.ts): `hooks/record/children.ts`

### Session analysis

- [Record digest](https://github.com/neokn/session-lens/blob/main/hooks/digest/record.ts): `hooks/digest/record.ts`
- [Session digest](https://github.com/neokn/session-lens/blob/main/hooks/digest/session.ts): `hooks/digest/session.ts`
- [Turn analysis](https://github.com/neokn/session-lens/blob/main/hooks/digest/turns.ts): `hooks/digest/turns.ts`
- [Cost analysis](https://github.com/neokn/session-lens/blob/main/hooks/digest/cost.ts): `hooks/digest/cost.ts`
- [Context analysis](https://github.com/neokn/session-lens/blob/main/hooks/digest/context.ts): `hooks/digest/context.ts`
- [Compaction analysis](https://github.com/neokn/session-lens/blob/main/hooks/digest/autocompact.ts): `hooks/digest/autocompact.ts`
- [Timeline and events](https://github.com/neokn/session-lens/tree/main/hooks/digest): `hooks/digest`
- [Effort and forecast](https://github.com/neokn/session-lens/tree/main/hooks/digest): `hooks/digest`

### Pane orchestration

- [Command registration](https://github.com/neokn/session-lens/blob/main/hooks/register.tsx): `hooks/register.tsx`
- [Live refresh](https://github.com/neokn/session-lens/blob/main/hooks/refresh.ts): `hooks/refresh.ts`
- [Pane state](https://github.com/neokn/session-lens/blob/main/hooks/state.ts): `hooks/state.ts`

### Terminal presentation

- [Session pane](https://github.com/neokn/session-lens/tree/main/hooks/views/templates): `hooks/views/templates`
- [Context display](https://github.com/neokn/session-lens/blob/main/hooks/views/organisms/ContextGrid.tsx): `hooks/views/organisms/ContextGrid.tsx`
- [Cost tables](https://github.com/neokn/session-lens/blob/main/hooks/views/organisms/CostTable.tsx): `hooks/views/organisms/CostTable.tsx`
- [Turn waterfall](https://github.com/neokn/session-lens/blob/main/hooks/views/organisms/Waterfall.tsx): `hooks/views/organisms/Waterfall.tsx`
- [Design tokens](https://github.com/neokn/session-lens/blob/main/hooks/views/palette.ts): `hooks/views/palette.ts`
- [Terminal layout](https://github.com/neokn/session-lens/blob/main/hooks/views/layout.ts): `hooks/views/layout.ts`
- [Theme selection](https://github.com/neokn/session-lens/blob/main/hooks/theme.ts): `hooks/theme.ts`

### Other components

- **Claude Code user**
- **/session-lens**
- **Session report plugin**

## Connections

- Claude Code user → /session-lens: runs
- /session-lens → Command registration: opens pane
- Command registration → Live refresh: starts refresh (evidence: `hooks/register.tsx`)
- Live refresh → Transcript reader: reads transcript (evidence: `hooks/refresh.ts`)
- Transcript reader → Child discovery: discovers children (evidence: `hooks/record/transcript.ts`)
- Transcript reader → Record digest: digests rows (evidence: `hooks/record/transcript.ts`)
- Transcript reader → Session digest: builds session (evidence: `hooks/record/transcript.ts`)
- Session digest → Record digest: uses record digest (evidence: `hooks/digest/session.ts`)
- Session digest → Turn analysis: uses turn analysis (evidence: `hooks/digest/session.ts`)
- Turn analysis → Record digest: scans records (evidence: `hooks/digest/turns.ts`)
- Turn analysis → Cost analysis: prices requests (evidence: `hooks/digest/turns.ts`)
- Record digest → Cost analysis: uses pricing (evidence: `hooks/digest/record.ts`)
- Live refresh → Pane state: updates state (evidence: `hooks/refresh.ts`)
- Command registration → Context analysis: loads digest (evidence: `hooks/register.tsx`)
- Command registration → Cost analysis: loads digest (evidence: `hooks/register.tsx`)
- Command registration → Compaction analysis: loads digest (evidence: `hooks/register.tsx`)
- Command registration → Timeline and events: loads activity data (evidence: `hooks/register.tsx`)
- Command registration → Effort and forecast: loads effort data (evidence: `hooks/register.tsx`)
- Command registration → Session pane: renders pane (evidence: `hooks/register.tsx`)
- Command registration → Context display: renders context (evidence: `hooks/register.tsx`)
- Command registration → Cost tables: renders cost (evidence: `hooks/register.tsx`)
- Command registration → Turn waterfall: renders turns (evidence: `hooks/register.tsx`)
- Command registration → Design tokens: uses palette (evidence: `hooks/register.tsx`)
- Command registration → Terminal layout: uses layout (evidence: `hooks/register.tsx`)
- Command registration → Theme selection: selects theme (evidence: `hooks/register.tsx`)
- Claude Code user → Session report plugin: opens report