@claudeye/linux-x64 1.0.0-beta.6

package/assets/standalone/README.md

@@ -0,0 +1,2111 @@
+```
+  ____ _                 _
+ / ___| | __ _ _   _  __| | ___ _   _  ___
+| |   | |/ _` | | | |/ _` |/ _ \ | | |/ _ \
+| |___| | (_| | |_| | (_| |  __/ |_| |  __/
+ \____|_|\__,_|\__,_|\__,_|\___|\__, |\___|
+                                |___/
+```
+
+# Claudeye: Watchtower for Claude Code and Claude Agents SDK
+
+**Uncover** what your agents did.
+**Understand** where they struggle.
+**Utilize** insights to improve.
+
+[![npm version](https://img.shields.io/npm/v/claudeye)](https://www.npmjs.com/package/claudeye)
+[![npm downloads](https://img.shields.io/npm/dm/claudeye)](https://www.npmjs.com/package/claudeye)
+[![node](https://img.shields.io/node/v/claudeye)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/Built%20with-TypeScript-blue)](https://www.typescriptlang.org/)
+[![Discord](https://badgen.net/discord/members/zT92CAgvkj)](https://discord.com/invite/zT92CAgvkj)
+
+## Table of Contents
+
+- [What is Claudeye?](#what-is-claudeye)
+- [Quick Start](#quick-start)
+- [Why Claudeye?](#why-claudeye)
+- [Features](#features)
+- [CLI Reference](#cli-reference)
+- [Custom Evals & Enrichments](#custom-evals--enrichments)
+- [API Reference](#api-reference)
+  - [`createApp()`](#createapp)
+  - [`app.condition(fn)`](#appconditionfn)
+  - [`app.queueCondition(fn, options?)`](#appqueueconditionfn-options)
+  - [`app.eval(name, fn, options?)`](#appevalname-fn-options)
+  - [`app.enrich(name, fn, options?)`](#appenrichname-fn-options)
+  - [`app.action(name, fn, options?)`](#appactionname-fn-options)
+  - [`app.alert(name, fn, options?)`](#appalertname-fn-options)
+  - [`app.dashboard.view(name, options?)`](#appdashboardviewname-options)
+  - [`app.dashboard.filter(name, fn, options?)`](#appdashboardfiltername-fn-options)
+  - [`app.dashboard.filter({ preBuilt })`](#appdashboardfilter-prebuilt-)
+  - [`app.dashboard.aggregate(name, definition, options?)`](#appdashboardaggregatename-definition-options)
+  - [`app.auth(options)`](#appauthoptions)
+  - [`app.listen(port?, options?)`](#applistenport-options)
+- [Subagent Scope](#subagent-scope)
+- [Evaluation Order](#evaluation-order)
+- [UI Behavior](#ui-behavior)
+- [Types](#types)
+- [Examples](#examples)
+  - [Basic Evals & Enrichments](#example-basic-evals--enrichments)
+  - [Dashboard Filters](#example-dashboard-filters)
+  - [Multi-View Dashboard](#example-multi-view-dashboard)
+  - [Eval Score Filters (cachedOnly)](#example-eval-score-filters-cachedonly)
+  - [Actions](#example-actions)
+  - [Alerts](#example-alerts)
+  - [Minimal Filters Only](#example-minimal-filters-only)
+- [Background Queue Processing](#background-queue-processing)
+- [Caching](#caching)
+- [Authentication](#authentication)
+- [Deployment with PM2](#deployment-with-pm2)
+- [How It Works](#how-it-works)
+- [Community](#community)
+- [License](#license)
+
+---
+
+## What is Claudeye?
+
+One command. Full visibility into every Claude agent session.
+
+Claudeye lets you replay agent executions, grade them with custom evals, and surface exactly where reliability breaks down, across both Claude Code and the Agents SDK. Deploy it locally or on your infrastructure. No setup, no config, just `claudeye` and you're in.
+
+## Quick Start
+
+```bash
+npm install -g claudeye && claudeye
+# or: bun install -g claudeye && claudeye
+```
+
+Opens your browser at `localhost:8020`. Reads from `~/.claude/projects` by default.
+
+Works with [Claude Code](https://docs.anthropic.com/en/docs/claude-code) sessions and [Claude Agents SDK](https://github.com/anthropics/anthropic-sdk-python) logs.
+
+> **Note:** Claudeye is distributed as a compiled native binary per platform. When you install `claudeye`, npm automatically pulls the correct platform-specific package (`@claudeye/linux-x64`, `@claudeye/darwin-arm64`, etc.) as an optional dependency. Node.js >= 20.9.0 must be available on PATH for the dashboard server.
+
+## Why Claudeye?
+
+| Feature | Claudeye | Langfuse | Dev-Agent-Lens | ccusage | Raw JSONL |
+|---------|:--------:|:--------:|:--------------:|:-------:|:---------:|
+| Local-first (no cloud) | **Yes** | Self-host option | Proxy required | Yes | Yes |
+| Session replay | **Yes** | Traces only | Traces only | No | Manual |
+| Custom evals | **Yes** | Limited | No | No | No |
+| Subagent expansion | **Yes** | No | No | No | No |
+| Zero config | **Yes** | Setup required | Proxy setup | Yes | N/A |
+| Visual dashboard | **Yes** | Yes | Yes (Phoenix) | CLI only | No |
+
+## Features
+
+### Uncover
+
+- **Projects & sessions browser** - filter by date range or keyword, paginated and sorted newest-first
+- **Full execution trace viewer** - every message, tool call, thinking block, and system event
+- **Nested subagent logs** - expand to see subagent executions inline, pre-loaded with the session
+- **Virtual scrolling** - handles sessions with thousands of entries without performance issues
+
+### Understand
+
+- **Session stats bar** - turns, tool calls, subagents, duration, and models at a glance
+- **Custom evals** - grade sessions with pass/fail results and 0-1 scores
+- **Per-eval recompute** - re-run a single eval without reprocessing all others
+- **Conditional evals** - gate evals globally or per-item, with session/subagent scope control
+
+### Utilize
+
+- **Custom enrichments** - compute metadata (token counts, quality signals, labels) as key-value pairs
+- **Custom actions** - on-demand tasks triggered from the dashboard via `app.action()` — generate summaries, export metrics, or run side-effects with full access to eval and enrichment results
+- **Alerts** - register callbacks via `app.alert()` that fire after all evals and enrichments complete (Slack webhooks, CI notifications, logging)
+- **Dashboard views & filters** - organize filters into named views, each with focused filter tiles (boolean toggles, range sliders, multi-select dropdowns) and a filterable sessions table
+- **Dashboard aggregates** - define cross-session summary tables with `app.dashboard.aggregate()`, using `{ collect, reduce }` for full control over output
+- **Unified queue** - all evals and enrichments (session, subagent, UI, background) go through a single priority queue with bounded concurrency, live tracking at `/queue`
+- **JSONL export** - download raw session logs
+- **Auto-refresh** - monitor live sessions at 5s, 10s, or 30s intervals
+- **Light/dark theme** - with system preference detection
+
+## CLI Reference
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--projects-path, -p <path>` | Path to Claude projects directory | `~/.claude/projects` |
+| `--port <number>` | Port to bind | `8020` |
+| `--host <address>` | Host to bind (`0.0.0.0` for LAN) | `localhost` |
+| `--evals <path>` | Path to evals/enrichments file | - |
+| `--auth-user <user:pass>` | Add an auth user (repeatable) | - |
+| `--cache-path <path>` | Custom cache directory | `~/.claudeye/cache` |
+| `--cache-clear` | Clear all cached results and exit | - |
+| `--no-open` | Don't auto-open the browser | - |
+| `--queue-interval <secs>` | Background scan interval in seconds | disabled |
+| `--queue-concurrency <num>` | Max parallel items per batch | `2` |
+| `--queue-history-ttl <secs>` | Seconds to keep completed items | `3600` |
+| `--max-queue-items <num>` | Max items to enqueue per scan (0=unlimited) | `500` |
+| `--logging <level>` | Log level: `info`, `warn`, `error` | `warn` |
+| `-h, --help` | Show help | - |
+
+### CLI Examples
+
+```bash
+# Custom projects path
+claudeye --projects-path /path/to/projects
+
+# Different port, no browser
+claudeye --port 3000 --no-open
+
+# LAN access
+claudeye --host 0.0.0.0
+
+# Load custom evals and enrichments
+claudeye --evals ./my-evals.js
+
+# Password-protect the dashboard
+claudeye --auth-user admin:secret
+
+# Multiple auth users
+claudeye --auth-user admin:secret --auth-user viewer:readonly
+
+# Clear cached results
+claudeye --cache-clear
+
+# Enable background queue processing (scan every 60 seconds)
+claudeye --evals ./my-evals.js --queue-interval 60
+
+# Background processing with higher concurrency
+claudeye --evals ./my-evals.js --queue-interval 30 --queue-concurrency 5
+```
+
+## Custom Evals & Enrichments
+
+Define evals and enrichments in a single JS file and load with `--evals`:
+
+```js
+import { createApp } from 'claudeye';
+
+const app = createApp();
+
+// Evals: grade your sessions
+app.eval('under-50-turns', ({ stats }) => ({
+  pass: stats.turnCount <= 50,
+  score: Math.max(0, 1 - stats.turnCount / 100),
+  message: `${stats.turnCount} turn(s)`,
+}));
+
+app.eval('tool-success', ({ entries }) => {
+  const results = entries.filter(e => e.type === 'tool_result');
+  const errors = results.filter(e => e.is_error);
+  const rate = results.length ? 1 - errors.length / results.length : 1;
+  return { pass: rate >= 0.9, score: rate };
+});
+
+// Enrichments: add metadata to sessions
+app.enrich('session-summary', ({ entries, stats }) => ({
+  'Total Tokens': entries.reduce((s, e) => s + (e.usage?.total_tokens || 0), 0),
+  'Primary Model': stats.models[0] || 'unknown',
+  'Tool Calls': stats.toolCallCount,
+}));
+```
+
+```bash
+claudeye --evals ./my-evals.js
+```
+
+---
+
+## API Reference
+
+> **Distribution note (v1.0.0+):** Claudeye is distributed as a compiled native binary. The `claudeye` npm package is a thin JS wrapper that proxies `createApp()` calls to the binary via JSON IPC. User-defined functions (eval closures, enrich callbacks, etc.) remain in your Node.js process — they are never serialized into the binary. The public API surface is identical to previous versions; no code changes are required.
+
+### `createApp()`
+
+Returns a `ClaudeyeApp` instance. All methods are chainable.
+
+```ts
+import { createApp } from 'claudeye';
+const app = createApp();
+```
+
+---
+
+### `app.condition(fn)`
+
+Set a global condition that gates all evals, enrichments, and actions. Calling this multiple times replaces the previous condition.
+
+```ts
+app.condition(({ entries, stats, projectName, sessionId }) => boolean | Promise<boolean>);
+```
+
+If the global condition returns `false` (or throws), every registered eval, enrichment, and action is skipped.
+
+#### Examples
+
+```js
+// Only run for sessions with actual content
+app.condition(({ entries }) => entries.length > 0);
+
+// Only run for non-test projects
+app.condition(({ projectName }) => !projectName.includes('test'));
+
+// Only run for sessions longer than 5 turns
+app.condition(({ stats }) => stats.turnCount >= 5);
+
+// Async condition
+app.condition(async ({ sessionId }) => {
+  // You could check an external service, database, etc.
+  return sessionId !== 'skip-this-one';
+});
+```
+
+#### Combining Global and Per-Item Conditions
+
+Global and per-item conditions stack. The global condition runs first; if it passes, per-item conditions are checked individually:
+
+```js
+const app = createApp();
+
+// Global: skip everything for empty sessions
+app.condition(({ entries }) => entries.length > 0);
+
+// Per-eval: only check turn count for sessions with tool calls
+app.eval('efficient-tools',
+  ({ stats }) => ({
+    pass: stats.toolCallCount <= stats.turnCount * 2,
+    score: Math.max(0, 1 - (stats.toolCallCount / (stats.turnCount * 4))),
+  }),
+  { condition: ({ stats }) => stats.toolCallCount > 0 }
+);
+
+// Per-enrichment: only compute model info for sessions that used a model
+app.enrich('model-info',
+  ({ stats }) => ({
+    'Primary Model': stats.models[0] || 'unknown',
+    'Model Count': stats.models.length,
+  }),
+  { condition: ({ stats }) => stats.models.length > 0 }
+);
+```
+
+> **Note:** Calling `app.condition()` multiple times replaces the previous condition. Only the last one is active. The global condition applies to both evals and enrichments; there's no way to set separate global conditions for each.
+
+---
+
+### `app.queueCondition(fn, options?)`
+
+Set a condition that gates **background queue processing**. This is separate from `app.condition()` — it only affects the background scanner (`scanAndEnqueue`), not UI-triggered runs.
+
+```ts
+app.queueCondition(fn: ConditionFunction, options?: QueueConditionOptions): ClaudeyeApp;
+```
+
+If the queue condition returns `false` (or throws), the session is skipped entirely — no evals or enrichments are enqueued for that session during background scanning.
+
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `cacheable` | `boolean` | `false` | When `true`, condition results are cached per-session with hash-based invalidation. When `false` (default), the condition is evaluated fresh every scan cycle. |
+
+#### Caching
+
+By default (`cacheable: false`), the condition is re-evaluated every scan cycle. This is safe for time-dependent or external-state-dependent conditions (e.g., business hours, feature flags).
+
+When `cacheable: true`, condition results are cached per-session. The cache auto-invalidates when:
+- The **session file changes** (new content → different `contentHash`)
+- The **condition function is edited** (different `conditionCodeHash` via `fn.toString()` → SHA-256)
+
+Use `cacheable: true` only when the condition depends solely on session data.
+
+Log parsing is **lazy** — only triggered when the condition is actually evaluated (every cycle when non-cacheable, or on cache miss when cacheable). The parsed session data comes from `getCachedSessionLog()` which is itself LRU-cached in memory.
+
+#### Examples
+
+```js
+// Only process sessions with actual content (evaluated fresh every cycle)
+app.queueCondition(({ entries }) => entries.length > 5);
+
+// Only process sessions from specific projects (safe to cache — depends only on session data)
+app.queueCondition(({ projectName }) => projectName.startsWith('production'), { cacheable: true });
+
+// Time-dependent condition — must not be cached
+app.queueCondition(() => {
+  const hour = new Date().getHours();
+  return hour >= 9 && hour < 17; // business hours only
+});
+
+// Skip sessions that are too short to be meaningful (safe to cache)
+app.queueCondition(({ stats }) => stats.turnCount >= 3, { cacheable: true });
+```
+
+#### Difference from `app.condition()`
+
+| | `app.condition()` | `app.queueCondition()` |
+|---|---|---|
+| **Scope** | Gates all evals/enrichments/actions | Gates background queue only |
+| **Affects UI runs** | Yes | No |
+| **Affects background scanner** | No | Yes |
+| **Caching** | No (re-evaluated each run) | Opt-in via `{ cacheable: true }` |
+
+Both can be set simultaneously. `app.queueCondition()` acts as a pre-filter for the background scanner; sessions that pass then go through the normal `app.condition()` check when individual items execute.
+
+---
+
+### `app.eval(name, fn, options?)`
+
+Register an eval function. Evals grade sessions with a pass/fail result and an optional 0-1 score.
+
+- **`name`** - unique string identifier for the eval
+- **`fn`** - function receiving an `EvalContext` and returning an `EvalResult`
+- **`options.condition`** - optional condition function to gate this eval
+- **`options.scope`** - `'session'` (default), `'subagent'`, or `'both'`
+- **`options.subagentType`** - only run for subagents of this type (e.g. `'Explore'`)
+
+If a per-eval condition returns `false`, the eval is marked as **skipped** in the results panel. If the condition throws, the eval is marked as **errored** with the message `Condition error: <message>`.
+
+#### `EvalResult`
+
+```ts
+interface EvalResult {
+  pass: boolean;                          // Did the eval pass?
+  score?: number;                         // 0-1, clamped automatically (default: 1.0)
+  message?: string;                       // Shown in the UI
+  metadata?: Record<string, unknown>;     // Arbitrary data
+}
+```
+
+#### Examples
+
+```js
+// Simple: check if session stayed under a turn budget
+app.eval('under-50-turns', ({ stats }) => ({
+  pass: stats.turnCount <= 50,
+  score: Math.max(0, 1 - stats.turnCount / 100),
+  message: `${stats.turnCount} turn(s)`,
+}));
+
+// Check tool success rate
+app.eval('tool-success-rate', ({ entries }) => {
+  const toolResults = entries.filter(e =>
+    e.type === 'user' &&
+    Array.isArray(e.message?.content) &&
+    e.message.content.some(b => b.type === 'tool_result')
+  );
+  const errors = toolResults.filter(e =>
+    e.message?.content?.some(b => b.is_error === true)
+  );
+  const rate = toolResults.length > 0
+    ? 1 - (errors.length / toolResults.length)
+    : 1;
+  return {
+    pass: rate >= 0.9,
+    score: rate,
+    message: `${errors.length}/${toolResults.length} tool errors`,
+  };
+});
+
+// Check that the session ended with a text response
+app.eval('has-completion', ({ entries }) => {
+  const lastAssistant = [...entries].reverse().find(e => e.type === 'assistant');
+  const hasText = lastAssistant?.message?.content?.some?.(b => b.type === 'text');
+  return {
+    pass: !!hasText,
+    score: hasText ? 1.0 : 0,
+    message: hasText ? 'Session completed with text response' : 'No final text response',
+  };
+});
+
+// With a per-eval condition: only run for longer sessions
+app.eval('under-budget',
+  ({ stats }) => ({
+    pass: stats.turnCount <= 30,
+    score: Math.max(0, 1 - stats.turnCount / 60),
+    message: `${stats.turnCount} turns`,
+  }),
+  { condition: ({ stats }) => stats.turnCount >= 5 }
+);
+
+// Subagent-scoped eval
+app.eval('explore-depth', ({ entries, source }) => {
+  const myEntries = entries.filter(e => e._source === source);
+  return {
+    pass: myEntries.length > 5,
+    score: Math.min(myEntries.length / 20, 1),
+  };
+}, { scope: 'subagent', subagentType: 'Explore' });
+```
+
+---
+
+### `app.enrich(name, fn, options?)`
+
+Register an enricher function. Enrichments compute key-value metadata displayed in the dashboard.
+
+- **`name`** - unique string identifier for the enricher
+- **`fn`** - function receiving an `EvalContext` and returning a `Record<string, string | number | boolean>`
+- **`options.condition`** - optional condition function to gate this enricher
+- **`options.scope`** - `'session'` (default), `'subagent'`, or `'both'`
+- **`options.subagentType`** - only run for subagents of this type (e.g. `'Explore'`)
+
+#### `EnrichmentResult`
+
+```ts
+// Enrichers return a flat key-value map
+type EnrichmentResult = Record<string, string | number | boolean>;
+```
+
+#### Examples
+
+```js
+// Session overview
+app.enrich('overview', ({ stats }) => ({
+  'Turns': stats.turnCount,
+  'Tool Calls': stats.toolCallCount,
+  'Duration': stats.duration,
+  'Models': stats.models.join(', ') || 'none',
+}));
+
+// Token and cost breakdown
+app.enrich('token-usage', ({ entries }) => {
+  const inputTokens = entries.reduce((s, e) => s + (e.usage?.input_tokens || 0), 0);
+  const outputTokens = entries.reduce((s, e) => s + (e.usage?.output_tokens || 0), 0);
+  return {
+    'Input Tokens': inputTokens,
+    'Output Tokens': outputTokens,
+    'Total Tokens': inputTokens + outputTokens,
+    'Est. Cost': `$${((inputTokens * 0.003 + outputTokens * 0.015) / 1000).toFixed(4)}`,
+  };
+});
+
+// Error analysis (only when errors exist)
+app.enrich('error-analysis',
+  ({ entries }) => {
+    const errors = entries.filter(e => e.is_error === true);
+    return {
+      'Total Errors': errors.length,
+      'Error Rate': `${((errors.length / entries.length) * 100).toFixed(1)}%`,
+    };
+  },
+  { condition: ({ entries }) => entries.some(e => e.is_error === true) }
+);
+
+// Subagent info (only when subagents were spawned)
+app.enrich('subagent-info',
+  ({ entries, stats }) => {
+    const subagentEntries = entries.filter(e => e.type === 'assistant' && e.parentUuid);
+    return {
+      'Subagent Count': stats.subagentCount,
+      'Subagent Entries': subagentEntries.length,
+    };
+  },
+  { condition: ({ stats }) => stats.subagentCount > 0 }
+);
+
+// Advanced metrics (async condition)
+app.enrich('advanced-metrics',
+  ({ entries }) => ({
+    'Entry Count': entries.length,
+    'Avg Entry Size': Math.round(
+      entries.reduce((s, e) => s + JSON.stringify(e).length, 0) / entries.length
+    ),
+  }),
+  {
+    condition: async ({ entries }) => {
+      return entries.length > 10;
+    },
+  }
+);
+```
+
+---
+
+### `app.action(name, fn, options?)`
+
+Register a user-defined action. Actions are a flexible primitive for on-demand tasks — generating summaries, exporting metrics, running side-effects, or anything else that doesn't fit the eval (pass/fail) or enrichment (key-value) model. Actions are never auto-run; they are triggered manually from the dashboard.
+
+- **`name`** - unique string identifier for the action
+- **`fn`** - function receiving an `ActionContext` and returning an `ActionResult`
+- **`options.condition`** - optional condition function to gate this action
+- **`options.scope`** - `'session'` (default), `'subagent'`, or `'both'`
+- **`options.subagentType`** - only run for subagents of this type (e.g. `'Explore'`)
+- **`options.cache`** - cache results (default: `true`). Set to `false` for side-effect actions that should always re-run.
+
+#### `ActionContext`
+
+Actions receive an extended context that includes cached eval and enrichment results:
+
+```ts
+interface ActionContext extends EvalContext {
+  evalResults: Record<string, EvalRunResult>;       // Cached eval results for the session
+  enrichmentResults: Record<string, EnrichRunResult>; // Cached enrichment results
+}
+```
+
+This means actions can build on prior analysis — check which evals passed, read enrichment data, and combine it with raw session data.
+
+#### `ActionResult`
+
+```ts
+interface ActionResult {
+  output?: string;                    // Free-form text (rendered in monospace block with copy button)
+  status: 'success' | 'error';       // Action outcome
+  message?: string;                   // Short summary shown in the UI
+}
+```
+
+Return `output` for text. The output is rendered in a scrollable monospace block with a copy-to-clipboard button. The `status` field determines the icon in the results panel.
+
+#### Examples
+
+```js
+// Session summary: combine stats with eval results
+app.action('session-summary', ({ stats, evalResults }) => {
+  const evalNames = Object.keys(evalResults);
+  const passCount = evalNames.filter(n => evalResults[n]?.pass).length;
+  return {
+    output: [
+      `Session: ${stats.turnCount} turns, ${stats.toolCallCount} tool calls`,
+      `Duration: ${stats.duration}`,
+      `Models: ${stats.models.join(', ') || 'unknown'}`,
+      `Evals: ${passCount}/${evalNames.length} passed`,
+    ].join('\n'),
+    status: 'success',
+    message: 'Summary generated',
+  };
+});
+
+// Export metrics: gather enrichment data into a text report
+app.action('export-metrics', ({ stats, enrichmentResults }) => {
+  const enrichData = {};
+  for (const [name, result] of Object.entries(enrichmentResults)) {
+    if (result.data) Object.assign(enrichData, result.data);
+  }
+  const lines = [
+    ...Object.entries(enrichData).map(([k, v]) => `${k}: ${v}`),
+    `turnCount: ${stats.turnCount}`,
+    `toolCallCount: ${stats.toolCallCount}`,
+  ];
+  return {
+    output: lines.join('\n'),
+    status: 'success',
+    message: `Exported ${Object.keys(enrichData).length + 2} metrics`,
+  };
+});
+
+// Side-effect action: write results to a file (disable caching)
+app.action('write-report', async ({ projectName, sessionId, stats, evalResults }) => {
+  const fs = await import('fs/promises');
+  const report = {
+    projectName, sessionId,
+    turns: stats.turnCount,
+    evals: Object.fromEntries(
+      Object.entries(evalResults).map(([name, r]) => [name, { pass: r.pass, score: r.score }])
+    ),
+    timestamp: new Date().toISOString(),
+  };
+  await fs.appendFile('session-reports.jsonl', JSON.stringify(report) + '\n');
+  return {
+    status: 'success',
+    message: `Report appended to session-reports.jsonl`,
+    output: 'Written to session-reports.jsonl',
+  };
+}, { cache: false });
+
+// Conditional action: only available for sessions with tool usage
+app.action('tool-analysis', ({ entries, source }) => {
+  const toolUses = entries.filter(e =>
+    e._source === (source || 'session') &&
+    e.type === 'assistant' &&
+    Array.isArray(e.message?.content) &&
+    e.message.content.some(b => b.type === 'tool_use')
+  );
+  const toolNames = [...new Set(toolUses.flatMap(e =>
+    (e.message?.content || []).filter(b => b.type === 'tool_use').map(b => b.name)
+  ))];
+  return {
+    output: toolNames.length > 0
+      ? `Tools used: ${toolNames.join(', ')}`
+      : 'No tools used',
+    status: 'success',
+  };
+}, { condition: ({ stats }) => stats.toolCallCount > 0 });
+
+// Subagent-scoped action
+app.action('agent-report', ({ entries, source, stats }) => {
+  const myEntries = entries.filter(e => e._source === source);
+  return {
+    output: [
+      `Source: ${source}`,
+      `Entries: ${myEntries.length}`,
+      `Turns: ${stats.turnCount}`,
+      `Tool calls: ${stats.toolCallCount}`,
+    ].join('\n'),
+    status: 'success',
+    message: `Agent ${source}: ${myEntries.length} entries`,
+  };
+}, { scope: 'subagent' });
+```
+
+#### Action UI Behavior
+
+The Actions panel appears on session pages (and in expanded subagent cards for subagent-scoped actions) when matching actions are registered. The panel:
+
+- Shows all registered actions as idle (not run) on initial load, with cached results displayed immediately
+- Provides a **Run** button per action and a **Run All** button in the header
+- Displays `output` in a scrollable monospace block with a copy-to-clipboard button
+- Shows a "cached" badge for results served from cache
+- Collapses by default (click the header to expand)
+- Error count, success count, and loading spinners are visible in the header even when collapsed
+
+#### Action Types
+
+```ts
+type ActionFunction = (context: ActionContext) => ActionResult | Promise<ActionResult>;
+
+interface RegisteredAction {
+  name: string;
+  fn: ActionFunction;
+  condition?: ConditionFunction;
+  scope: EvalScope;           // 'session' | 'subagent' | 'both'
+  subagentType?: string;
+  cache: boolean;             // default: true
+}
+
+interface ActionRunResult {
+  name: string;
+  output?: string;
+  status: 'success' | 'error';
+  message?: string;
+  durationMs: number;
+  error?: string;             // Present when the action threw or its condition threw
+  skipped?: boolean;          // Present when the global/per-action condition returned false
+}
+
+interface ActionRunSummary {
+  results: ActionRunResult[];
+  totalDurationMs: number;
+  errorCount: number;
+  skippedCount: number;
+}
+```
+
+---
+
+### `app.alert(name, fn, options?)`
+
+Register an alert callback that fires after all evals and enrichments complete for a session. Alerts are the hook point for Slack webhooks, CI notifications, logging, or any post-processing logic.
+
+- **`name`** - unique string identifier for the alert (re-registering replaces the previous callback)
+- **`fn`** - function receiving an `AlertContext` and returning `void | Promise<void>`
+- **`options`** - optional `AlertOptions` object:
+  - **`suppressOnRecompute`** (default: `true`) — when `true`, this alert is suppressed during recomputes triggered by code changes (e.g., modifying an eval function). Alerts still fire when new session data arrives. Set to `false` for alerts that should always fire regardless of the trigger.
+
+#### When Alerts Fire
+
+Alerts fire **once per session content version** — the unified queue checks after each item completes whether all eval/enrichment work for that session is done (no pending or processing items remain). When the last item completes, a debounced check fires alerts if the dedup marker allows it.
+
+| Trigger | Behavior |
+|---------|----------|
+| **Initial page load** | `queuePerItem()` per eval/enrichment → alerts fire when last item completes |
+| **Background processing** | `scanAndEnqueue()` → individual items at LOW priority → alerts fire when last item completes |
+| **Page reload (all cached)** | No items enter the queue → no alerts fire |
+| **Re-run All** | Clears dedup marker first, then parallel `queuePerItem()` calls → alerts fire exactly once |
+| **Re-run single** | `queuePerItem()` for one item → alerts do NOT re-fire (dedup marker still valid) |
+| **Session content changes** | New `contentHash` invalidates the dedup marker → alerts fire again |
+| **Alert registrations change** | New `alertsHash` invalidates the dedup marker → alerts fire again |
+
+Each alert callback is individually try/caught via `Promise.allSettled`. A throwing alert never blocks other alerts or eval processing. Errors are logged to console.
+
+#### `AlertContext`
+
+```ts
+interface AlertContext {
+  projectName: string;              // Encoded project folder name
+  sessionId: string;                // Session UUID
+  evalSummary?: EvalRunSummary;     // Present when evals registered & ran
+  enrichSummary?: EnrichRunSummary; // Present when enrichments registered & ran
+}
+```
+
+`evalSummary` and `enrichSummary` contain **all** results for the session — both cached and freshly computed. The alert always sees the complete picture.
+
+#### Examples
+
+```js
+// Slack webhook on eval failure
+app.alert('slack-on-failure', async ({ projectName, sessionId, evalSummary }) => {
+  if (evalSummary && evalSummary.failCount > 0) {
+    await fetch('https://hooks.slack.com/services/T.../B.../xxx', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        text: `${evalSummary.failCount} evals failed for ${projectName}/${sessionId}`,
+      }),
+    });
+  }
+});
+
+// Console logging
+app.alert('log-results', ({ projectName, sessionId, evalSummary, enrichSummary }) => {
+  const evals = evalSummary
+    ? `${evalSummary.passCount} pass, ${evalSummary.failCount} fail, ${evalSummary.errorCount} error`
+    : 'no evals';
+  const enrichments = enrichSummary
+    ? `${enrichSummary.results.length} enrichments (${enrichSummary.errorCount} errors)`
+    : 'no enrichments';
+  console.log(`[ALERT] ${projectName}/${sessionId}: ${evals} | ${enrichments}`);
+});
+
+// Write results to a file for CI
+app.alert('ci-report', async ({ projectName, sessionId, evalSummary }) => {
+  if (!evalSummary) return;
+  const fs = await import('fs/promises');
+  await fs.appendFile('eval-results.jsonl', JSON.stringify({
+    projectName,
+    sessionId,
+    passCount: evalSummary.passCount,
+    failCount: evalSummary.failCount,
+    results: evalSummary.results.map(r => ({ name: r.name, pass: r.pass, score: r.score })),
+    timestamp: new Date().toISOString(),
+  }) + '\n');
+});
+
+// Alert that fires even on code-change recomputes (e.g., audit logging)
+app.alert('audit-log', ({ projectName, sessionId }) => {
+  console.log(`[AUDIT] Processed ${projectName}/${sessionId}`);
+}, { suppressOnRecompute: false });
+```
+
+#### Alert Types
+
+```ts
+type AlertFunction = (context: AlertContext) => void | Promise<void>;
+
+interface AlertOptions {
+  suppressOnRecompute?: boolean;  // Default: true
+}
+
+interface RegisteredAlert {
+  name: string;
+  fn: AlertFunction;
+  suppressOnRecompute: boolean;
+}
+
+interface EvalRunSummary {
+  results: EvalRunResult[];
+  totalDurationMs: number;
+  passCount: number;
+  failCount: number;
+  errorCount: number;
+  skippedCount: number;
+}
+
+interface EnrichRunSummary {
+  results: EnrichRunResult[];
+  totalDurationMs: number;
+  errorCount: number;
+  skippedCount: number;
+}
+```
+
+---
+
+### `app.dashboard.view(name, options?)`
+
+Create a named dashboard view. Views group related filters into focused sets. Each view appears as a card on `/dashboard` and has its own route at `/dashboard/[viewName]`.
+
+- **`name`** - unique string identifier for the view
+- **`options.label`** - human-readable label displayed on the card (defaults to the name)
+- **`options.cachedOnly`** - only show sessions with complete cache entries (default: `false`)
+
+Returns a `DashboardViewBuilder` with chainable `.filter()` and `.aggregate()` methods.
+
+#### `DashboardViewBuilder`
+
+```ts
+interface DashboardViewBuilder {
+  filter(name: string, fn: FilterFunction, options?: FilterOptions): DashboardViewBuilder;
+  filter(options: { preBuilt: string[] }): DashboardViewBuilder;
+  aggregate(name: string, definition: AggregateDefinition, options?: AggregateOptions): DashboardViewBuilder;
+}
+```
+
+The view builder's `.filter()` returns the view builder (not the app), so you can chain multiple filters within a view:
+
+```js
+app.dashboard.view('performance', { label: 'Performance Metrics' })
+  .filter('turn-count', ({ stats }) => stats.turnCount, { label: 'Turn Count' })
+  .filter('tool-calls', ({ stats }) => stats.toolCallCount, { label: 'Tool Calls' });
+```
+
+#### `ViewOptions`
+
+```ts
+interface ViewOptions {
+  label?: string;       // Human-readable label (defaults to name)
+  cachedOnly?: boolean; // Only show sessions with complete cache entries (default: false)
+}
+```
+
+#### `cachedOnly` Views
+
+When `cachedOnly: true`, uncached sessions are **pre-filtered** before any filter computation runs — sessions without complete cache entries are skipped entirely. This avoids expensive log parsing, eval cache reads, and filter function execution for uncached sessions. Sessions appear in the view as the background queue processes them.
+
+Filter functions in `cachedOnly` views receive `ctx.evalResults` — a record of cached eval results keyed by eval name. Each entry has `pass`, `score`, and optional `error`/`message` fields. This lets you create per-eval score filters (range sliders) and composite boolean filters without re-running evals.
+
+```js
+// Only show sessions that have been fully processed
+app.dashboard.view('quality', { cachedOnly: true })
+  .filter('has-errors', ({ entries }) =>
+    entries.some(e => e.type === 'assistant' &&
+      Array.isArray(e.message?.content) &&
+      e.message.content.some(b => b.type === 'tool_use' && b.is_error)),
+    { label: 'Has Errors' });
+
+// Per-eval score filters using evalResults
+app.dashboard.view('eval-results', { cachedOnly: true, label: 'Eval Score Filters' })
+  .filter('quality-score', (ctx) => ctx.evalResults?.['quality']?.score ?? 0,
+    { label: 'Quality Score' })
+  .filter('all-passing', (ctx) => {
+    if (!ctx.evalResults) return false;
+    return Object.values(ctx.evalResults).every(r => r.pass);
+  }, { label: 'All Evals Passing' });
+```
+
+#### Routing
+
+| URL | Behavior |
+|-----|----------|
+| `/dashboard` | If named views exist, shows a view index (card grid). If only default filters, shows them directly. If nothing registered, shows an empty state. |
+| `/dashboard/[viewName]` | Specific named view with its filters and sessions table. |
+
+#### Examples
+
+```js
+// Two focused views
+app.dashboard.view('performance', { label: 'Performance Metrics' })
+  .filter('turn-count', ({ stats }) => stats.turnCount, { label: 'Turn Count' })
+  .filter('tool-calls', ({ stats }) => stats.toolCallCount, { label: 'Tool Calls' });
+
+app.dashboard.view('quality', { label: 'Quality Checks' })
+  .filter('has-errors', ({ entries }) =>
+    entries.some(e => e.type === 'assistant' &&
+      Array.isArray(e.message?.content) &&
+      e.message.content.some(b => b.type === 'tool_use' && b.is_error)),
+    { label: 'Has Errors' })
+  .filter('primary-model', ({ stats }) => stats.models[0] || 'unknown',
+    { label: 'Primary Model' });
+
+// Backward-compat: app.dashboard.filter() still works (goes to "default" view)
+app.dashboard.filter('uses-subagents', ({ stats }) => stats.subagentCount > 0,
+  { label: 'Uses Subagents' }
+);
+```
+
+---
+
+### `app.dashboard.filter(name, fn, options?)`
+
+Register a dashboard filter on the **default** view. For organizing filters into named views, see `app.dashboard.view()` above.
+
+- **`name`** - unique string identifier for the filter
+- **`fn`** - function receiving an `EvalContext` and returning a `FilterValue` (`boolean`, `number`, or `string`)
+- **`options.label`** - human-readable label for the filter tile (defaults to the name)
+- **`options.condition`** - optional condition function to gate this filter
+
+The return type auto-determines the UI control:
+
+| Return type | UI control | Behavior |
+|-------------|-----------|----------|
+| `boolean` | Three-state toggle | Cycle: All &rarr; Yes &rarr; No &rarr; All |
+| `number` | Range slider | Dual-handle slider with min/max inputs. Step auto-adapts: integer data uses steps of 1/5/10; float data uses 0.01 (range&le;1), 0.1 (range&le;10), or 1 |
+| `string` | Multi-select dropdown | Checkboxes with Select All / Clear |
+
+Filter values are computed server-side with an incremental index (only new/changed sessions are reprocessed). Filtering and pagination happen server-side, returning only the matching page of results.
+
+#### Examples
+
+```js
+// Boolean filter: toggle sessions that have tool errors
+app.dashboard.filter('has-errors', ({ entries }) =>
+  entries.some(e =>
+    e.type === 'assistant' &&
+    Array.isArray(e.message?.content) &&
+    e.message.content.some(b => b.type === 'tool_use' && b.is_error)
+  ),
+  { label: 'Has Errors' }
+);
+
+// Number filter: range slider for turn count
+app.dashboard.filter('turn-count', ({ stats }) => stats.turnCount,
+  { label: 'Turn Count' }
+);
+
+// String filter: multi-select for primary model
+app.dashboard.filter('primary-model', ({ stats }) => stats.models[0] || 'unknown',
+  { label: 'Primary Model' }
+);
+
+// Number filter: range slider for tool call count
+app.dashboard.filter('tool-calls', ({ stats }) => stats.toolCallCount,
+  { label: 'Tool Calls' }
+);
+
+// Boolean filter: sessions with subagents
+app.dashboard.filter('uses-subagents', ({ stats }) => stats.subagentCount > 0,
+  { label: 'Uses Subagents' }
+);
+
+// String filter: session duration bucket
+app.dashboard.filter('duration-bucket', ({ stats }) => {
+  const ms = parseInt(stats.duration) || 0;
+  if (ms < 60000) return 'Under 1m';
+  if (ms < 300000) return '1-5m';
+  if (ms < 900000) return '5-15m';
+  return 'Over 15m';
+}, { label: 'Duration' });
+
+// With a per-filter condition: only compute for non-empty sessions
+app.dashboard.filter('avg-tools-per-turn',
+  ({ stats }) => stats.turnCount > 0
+    ? Math.round(stats.toolCallCount / stats.turnCount * 10) / 10
+    : 0,
+  {
+    label: 'Avg Tools/Turn',
+    condition: ({ entries }) => entries.length > 0,
+  }
+);
+```
+
+#### How Filters Work
+
+1. When the `/dashboard` page loads, the server action discovers all projects and sessions
+2. An incremental `DashboardIndex` diffs the discovered sessions against previously computed rows — only new or changed sessions are processed (unchanged sessions are skipped entirely)
+3. For new/changed sessions, it checks the per-session disk cache first, then falls back to parsing the JSONL log and running filters
+4. Filter metadata (min/max for numbers, unique values for strings) is rebuilt from accumulators only when the session set changes
+5. Server-side filtering and pagination are applied — only the matching page of results is sent to the client
+6. User interactions (toggle, slider, dropdown) trigger a debounced (300ms) server re-fetch with the new filter state
+
+#### Global Condition
+
+Dashboard filters respect the global condition set via `app.condition()`. If the global condition returns `false` for a session, all filters are skipped for that session.
+
+```js
+// Skip empty sessions across evals, enrichments, AND dashboard filters
+app.condition(({ entries }) => entries.length > 0);
+```
+
+---
+
+### `app.dashboard.filter({ preBuilt })`
+
+Enable pre-built filters on the dashboard. Pre-built filters provide common filtering functionality with optimized UX — no custom filter function needed.
+
+- **`preBuilt`** - array of pre-built filter names to enable
+
+#### Available Pre-Built Filters
+
+| Name | UI control | Description |
+|------|-----------|-------------|
+| `'lastModified'` | Date range picker (from/to) | Filters sessions by their last modified date |
+
+#### Examples
+
+```js
+// Enable on the default view
+app.dashboard.filter({ preBuilt: ['lastModified'] });
+
+// Combine with custom filters
+app.dashboard.filter({ preBuilt: ['lastModified'] });
+app.dashboard.filter('model', ({ stats }) => stats.models[0] || 'unknown',
+  { label: 'Model' });
+
+// Enable on a named view
+app.dashboard.view('overview', { label: 'Overview' })
+  .filter({ preBuilt: ['lastModified'] })
+  .filter('turns', ({ stats }) => stats.turnCount, { label: 'Turns' });
+```
+
+Pre-built date filters operate directly on the `DashboardSessionRow.lastModified` field — they don't require parsing session logs or running a filter function. The date range (min/max) is computed from the observed session data. Filtering is done server-side using normalized server-local calendar dates.
+
+---
+
+### `app.dashboard.aggregate(name, definition, options?)`
+
+Register a cross-session aggregate on the **default** view. For organizing aggregates into named views, use `app.dashboard.view().aggregate()`.
+
+- **`name`** - unique string identifier for the aggregate
+- **`definition`** - a `{ collect, reduce }` object
+- **`options.label`** - human-readable label for the aggregate section (defaults to the name)
+- **`options.condition`** - optional condition function to gate this aggregate per session
+
+Provide a `{ collect, reduce }` object. The `collect` function runs per session, and `reduce` transforms all collected values into your output table.
+
+#### Examples
+
+```js
+// Eval pass rate summary table
+app.dashboard.aggregate('eval-summary', {
+  collect: ({ evalResults }) => {
+    const result = {};
+    for (const [name, r] of Object.entries(evalResults)) {
+      result[`${name}_pass`] = r.pass;
+      result[`${name}_score`] = r.score;
+    }
+    return result;
+  },
+  reduce: (collected) => {
+    const evalNames = new Set();
+    for (const s of collected) {
+      for (const key of Object.keys(s.values)) {
+        if (key.endsWith('_pass')) evalNames.add(key.replace('_pass', ''));
+      }
+    }
+    return Array.from(evalNames).map(name => ({
+      'Eval': name,
+      'Pass Rate': collected.filter(s => s.values[`${name}_pass`]).length / collected.length,
+      'Avg Score': collected.reduce((sum, s) => {
+        const v = s.values[`${name}_score`];
+        return sum + (typeof v === 'number' ? v : 0);
+      }, 0) / collected.length,
+    }));
+  },
+});
+
+// Aggregates on named views alongside filters
+app.dashboard.view('quality', { label: 'Quality' })
+  .aggregate('session-metrics', {
+    collect: ({ stats }) => ({
+      turnCount: stats.turnCount,
+      toolCalls: stats.toolCallCount,
+    }),
+    reduce: (collected) => {
+      const n = collected.length || 1;
+      let turns = 0, tools = 0;
+      for (const s of collected) {
+        turns += typeof s.values.turnCount === 'number' ? s.values.turnCount : 0;
+        tools += typeof s.values.toolCalls === 'number' ? s.values.toolCalls : 0;
+      }
+      return [
+        { Metric: 'Avg Turns', Value: +(turns / n).toFixed(1) },
+        { Metric: 'Avg Tool Calls', Value: +(tools / n).toFixed(1) },
+      ];
+    },
+  })
+  .filter('turns', ({ stats }) => stats.turnCount, { label: 'Turns' });
+```
+
+#### `AggregateContext`
+
+The collect function receives an extended context:
+
+```ts
+interface AggregateContext {
+  entries: Record<string, unknown>[];  // Raw JSONL lines
+  stats: EvalLogStats;                 // Computed stats
+  projectName: string;
+  sessionId: string;
+  source: string;
+  evalResults: Record<string, { pass: boolean; score: number; error?: string; message?: string }>;
+  enrichResults: Record<string, Record<string, EnrichmentValue>>;
+  filterValues: Record<string, FilterValue>;
+}
+```
+
+#### Aggregate Types
+
+```ts
+type AggregateValue = boolean | number | string;
+
+type AggregateCollectFunction = (
+  context: AggregateContext,
+) => Record<string, AggregateValue> | Promise<Record<string, AggregateValue>>;
+
+type AggregateReduceFunction = (
+  collected: CollectedSession[],
+) => AggregateTableRow[] | Promise<AggregateTableRow[]>;
+
+type AggregateDefinition = {
+  collect: AggregateCollectFunction;
+  reduce: AggregateReduceFunction;
+};
+
+interface AggregateOptions {
+  label?: string;
+  condition?: ConditionFunction;
+}
+
+interface CollectedSession {
+  projectName: string;
+  sessionId: string;
+  values: Record<string, AggregateValue>;
+}
+
+type AggregateTableRow = Record<string, AggregateValue>;
+
+interface AggregatePayload {
+  aggregates: {
+    name: string;
+    label: string;
+    rows: AggregateTableRow[];
+    columns: string[];
+  }[];
+  totalSessions: number;
+  totalDurationMs: number;
+}
+```
+
+---
+
+### `app.auth(options)`
+
+Configure username/password authentication. When at least one user is configured (via `app.auth()`, `--auth-user`, or `CLAUDEYE_AUTH_USERS` env var), all UI routes are protected by a login page. Users from all sources are merged.
+
+- **`options.users`** - array of `{ username: string; password: string }` objects
+
+```ts
+app.auth({ users: [
+  { username: 'admin', password: 'secret' },
+  { username: 'viewer', password: 'readonly' },
+] });
+```
+
+Chainable — returns the app instance:
+
+```js
+app
+  .auth({ users: [{ username: 'admin', password: 'secret' }] })
+  .eval('my-eval', fn)
+  .listen();
+```
+
+When auth is active:
+- All UI routes redirect to `/login` for unauthenticated users
+- A signed HMAC-SHA256 session cookie (`claudeye_session`) is set on login, with 24h expiry
+- The navbar shows a **Sign out** button
+- If no users are configured, auth is completely disabled (no login page, no blocking)
+
+#### Multiple Sources
+
+Users from CLI, environment, and API are merged:
+
+```bash
+# CLI
+claudeye --evals ./my-evals.js --auth-user ops:pass123
+
+# Environment (comma-separated user:password pairs)
+CLAUDEYE_AUTH_USERS=admin:secret claudeye --evals ./my-evals.js
+
+# API (in my-evals.js)
+app.auth({ users: [{ username: 'dev', password: 'devpass' }] });
+```
+
+All three users (`ops`, `admin`, `dev`) would be valid.
+
+---
+
+### `app.listen(port?, options?)`
+
+Start the Claudeye dashboard server.
+
+- **`port`** - port number (default: 8020)
+- **`options.host`** - bind address (default: `"localhost"`, use `"0.0.0.0"` for LAN)
+- **`options.open`** - auto-open browser (default: `true`)
+
+When the file is loaded via `--evals` or `CLAUDEYE_EVALS_MODULE`, `listen()` is a no-op. It won't spawn a duplicate server.
+
+```js
+const app = createApp();
+
+app.eval('my-eval', fn);
+app.enrich('my-enricher', fn);
+
+// Only starts a server when run directly with `node` or `bun`
+app.listen(3000, { host: '0.0.0.0', open: false });
+```
+
+You can also run your evals file directly with `bun my-evals.js` (or `node my-evals.js`) if you include `app.listen()`. This spawns the dashboard as a child process.
+
+---
+
+## Subagent Scope
+
+Evals, enrichments, and actions run at the session level by default. Use the `scope` option to target subagent logs.
+
+### Scope Options
+
+| Scope | Runs at session level | Runs at subagent level |
+|-------|:---:|:---:|
+| `'session'` (default) | Yes | No |
+| `'subagent'` | No | Yes |
+| `'both'` | Yes | Yes |
+
+### Subagent Context
+
+When running at subagent level, the `EvalContext` includes additional metadata:
+
+```js
+app.eval('adaptive-eval', (ctx) => {
+  if (ctx.source !== 'session') {
+    // Running at subagent level — source is "agent-{id}"
+    console.log(ctx.source);              // e.g. 'agent-a1b2c3'
+    console.log(ctx.subagentType);        // e.g. 'Explore'
+    console.log(ctx.subagentDescription); // e.g. 'Search for auth code'
+    console.log(ctx.parentSessionId);     // parent session ID
+  }
+  return { pass: true };
+}, { scope: 'both' });
+```
+
+### Combined Data in Subagent Scope
+
+Subagent-scoped evals and enrichments receive the full combined data (session + all subagents), not just the subagent's own entries. The `source` field in `EvalContext` directly matches the `_source` value on entries, so you can filter easily:
+
+```js
+// Subagent-scoped eval that filters to its own entries
+app.eval('explore-thoroughness', ({ entries, source }) => {
+  const myEntries = entries.filter(e => e._source === source);
+  return {
+    pass: myEntries.length > 5,
+    score: Math.min(myEntries.length / 20, 1),
+  };
+}, { scope: 'subagent', subagentType: 'Explore' });
+```
+
+### SubagentType Filtering
+
+When you specify `subagentType`, the eval/enrichment only runs for subagents of that type. Subagents of other types will not see the eval panel at all.
+
+```js
+// Only runs for Explore subagents
+app.eval('explore-thoroughness', ({ entries, source }) => {
+  const myEntries = entries.filter(e => e._source === source);
+  return {
+    pass: myEntries.length > 5,
+    score: Math.min(myEntries.length / 20, 1),
+    message: `${myEntries.length} entries explored`,
+  };
+}, { scope: 'subagent', subagentType: 'Explore' });
+
+// Runs for all subagent types
+app.eval('agent-efficiency', ({ stats }) => ({
+  pass: stats.turnCount <= 10,
+  score: Math.max(0, 1 - stats.turnCount / 20),
+  message: `${stats.turnCount} turns`,
+}), { scope: 'subagent' });
+
+// Subagent-scoped enrichment
+app.enrich('agent-summary',
+  ({ stats, entries }) => ({
+    'Agent Turns': stats.turnCount,
+    'Agent Tool Calls': stats.toolCallCount,
+    'Agent Entries': entries.length,
+  }),
+  { scope: 'subagent' }
+);
+
+// Scoped to both session and subagent level
+app.eval('quality-check', ({ stats, source }) => ({
+  pass: stats.toolCallCount <= 20,
+  score: Math.max(0, 1 - stats.toolCallCount / 40),
+  message: `${source}: ${stats.toolCallCount} tool calls`,
+}), { scope: 'both' });
+```
+
+---
+
+## Evaluation Order
+
+When a session is loaded, conditions are evaluated in this order:
+
+```
+1. Global condition checked
+   |-- Returns false or throws -> ALL evals/enrichments marked "skipped"
+   \-- Returns true -> proceed to step 2
+
+2. For each eval/enrichment:
+   |-- Has per-item condition?
+   |   |-- Returns false -> that item marked "skipped"
+   |   |-- Throws -> that item marked "errored" (not skipped)
+   |   \-- Returns true -> run the function
+   \-- No condition -> run the function
+
+3. Function executes
+   |-- Returns result -> recorded normally
+   \-- Throws -> marked "errored", other items still run
+```
+
+---
+
+## UI Behavior
+
+In the dashboard, conditional results appear as follows:
+
+| Status | Evals Panel | Enrichments Panel |
+|--------|-------------|-------------------|
+| **Skipped** | Grayed-out row with "skipped" label | Grayed-out row with "skipped" label |
+| **Condition error** | Row with warning icon and error message | Row with warning icon and error message |
+| **Passed / Data** | Green check with score bar | Key-value pairs grouped by enricher |
+| **Failed** | Red X with score bar | N/A |
+
+Skipped items are counted separately in the summary bar (e.g. "2 passed, 1 skipped").
+
+---
+
+## Types
+
+All TypeScript types exported from `claudeye`:
+
+### `EvalContext`
+
+Both evals and enrichers receive the same context object:
+
+```ts
+interface EvalContext {
+  entries: Record<string, unknown>[];  // Combined session + subagent JSONL lines, each tagged with `_source`
+  stats: EvalLogStats;                 // Computed stats across all entries (session + subagent)
+  projectName: string;                 // Encoded project folder name
+  sessionId: string;                   // Session UUID
+  source: string;                      // "session" or "agent-{id}" — matches entry._source directly
+  subagentType?: string;               // e.g. 'Explore', 'Bash' (subagent scope only)
+  subagentDescription?: string;        // Short description (subagent scope only)
+  parentSessionId?: string;            // Parent session ID (subagent scope only)
+  evalResults?: Record<string, {       // Cached eval results (cachedOnly views only)
+    pass: boolean;
+    score: number;
+    error?: string;
+    message?: string;
+  }>;
+}
+```
+
+`entries` contains the **raw JSONL data** from the session and all its subagents combined. Every line from the session log file and its subagent log files is parsed as JSON and included. Each entry has a `_source` field: `"session"` for main session entries, or `"agent-{id}"` for subagent entries. This means:
+
+- Tool-result lines (which the display view merges into tool_use blocks) are present as separate entries
+- All entry types are included: `user`, `assistant`, `system`, `tool_result`, `queue-operation`, etc.
+- Properties are accessed directly (e.g. `e.usage?.total_tokens`) rather than through a `.raw` wrapper
+- Filter by `e._source === "session"` to get only main session data
+- Filter by `e._source` starting with `"agent-"` to get subagent data
+
+### `EvalLogEntry` (helper type)
+
+`EvalLogEntry` is exported as a convenience type for describing the display-oriented parsed entries, but it is **not** the type of `EvalContext.entries`. The entries passed to evals and enrichments are raw JSONL objects (`Record<string, unknown>[]`).
+
+```ts
+interface EvalLogEntry {
+  type: string;
+  _source?: string;  // "session" or "agent-{id}"
+  uuid: string;
+  parentUuid: string | null;
+  timestamp: string;
+  timestampMs: number;
+  timestampFormatted: string;
+  message?: {
+    role: string;
+    content: string | EvalContentBlock[];
+    model?: string;
+  };
+  raw?: Record<string, unknown>;
+  label?: string;
+}
+```
+
+### `EvalLogStats`
+
+> Stats are computed across all entries (session + subagent combined). Use `_source` filtering on entries before computing custom scoped metrics if needed.
+
+```ts
+interface EvalLogStats {
+  turnCount: number;      // Number of conversation turns
+  userCount: number;      // Number of user messages
+  assistantCount: number; // Number of assistant responses
+  toolCallCount: number;  // Total tool invocations
+  subagentCount: number;  // Number of subagent spawns
+  duration: string;       // Formatted duration (e.g. "2m 15s")
+  models: string[];       // Distinct model IDs used
+}
+```
+
+### `EvalResult`
+
+```ts
+interface EvalResult {
+  pass: boolean;                          // Did the eval pass?
+  score?: number;                         // 0-1, clamped automatically (default: 1.0)
+  message?: string;                       // Shown in the UI
+  metadata?: Record<string, unknown>;     // Arbitrary data
+}
+```
+
+### `EnrichmentResult`
+
+```ts
+type EnrichmentResult = Record<string, string | number | boolean>;
+```
+
+### `ConditionFunction`
+
+```ts
+type ConditionFunction = (context: EvalContext) => boolean | Promise<boolean>;
+```
+
+### `FilterValue`
+
+```ts
+type FilterValue = boolean | number | string;
+```
+
+### `FilterFunction`
+
+```ts
+type FilterFunction = (context: EvalContext) => FilterValue | Promise<FilterValue>;
+```
+
+### `FilterOptions`
+
+```ts
+interface FilterOptions {
+  label?: string;                // Human-readable tile label (defaults to name)
+  condition?: ConditionFunction; // Per-filter gate
+}
+```
+
+### `FilterMeta`
+
+Metadata auto-derived from computed filter values. Discriminated union by `type`:
+
+```ts
+type FilterMeta =
+  | { type: 'boolean'; name: string; label: string }
+  | { type: 'number';  name: string; label: string; min: number; max: number }
+  | { type: 'string';  name: string; label: string; values: string[] }
+  | { type: 'date';    name: string; label: string; min: string; max: string };
+```
+
+### `DashboardPayload`
+
+```ts
+interface DashboardPayload {
+  sessions: DashboardSessionRow[];  // One page of matching sessions
+  filterMeta: FilterMeta[];         // One per registered filter
+  totalDurationMs: number;          // Server-side computation time
+  totalCount: number;               // Total sessions before filtering
+  matchingCount: number;            // Total sessions after filtering
+  page: number;                     // Current page (1-based)
+  pageSize: number;                 // Items per page
+}
+
+interface DashboardSessionRow {
+  projectName: string;
+  sessionId: string;
+  lastModified: string;             // ISO 8601
+  lastModifiedFormatted: string;    // Human-readable
+  filterValues: Record<string, FilterValue>;
+}
+```
+
+### `EvalScope`
+
+```ts
+type EvalScope = 'session' | 'subagent' | 'both';
+```
+
+---
+
+## Examples
+
+Complete, runnable example files. Save any of these as a `.js` file and run with `claudeye --evals ./your-file.js`.
+
+### Example: Basic Evals & Enrichments
+
+The quickstart example — define evals and enrichments in one file:
+
+```js
+import { createApp } from 'claudeye';
+
+const app = createApp();
+
+// ── Global condition ────────────────────────────────────────────
+// Skip empty sessions across evals, enrichments, AND dashboard filters.
+app.condition(({ entries }) => entries.length > 0);
+
+// ── Evals ───────────────────────────────────────────────────────
+
+app.eval('under-50-turns', ({ stats }) => ({
+  pass: stats.turnCount <= 50,
+  score: Math.max(0, 1 - stats.turnCount / 100),
+  message: `${stats.turnCount} turn(s)`,
+}));
+
+app.eval('has-completion', ({ entries }) => {
+  const last = [...entries].reverse().find(e => e.type === 'assistant');
+  const hasText = last?.message?.content?.some?.(b => b.type === 'text');
+  return {
+    pass: !!hasText,
+    score: hasText ? 1.0 : 0,
+    message: hasText ? 'Ended with text' : 'No final text response',
+  };
+});
+
+app.eval('session-tool-count', ({ entries }) => {
+  const sessionTools = entries
+    .filter(e => e._source === 'session' && e.type === 'assistant')
+    .flatMap(e => (e.message?.content || []).filter(b => b.type === 'tool_use'));
+  return {
+    pass: sessionTools.length <= 100,
+    score: Math.max(0, 1 - sessionTools.length / 200),
+    message: `${sessionTools.length} session-level tool calls`,
+  };
+});
+
+// ── Enrichments ─────────────────────────────────────────────────
+
+app.enrich('session-overview', ({ stats }) => ({
+  'Turns': stats.turnCount,
+  'Tool Calls': stats.toolCallCount,
+  'Subagents': stats.subagentCount,
+  'Duration': stats.duration,
+  'Models': stats.models.join(', ') || 'none',
+}));
+
+app.listen();
+```
+
+### Example: Dashboard Filters
+
+Named dashboard views with focused filter sets, evals, and enrichments:
+
+```js
+import { createApp } from 'claudeye';
+
+const app = createApp();
+
+// ── Global condition ────────────────────────────────────────────
+app.condition(({ entries }) => entries.length > 0);
+
+// ── Performance view ────────────────────────────────────────────
+app.dashboard.view('performance', { label: 'Performance Metrics' })
+  .filter({ preBuilt: ['lastModified'] })
+  .filter('turn-count', ({ stats }) => stats.turnCount, { label: 'Turn Count' })
+  .filter('tool-calls', ({ stats }) => stats.toolCallCount, { label: 'Tool Calls' })
+  .filter('avg-tools-per-turn',
+    ({ stats }) => stats.turnCount > 0
+      ? Math.round(stats.toolCallCount / stats.turnCount * 10) / 10
+      : 0,
+    {
+      label: 'Avg Tools/Turn',
+      condition: ({ stats }) => stats.toolCallCount > 0,
+    }
+  );
+
+// ── Quality view ────────────────────────────────────────────────
+app.dashboard.view('quality', { label: 'Quality Checks' })
+  .filter('has-errors', ({ entries }) =>
+    entries.some(e =>
+      e.type === 'assistant' &&
+      Array.isArray(e.message?.content) &&
+      e.message.content.some(b => b.type === 'tool_use' && b.is_error)
+    ),
+    { label: 'Has Errors' }
+  )
+  .filter('primary-model', ({ stats }) => stats.models[0] || 'unknown',
+    { label: 'Primary Model' }
+  )
+  .filter('uses-subagents', ({ stats }) => stats.subagentCount > 0,
+    { label: 'Uses Subagents' }
+  );
+
+// ── Evals ───────────────────────────────────────────────────────
+
+app.eval('under-50-turns', ({ stats }) => ({
+  pass: stats.turnCount <= 50,
+  score: Math.max(0, 1 - stats.turnCount / 100),
+  message: `${stats.turnCount} turn(s)`,
+}));
+
+app.eval('has-completion', ({ entries }) => {
+  const last = [...entries].reverse().find(e => e.type === 'assistant');
+  const hasText = last?.message?.content?.some?.(b => b.type === 'text');
+  return {
+    pass: !!hasText,
+    score: hasText ? 1.0 : 0,
+    message: hasText ? 'Ended with text' : 'No final text response',
+  };
+});
+
+app.eval('session-tool-count', ({ entries }) => {
+  const sessionTools = entries
+    .filter(e => e._source === 'session' && e.type === 'assistant')
+    .flatMap(e => (e.message?.content || []).filter(b => b.type === 'tool_use'));
+  return {
+    pass: sessionTools.length <= 100,
+    score: Math.max(0, 1 - sessionTools.length / 200),
+    message: `${sessionTools.length} session-level tool calls`,
+  };
+});
+
+// ── Enrichments ─────────────────────────────────────────────────
+
+app.enrich('session-overview', ({ stats }) => ({
+  'Turns': stats.turnCount,
+  'Tool Calls': stats.toolCallCount,
+  'Subagents': stats.subagentCount,
+  'Duration': stats.duration,
+  'Models': stats.models.join(', ') || 'none',
+}));
+
+app.listen();
+```
+
+### Example: Multi-View Dashboard
+
+Multiple named views with focused filter sets:
+
+```js
+import { createApp } from 'claudeye';
+
+const app = createApp();
+
+// ── Performance view ────────────────────────────────────────────
+// Metrics about session length and tool usage.
+app.dashboard.view('performance', { label: 'Performance Metrics' })
+  .filter('turn-count', ({ stats }) => stats.turnCount,
+    { label: 'Turn Count' })
+  .filter('tool-calls', ({ stats }) => stats.toolCallCount,
+    { label: 'Tool Calls' })
+  .filter('uses-subagents', ({ stats }) => stats.subagentCount > 0,
+    { label: 'Uses Subagents' });
+
+// ── Quality view ────────────────────────────────────────────────
+// Error and model analysis.
+app.dashboard.view('quality', { label: 'Quality Checks' })
+  .filter('has-errors', ({ entries }) =>
+    entries.some(e =>
+      e.type === 'assistant' &&
+      Array.isArray(e.message?.content) &&
+      e.message.content.some(b => b.type === 'tool_use' && b.is_error)
+    ),
+    { label: 'Has Errors' })
+  .filter('primary-model', ({ stats }) => stats.models[0] || 'unknown',
+    { label: 'Primary Model' });
+
+// ── Backward-compatible default filter ──────────────────────────
+// app.dashboard.filter() still works — goes to the "default" view.
+// Default filters show below the view cards on /dashboard.
+app.dashboard.filter('model', ({ stats }) => stats.models[0] || 'unknown',
+  { label: 'Model' }
+);
+
+app.listen();
+```
+
+### Example: Eval Score Filters (cachedOnly)
+
+Per-eval score filters on a `cachedOnly` dashboard view. When a view uses `cachedOnly: true`, filter functions receive `ctx.evalResults` containing cached eval results:
+
+```js
+import { createApp } from 'claudeye';
+
+const app = createApp();
+
+// ── Register evals that produce scores ──────────────────────────
+app.eval('quality', ({ entries }) => {
+  const assistantMsgs = entries.filter(e => e.type === 'assistant');
+  const avgLength = assistantMsgs.reduce((sum, e) => {
+    const content = typeof e.message?.content === 'string' ? e.message.content : '';
+    return sum + content.length;
+  }, 0) / (assistantMsgs.length || 1);
+  const score = Math.min(avgLength / 500, 1);
+  return { pass: score > 0.5, score };
+});
+
+app.eval('speed', ({ stats }) => {
+  const durationSec = parseFloat(stats.duration) || 60;
+  const score = Math.max(0, 1 - durationSec / 120);
+  return { pass: score > 0.3, score };
+});
+
+// ── cachedOnly view with per-eval score filters ─────────────────
+app.dashboard.view('eval-results', { cachedOnly: true, label: 'Eval Score Filters' })
+  .filter('quality-score',
+    (ctx) => ctx.evalResults?.['quality']?.score ?? 0,
+    { label: 'Quality Score' })
+  .filter('speed-score',
+    (ctx) => ctx.evalResults?.['speed']?.score ?? 0,
+    { label: 'Speed Score' })
+  .filter('all-passing', (ctx) => {
+    if (!ctx.evalResults) return false;
+    return Object.values(ctx.evalResults).every(r => r.pass);
+  }, { label: 'All Evals Passing' });
+
+app.listen();
+```
+
+### Example: Actions
+
+On-demand tasks triggered manually from the dashboard. Actions receive the full session context plus cached eval and enrichment results:
+
+```js
+import { createApp } from 'claudeye';
+
+const app = createApp();
+
+// ── Evals (actions can read these results) ──────────────────────
+
+app.eval('under-50-turns', ({ stats }) => ({
+  pass: stats.turnCount <= 50,
+  score: Math.max(0, 1 - stats.turnCount / 100),
+  message: `${stats.turnCount} turn(s)`,
+}));
+
+app.eval('has-completion', ({ entries }) => {
+  const last = [...entries].reverse().find(e => e.type === 'assistant');
+  const hasText = last?.message?.content?.some?.(b => b.type === 'text');
+  return {
+    pass: !!hasText,
+    score: hasText ? 1.0 : 0,
+    message: hasText ? 'Ended with text' : 'No final text response',
+  };
+});
+
+// ── Enrichments (actions can read these results too) ────────────
+
+app.enrich('overview', ({ stats }) => ({
+  'Turns': stats.turnCount,
+  'Tool Calls': stats.toolCallCount,
+  'Models': stats.models.join(', ') || 'none',
+}));
+
+// ── Actions ─────────────────────────────────────────────────────
+
+// Session summary: combines stats with eval pass counts
+app.action('session-summary', ({ stats, evalResults }) => {
+  const evalNames = Object.keys(evalResults);
+  const passCount = evalNames.filter(n => evalResults[n]?.pass).length;
+  return {
+    output: [
+      `Session: ${stats.turnCount} turns, ${stats.toolCallCount} tool calls`,
+      `Duration: ${stats.duration}`,
+      `Models: ${stats.models.join(', ') || 'unknown'}`,
+      `Evals: ${passCount}/${evalNames.length} passed`,
+    ].join('\n'),
+    status: 'success',
+    message: 'Summary generated',
+  };
+});
+
+// Export metrics: gathers enrichment data into a text report
+app.action('export-metrics', ({ stats, enrichmentResults }) => {
+  const enrichData = {};
+  for (const [name, result] of Object.entries(enrichmentResults)) {
+    if (result.data) Object.assign(enrichData, result.data);
+  }
+  const lines = [
+    ...Object.entries(enrichData).map(([k, v]) => `${k}: ${v}`),
+    `turnCount: ${stats.turnCount}`,
+    `toolCallCount: ${stats.toolCallCount}`,
+  ];
+  return {
+    output: lines.join('\n'),
+    status: 'success',
+    message: `Exported ${Object.keys(enrichData).length + 2} metrics`,
+  };
+});
+
+// Tool inventory: lists unique tools used in the session
+app.action('tool-inventory', ({ entries }) => {
+  const toolUses = entries.filter(e =>
+    e.type === 'assistant' &&
+    Array.isArray(e.message?.content) &&
+    e.message.content.some(b => b.type === 'tool_use')
+  );
+  const toolNames = [...new Set(toolUses.flatMap(e =>
+    (e.message?.content || []).filter(b => b.type === 'tool_use').map(b => b.name)
+  ))];
+  return {
+    output: toolNames.length > 0
+      ? `Tools used:\n${toolNames.map(t => `  - ${t}`).join('\n')}`
+      : 'No tools used in this session',
+    status: 'success',
+  };
+}, { condition: ({ stats }) => stats.toolCallCount > 0 });
+
+// Side-effect action: always re-runs (cache: false)
+app.action('write-report', async ({ projectName, sessionId, stats }) => {
+  const fs = await import('fs/promises');
+  await fs.appendFile('session-reports.jsonl', JSON.stringify({
+    projectName, sessionId, turns: stats.turnCount,
+    timestamp: new Date().toISOString(),
+  }) + '\n');
+  return { status: 'success', message: 'Report appended' };
+}, { cache: false });
+
+app.listen();
+```
+
+### Example: Alerts
+
+Callbacks that fire after all evals and enrichments complete for a session:
+
+```js
+import { createApp } from 'claudeye';
+
+const app = createApp();
+
+// ── Evals ───────────────────────────────────────────────────────
+
+app.eval('under-50-turns', ({ stats }) => ({
+  pass: stats.turnCount <= 50,
+  score: Math.max(0, 1 - stats.turnCount / 100),
+  message: `${stats.turnCount} turn(s)`,
+}));
+
+app.eval('has-completion', ({ entries }) => {
+  const last = [...entries].reverse().find(e => e.type === 'assistant');
+  const hasText = last?.message?.content?.some?.(b => b.type === 'text');
+  return {
+    pass: !!hasText,
+    score: hasText ? 1.0 : 0,
+    message: hasText ? 'Ended with text' : 'No final text response',
+  };
+});
+
+// ── Enrichments ─────────────────────────────────────────────────
+
+app.enrich('overview', ({ stats }) => ({
+  'Turns': stats.turnCount,
+  'Tool Calls': stats.toolCallCount,
+  'Models': stats.models.join(', ') || 'none',
+}));
+
+// ── Alerts ──────────────────────────────────────────────────────
+
+// Console log: always fires, logs a summary line
+app.alert('log-results', ({ projectName, sessionId, evalSummary, enrichSummary }) => {
+  const evals = evalSummary
+    ? `${evalSummary.passCount} pass, ${evalSummary.failCount} fail, ${evalSummary.errorCount} error`
+    : 'no evals';
+  const enrichments = enrichSummary
+    ? `${enrichSummary.results.length} enrichments`
+    : 'no enrichments';
+  console.log(`[ALERT] ${projectName}/${sessionId}: ${evals} | ${enrichments}`);
+});
+
+// Failure alert: only logs when evals fail
+app.alert('warn-on-failure', ({ projectName, sessionId, evalSummary }) => {
+  if (evalSummary && evalSummary.failCount > 0) {
+    const failedNames = evalSummary.results
+      .filter(r => !r.error && !r.skipped && !r.pass)
+      .map(r => r.name);
+    console.warn(
+      `[FAILURE] ${projectName}/${sessionId}: ${failedNames.join(', ')} failed`
+    );
+  }
+});
+
+// Slack webhook example (uncomment and replace the URL to enable):
+// app.alert('slack-on-failure', async ({ projectName, sessionId, evalSummary }) => {
+//   if (evalSummary && evalSummary.failCount > 0) {
+//     await fetch('https://hooks.slack.com/services/T.../B.../xxx', {
+//       method: 'POST',
+//       headers: { 'Content-Type': 'application/json' },
+//       body: JSON.stringify({
+//         text: `${evalSummary.failCount} evals failed for ${projectName}/${sessionId}`,
+//       }),
+//     });
+//   }
+// });
+
+app.listen();
+```
+
+### Example: Minimal Filters Only
+
+A minimal example — a single named view with filters, no evals or enrichments:
+
+```js
+import { createApp } from 'claudeye';
+
+const app = createApp();
+
+app.dashboard.view('overview', { label: 'Session Overview' })
+  .filter({ preBuilt: ['lastModified'] })
+  .filter('model', ({ stats }) => stats.models[0] || 'unknown',
+    { label: 'Model' })
+  .filter('turns', ({ stats }) => stats.turnCount,
+    { label: 'Turns' })
+  .filter('used-tools', ({ stats }) => stats.toolCallCount > 0,
+    { label: 'Used Tools' });
+
+app.listen();
+```
+
+---
+
+## Background Queue Processing
+
+Enable background processing to automatically scan and evaluate all sessions on a timer:
+
+```bash
+claudeye --evals ./my-evals.js --queue-interval 60
+```
+
+Use `app.queueCondition()` to gate which sessions the background queue processes:
+
+```js
+// Only process sessions with more than 5 entries
+app.queueCondition(({ entries }) => entries.length > 5);
+```
+
+The condition receives the full `EvalContext` and returns a boolean. If false, the session is skipped entirely. Results are cached per-session and auto-invalidate when the session file or condition function changes.
+
+### How the Queue Works
+
+The queue is **unified** — every individual eval and enrichment (session-scoped, subagent-scoped, UI-triggered, or background-scanned) passes through a single priority queue with bounded concurrency.
+
+1. **Foreground (always active):** When a session page loads or a re-run is triggered, each uncached eval/enrichment is enqueued at HIGH priority via `queuePerItem()` and processed immediately (up to the concurrency limit)
+2. **Background (opt-in):** When `CLAUDEYE_QUEUE_INTERVAL` is set, a timer scans all projects for uncached sessions and enqueues individual uncached evals/enrichments at LOW priority
+3. **Priority:** HIGH (foreground/UI) items are always processed before LOW (background) items
+4. **Dedup:** If the same item is enqueued twice, the existing entry is upgraded to the higher priority
+5. **Subagent support:** Subagent evals/enrichments go through the same queue. The session ID is encoded as `sessionId/agent-agentId` for tracking purposes
+6. **Alerts:** After each successful item completes, the queue checks if any pending/processing work remains for that session. When no work remains, alerts fire once per content version
+
+### Queue Status UI
+
+The queue status is visible in two places:
+
+**Navbar dropdown** — shows current processing items (max 7) and pending items with priority badges. Badge count = pending + processing.
+
+**`/queue` details page** — three tabs:
+- **In Queue** — pending items with type badge, item name, session link, priority, queued time
+- **Processing** — active items with spinner, type badge, item name, session link, started time
+- **Processed** — completed items with type badge, item name, session link, duration, success/fail icon, completed time. Data is loaded from disk via paginated JSONL files (25 entries per page), so history survives process restarts
+
+**Dashboard panel** — collapsible panel showing queue state with processing and pending tables, background processor indicator, and error list.
+
+All views auto-refresh and self-hide when there's no queue activity.
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CLAUDEYE_QUEUE_INTERVAL` | Background scan interval in seconds | disabled |
+| `CLAUDEYE_QUEUE_CONCURRENCY` | Max parallel items per batch | `2` |
+| `CLAUDEYE_QUEUE_HISTORY_TTL` | Seconds to keep completed items | `3600` |
+| `CLAUDEYE_QUEUE_MAX_ITEMS` | Max items to enqueue per scan (0=unlimited) | `500` |
+| `CLAUDEYE_LOG_LEVEL` | Log verbosity: `info`, `warn`, `error` | `warn` |
+
+At `info` level, all log lines (including `ACTIVITY` lines for user actions) are emitted. At `warn` (default), only warnings and errors appear. At `error`, only errors are shown.
+
+---
+
+## Caching
+
+Caching is **always on**. Results are cached to `~/.claudeye/cache/` and automatically invalidated when session logs or eval definitions change. Click **Re-run** in the dashboard to bypass the cache.
+
+```bash
+claudeye --cache-path /tmp/cc  # Custom cache location
+claudeye --cache-clear         # Clear cache and exit
+```
+
+---
+
+## Authentication
+
+Claudeye ships with **opt-in** username/password auth. When no users are configured, everything works exactly as before — no login page, no blocking.
+
+### Enable via CLI
+
+```bash
+# Single user
+claudeye --auth-user admin:secret
+
+# Multiple users
+claudeye --auth-user admin:secret --auth-user viewer:readonly
+```
+
+### Enable via environment variable
+
+```bash
+CLAUDEYE_AUTH_USERS=admin:secret claudeye
+CLAUDEYE_AUTH_USERS=admin:secret,viewer:readonly claudeye
+```
+
+### Enable via the programmatic API
+
+```js
+import { createApp } from 'claudeye';
+
+const app = createApp();
+
+app.auth({ users: [
+  { username: 'admin', password: 'secret' },
+  { username: 'viewer', password: 'readonly' },
+] });
+
+app.listen();
+```
+
+All three methods can be combined — users from CLI flags, the env var, and `app.auth()` are merged together.
+
+When auth is active, all UI routes redirect to `/login`. After signing in, a signed session cookie (24h expiry) grants access. A **Sign out** button appears in the navbar.
+
+---
+
+## Deployment with PM2
+
+For production deployments, use PM2 with Bun as the interpreter:
+
+```js
+// ecosystem.config.cjs
+module.exports = {
+  apps: [{
+    name: 'claudeye',
+    script: 'node_modules/.bin/next',
+    args: 'start',
+    interpreter: 'bun',
+    cwd: '/path/to/claudeye',
+    env: {
+      PORT: 8020,
+      HOSTNAME: '0.0.0.0',
+      CLAUDE_PROJECTS_PATH: '/home/user/.claude/projects',
+      CLAUDEYE_EVALS_MODULE: './my-evals.js',
+      CLAUDEYE_QUEUE_INTERVAL: '60',
+    },
+  }],
+};
+```
+
+```bash
+# Start
+pm2 start ecosystem.config.cjs
+
+# Monitor
+pm2 monit
+
+# Auto-restart on reboot
+pm2 startup
+pm2 save
+```
+
+---
+
+## How It Works
+
+1. `createApp()` + `app.eval()` / `app.enrich()` / `app.action()` / `app.alert()` / `app.condition()` / `app.queueCondition()` / `app.dashboard.view()` / `app.dashboard.filter()` / `app.dashboard.aggregate()` register functions in global registries
+2. When you run `claudeye --evals ./my-file.js`, the server dynamically imports your file, populating the registries
+3. All eval/enrichment execution routes through a unified priority queue. Each individual eval and enrichment is a separate queue item. UI requests use HIGH priority; background scanning uses LOW priority
+4. Each item runs through: cache check → execute if uncached → cache result → check if session complete → fire alerts if complete
+5. The global condition is checked first. If it fails, everything is skipped
+6. Per-item conditions are checked individually. Skipped items don't block others
+7. Each function is individually error-isolated. If one throws, the others still run
+8. After all evals and enrichments complete, registered alerts fire with the complete `AlertContext` (eval summary + enrichment summary)
+9. Results are serialized and displayed in separate panels in the dashboard UI
+10. Named dashboard views (`/dashboard`) show a view index; each view (`/dashboard/[viewName]`) computes filter values incrementally (only new/changed sessions are processed), then filters and paginates server-side for efficiency
+11. Dashboard aggregates run a separate server action that collects per-session values (with eval/enrichment/filter results) and reduces them via user-defined reduce functions into sortable summary tables
+12. When `CLAUDEYE_QUEUE_INTERVAL` is set, a background processor scans for uncached items on a timer. Track queue state at `/queue` or via the navbar dropdown
+
+---
+
+## Community
+
+- [Discord](https://discord.com/invite/zT92CAgvkj) - get help and connect with other developers
+- [Issues](https://github.com/exospherehost/claudeye/issues) - bug reports and feature requests
+
+## License
+
+MIT + Commons Clause. See [LICENSE](./LICENSE).