npm - claudeye - Versions diffs - 1.0.9 → 1.1.0 - Mend

claudeye 1.0.9 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/README.md +17 -2643
package/package.json +10 -10

package/README.md CHANGED Viewed

@@ -1,2656 +1,30 @@
-```
-  ____ _                 _
- / ___| | __ _ _   _  __| | ___ _   _  ___
-| |   | |/ _` | | | |/ _` |/ _ \ | | |/ _ \
-| |___| | (_| | |_| | (_| |  __/ |_| |  __/
- \____|_|\__,_|\__,_|\__,_|\___|\__, |\___|
-                                |___/
-```
+# Claudeye is now FailproofAI — and we're open source!
-# Claudeye: Oversight and Observability for Claude Code Agents
+Hey there, fellow agent wranglers!
-**Uncover** what your agents did.
-**Understand** where they struggle.
-**Utilize** insights to improve.
+We've got some big news: **Claudeye has evolved.** New name. New home. Same mission of keeping your AI agents honest — but now with the doors wide open.
-[![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)
-[![Docs](https://img.shields.io/badge/docs-claudeye.exosphere.host-blue)](https://claudeye.exosphere.host)
+**Claudeye is now [FailproofAI](https://befailproof.ai)**, and it's fully open source.
-## Table of Contents
+That's right — all the oversight, observability, session replay, custom evals, and hook policies you know and love? Free. Open. Yours to fork, extend, and contribute to.
-- [What is Claudeye?](#what-is-claudeye)
-- [Quick Start](#quick-start)
-- [Hook Policies](#protect-hook-policies)
-- [Enterprise](#enterprise)
-- [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.cacheInvalidation(fn)`](#appcacheinvalidationfn)
-  - [`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)
-- [Telemetry](#telemetry)
-- [How It Works](#how-it-works)
-- [Community](#community)
-- [License](#license)
+## Where to find us
----
+| | |
+|---|---|
+| **GitHub** | [github.com/exospherehost/failproofai](https://github.com/exospherehost/failproofai) |
+| **Website** | [befailproof.ai](https://befailproof.ai) |
-## What is Claudeye?
+## Why the rename?
-Claudeye is an oversight and observability tool for Claude Code agents (CLI and Agents SDK).
+Because "keeping an eye on Claude" was just the beginning. FailproofAI is about making **all** your AI agents failproof — not just watching, but actively protecting, evaluating, and improving every session.
-AI agents execute shell commands, read files, and make changes autonomously — without guardrails, they can `rm -rf /`, read your `.env` secrets, `sudo` install packages, or force-push to main. Claudeye ships **27 built-in hook policies** (free, with more added every update) that block dangerous actions in real time, before they execute. Beyond protection, it gives you full session replay, custom evals, enrichments, and a local-first dashboard. One command and you're in:
+Plus, let's be honest — *failproofai* just rolls off the tongue better at conferences.
-## Quick Start
+## What's next?
-```bash
-npm install -g claudeye && claudeye
-# or: bun install -g claudeye && claudeye
-```
+Head over to the new repo, give it a star, and join the fun. Whether you're building evals, writing hook policies, or just want to replay that one session where your agent tried to `rm -rf /` — we've got you covered.
-Opens your browser at `localhost:8020`. Reads from `~/.claude/projects` by default.
+See you on the other side!
-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.
-> **Important — Session retention:**  Claude Code automatically deletes
-> sessions older than 30 days by default. To keep sessions visible in Claudeye,
-> set the retention period in `~/.claude/settings.json`:
->
-> ```json
-> { "cleanupPeriodDays": 9999 }
-> ```
->
-> Set `cleanupPeriodDays` to the number of days you want to retain session
-> history. **Do NOT set it to `0`** — this wipes all stored sessions
-> immediately. See [Claude Code settings](https://code.claude.com/docs/en/settings)
-> for details.
-## Protect: Hook Policies
-AI agents can execute arbitrary shell commands. Without guardrails, Claude can accidentally `rm -rf /`, read your `.env` secrets, `sudo` install packages, force-push to main, or pipe a curl download to `sh`. Claudeye's hook policies sit in Claude Code's hook pipeline and block dangerous actions in real time — before they execute.
-### Quick Start
-```bash
-# Install with interactive policy selector (Enter to toggle, S to submit)
-claudeye --install-hooks
-# Or install all 27 policies at once
-claudeye --install-hooks all
-# Install specific policies
-claudeye --install-hooks block-sudo block-env-files sanitize-jwt
-# See what's enabled
-claudeye --list-hooks
-# Disable a specific policy
-claudeye --remove-hooks block-sudo
-# Remove all hooks from Claude Code
-claudeye --remove-hooks
-```
-### Available Policies
-| Policy | Default | What it blocks / warns |
-|--------|:-------:|----------------|
-| `sanitize-jwt` | On | Scrubs JWT tokens (`eyJ...`) from tool output before Claude sees them |
-| `sanitize-api-keys` | On | Scrubs API keys from tool output (OpenAI, Anthropic, GitHub, AWS, Stripe, Google) |
-| `sanitize-connection-strings` | On | Scrubs database connection strings with embedded credentials (`postgresql://user:pass@host`) from tool output |
-| `sanitize-private-key-content` | On | Scrubs PEM private key blocks (`-----BEGIN PRIVATE KEY-----`) from tool output |
-| `sanitize-bearer-tokens` | On | Scrubs `Authorization: Bearer <token>` headers from tool output |
-| `protect-env-vars` | On | `env`, `printenv`, `echo $SECRET`, `export API_KEY=...` |
-| `block-env-files` | On | Reading or writing `.env`, `.env.local`, `.env.production` |
-| `block-sudo` | On | Any `sudo` command |
-| `block-curl-pipe-sh` | On | `curl ... \| sh`, `wget ... \| bash` — remote code execution |
-| `block-push-master` | On | `git push origin main`, `git push origin master` |
-| `block-claudeye-commands` | On | Direct `claudeye` CLI invocations and `npm/bun/yarn/pnpm uninstall claudeye` |
-| `block-rm-rf` | Off | `rm -rf /`, `rm -rf ~`, `rm -rf /*` — catastrophic deletions |
-| `block-force-push` | Off | `git push --force`, `git push -f` |
-| `block-secrets-write` | Off | Writing to `.pem`, `.key`, `id_rsa`, `credentials` files |
-| `block-read-outside-cwd` | Off | Read/Glob/Grep/Bash read commands targeting files outside session CWD (`~/.claude/` allowed except `settings*.json` files) |
-| `block-work-on-main` | Off | `git commit`, `git merge`, `git rebase`, `git cherry-pick` when current branch is `main` or `master` |
-| `warn-destructive-sql` | Off | Warns before `DROP TABLE/DATABASE`, `TRUNCATE`, or `DELETE FROM` (without `WHERE`) via `psql`, `mysql`, `sqlite3`, etc. |
-| `warn-large-file-write` | Off | Warns when a Write tool payload exceeds 100KB (catches runaway generation loops) |
-| `warn-package-publish` | Off | Warns before `npm publish`, `cargo publish`, `gem push`, `poetry publish`, and similar |
-| `warn-repeated-tool-calls` | Off | Detects 3+ identical tool calls in session transcript; warns Claude to try a different approach |
-| `warn-git-amend` | Off | Warns before `git commit --amend`, which rewrites history and can diverge shared branches |
-| `warn-git-stash-drop` | Off | Warns before `git stash drop` or `git stash clear`, which permanently deletes stashed changes |
-| `warn-all-files-staged` | Off | Warns before `git add -A`, `git add --all`, or `git add .`, which may stage unintended files |
-| `warn-schema-alteration` | Off | Warns before `ALTER TABLE` with column or rename operations via `psql`, `mysql`, `sqlite3`, etc. |
-| `warn-global-package-install` | Off | Warns before `npm install -g`, `cargo install`, `yarn global add`, and similar global installs |
-| `warn-background-process` | Off | Warns before `nohup`, `screen -d`, `tmux new -d`, or commands backgrounded with `&` |
-| `verify-intent` | ⚗ Beta | LLM-powered: verifies all user intents were addressed before Claude stops. Retries up to 3 times. Requires `--configure-llm` setup. |
-Selection is saved to `~/.claudeye/hooks-config.json`. In non-TTY environments (CI/piped), the 11 default policies are used automatically. Re-running `--install-hooks` re-opens the selector with your current choices pre-loaded.
-> **Web UI** — You can also toggle individual policies on/off from the **Policies** page in the Claudeye dashboard without re-running the CLI. Changes take effect immediately for the next hook invocation.
-### Scoped Installation
-By default, hooks are installed at **user** scope (`~/.claude/settings.json`). Use `--scope` to target a different settings file:
-| Scope | File | Use case |
-|-------|------|----------|
-| `user` (default) | `~/.claude/settings.json` | Machine-wide — applies to all projects |
-| `project` | `{cwd}/.claude/settings.json` | Committed to git — shared across the team |
-| `local` | `{cwd}/.claude/settings.local.json` | Per-developer, gitignored |
-```bash
-# Install to project scope (committed, shared with team)
-claudeye --install-hooks all --scope project
-# Install to local scope (gitignored, personal)
-claudeye --install-hooks --scope local
-# Install to a specific project directory (without cd-ing into it)
-claudeye --install-hooks all --scope project --cwd /path/to/project
-# Remove from all scopes (default)
-claudeye --remove-hooks
-# Remove from a specific scope only
-claudeye --remove-hooks --scope project
-# See which scopes have hooks installed
-claudeye --list-hooks
-```
-#### The `--cwd` flag
-`--cwd` overrides `process.cwd()` when resolving settings paths for `--scope project` and `--scope local`. It has **no effect** with `--scope user` because user-scope settings always live at `~/.claude/settings.json` regardless of the working directory.
-This is intentional: the `user` scope is machine-wide and has no concept of a project directory, while `project` and `local` scopes resolve relative to a project root. `--cwd` lets you target a project without `cd`-ing into it — useful in scripts, CI pipelines, or when managing hooks across multiple repositories.
-```bash
-# These two are equivalent:
-cd /path/to/project && claudeye --install-hooks all --scope project
-claudeye --install-hooks all --scope project --cwd /path/to/project
-# --cwd is silently ignored here (user scope doesn't need a project directory)
-claudeye --install-hooks all --cwd /path/to/project
-# ↑ installs to ~/.claude/settings.json, NOT /path/to/project/.claude/settings.json
-# Always pair --cwd with --scope project or --scope local:
-claudeye --install-hooks all --scope project --cwd /path/to/project
-claudeye --remove-hooks --scope local --cwd /path/to/project
-claudeye --list-hooks --cwd /path/to/project
-```
-> **Why `--cwd` instead of `--project-dir`?** The flag was originally named `--project-dir`, but that was confusingly similar to `--projects-path` (which points to `~/.claude/projects` for the dashboard). `--cwd` is a widely understood convention (npm, pnpm, turbo all use it) and precisely describes the behavior: it sets the working directory for path resolution.
-**Avoid installing hooks in multiple scopes for the same project.** Claude Code merges settings from all scopes, so duplicate hooks may cause the same policy to evaluate twice. If `--list-hooks` shows hooks in multiple scopes, remove the extra installation with `--remove-hooks --scope <scope>`.
-### Policy Params
-Tune builtin policies without replacing them. Add a `policyParams` key to any `.claudeye/hooks-config.json` file:
-```json
-{
-  "enabledPolicies": ["block-sudo", "block-push-master", "warn-large-file-write"],
-  "policyParams": {
-    "block-sudo": {
-      "allowPatterns": ["sudo systemctl status *", "sudo journalctl *"]
-    },
-    "block-push-master": {
-      "protectedBranches": ["main", "master", "release"]
-    },
-    "warn-large-file-write": {
-      "thresholdKb": 512
-    }
-  }
-}
-```
-Config files are read from three scopes in priority order (first wins for params):
-1. `{cwd}/.claudeye/hooks-config.json` — project (can be committed)
-2. `{cwd}/.claudeye/hooks-config.local.json` — local (gitignore this)
-3. `~/.claudeye/hooks-config.json` — global (managed by `--install-hooks`)
-`enabledPolicies` are unioned across all three scopes.
-| Policy | Param | Type | Default | Description |
-|---|---|---|---|---|
-| `block-sudo` | `allowPatterns` | `string[]` | `[]` | Token-matched patterns to allow (e.g. `"sudo systemctl *"`) |
-| `block-rm-rf` | `allowPaths` | `string[]` | `[]` | Paths exempt from catastrophic-deletion blocking |
-| `block-read-outside-cwd` | `allowPaths` | `string[]` | `[]` | Paths outside cwd allowed for reading |
-| `block-push-master` | `protectedBranches` | `string[]` | `["main","master"]` | Branch names blocked from `git push` |
-| `block-work-on-main` | `protectedBranches` | `string[]` | `["main","master"]` | Branch names blocked for commits/merges |
-| `sanitize-api-keys` | `additionalPatterns` | `{regex,label}[]` | `[]` | Extra credential patterns to redact from output |
-| `block-secrets-write` | `additionalPatterns` | `string[]` | `[]` | Extra filename substrings to block writing |
-| `warn-large-file-write` | `thresholdKb` | `number` | `1024` | Threshold in KB above which file writes warn |
-> **`allowPatterns` safety** — `block-sudo` matches patterns against **parsed argv tokens**, not the raw command string. This prevents shell injection bypass like `sudo systemctl status; rm -rf /` from matching the pattern `sudo systemctl status *`.
-> **Web UI** — Policy params can also be edited directly from the **Policies tab** in the dashboard. Click the gear icon next to any policy with configurable parameters to open the editor.
-### Custom Hooks
-Register arbitrary hook logic in a JavaScript file using the `custom` keyword with `--install-hooks`:
-```bash
-claudeye --install-hooks custom ./my-hooks.js
-```
-**`my-hooks.js`**:
-```js
-import { customPolicies, allow, deny, instruct } from "claudeye";
-customPolicies.add({
-  name: "block-production-writes",
-  description: "Prevent writes to production config files",
-  match: { events: ["PreToolUse"] },
-  fn: async (ctx) => {
-    if (ctx.toolName === "Write") {
-      const path = ctx.toolInput?.file_path ?? "";
-      if (path.includes("production") || path.includes("prod.")) {
-        return deny("Writing to production config is blocked");
-      }
-    }
-    return allow();
-  },
-});
-```
-- **`ctx`** fields: `eventType`, `toolName`, `toolInput`, `payload`, `session`, `params`
-- **Return values**: `allow()`, `deny(message)`, `instruct(message)` — `deny(message)` is surfaced to Claude as `"Blocked by claudeye: <message>"`, consistent with builtin policy output
-- **Transitive imports**: files imported by your hooks entry point are automatically rewritten
-- **Fail-open**: any error or 10-second timeout returns `allow` and logs a warning — Claude is never blocked by a broken hook
-- **View loaded hooks**: `claudeye --list-hooks` shows a Custom Hooks section when a path is configured; the Policies tab in the dashboard shows each custom policy as a rich row with its name, description, and event scope (where defined), aligned with the built-in policy layout — edit the JS file to add, remove, or reorder them
-- **Remove**: `claudeye --remove-hooks custom` clears the path from global config
-- **Validation**: the file is loaded and validated at install time — if it has syntax errors, import failures, or registers no hooks, the install fails with an error and config is left unchanged
-**TypeScript types** (exported from `claudeye`):
-```ts
-interface PolicyContext {
-  eventType: string;
-  toolName?: string;
-  toolInput?: Record<string, unknown>;
-  payload: Record<string, unknown>;
-  session?: {
-    sessionId?: string;
-    transcriptPath?: string;
-    cwd?: string;
-    permissionMode?: string;
-    hookEventName?: string;
-  };
-  params?: Record<string, unknown>;
-}
-type PolicyDecision = "allow" | "deny" | "instruct";
-interface PolicyResult {
-  decision: PolicyDecision;
-  reason?: string;
-  message?: string;
-}
-interface CustomHook {
-  name: string;
-  description?: string;
-  match?: { events?: HookEventType[] };
-  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
-}
-```
-### LLM-Powered Policies
-Some policies (like `verify-intent`) use an external LLM to make intelligent decisions. These require a one-time configuration of an OpenAI-compatible API provider.
-#### Configure LLM Provider
-```bash
-# Interactive setup (prompts for API key, base URL, model)
-claudeye --configure-llm
-# Non-interactive (flags)
-claudeye --configure-llm --llm-api-key sk-xxx
-# Full configuration
-claudeye --configure-llm --llm-api-key sk-xxx --llm-base-url https://api.groq.com/openai/v1 --llm-model llama-3-70b
-```
-Any OpenAI-compatible API works — OpenAI, Groq, Together, Ollama (`http://localhost:11434/v1`), etc. Configuration is saved to `~/.claudeye/hooks-config.json`:
-```json
-{
-  "enabledPolicies": ["verify-intent"],
-  "llm": {
-    "apiKey": "sk-...",
-    "baseUrl": "https://api.openai.com/v1",
-    "model": "gpt-4o-mini"
-  }
-}
-```
-You can also override at runtime with environment variables (useful for CI):
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `CLAUDEYE_LLM_API_KEY` | API key | - |
-| `CLAUDEYE_LLM_BASE_URL` | Base URL | `https://api.openai.com/v1` |
-| `CLAUDEYE_LLM_MODEL` | Model name | `gpt-4o-mini` |
-#### verify-intent Policy
-The `verify-intent` policy fires when Claude says it's done (Stop event) and uses two LLM calls to check whether all user requests were actually completed:
-1. **Extract** — Reads the session transcript and asks the LLM to list all actionable user intents
-2. **Verify** — Sends the intents and transcript to the LLM, which checks if each was satisfied
-If any intents are unsatisfied, Claude is instructed to continue working. This repeats up to 3 times before allowing the stop.
-```bash
-# Enable after configuring LLM
-claudeye --install-hooks verify-intent
-```
-### Hook Activity Dashboard
-Every policy evaluation is logged to `~/.claudeye/cache/hook-activity/` and displayed at `/policies` in the dashboard. You can filter by decision (allow/deny), event type, and policy name — with pagination and auto-refresh.
-Deny events are also reported to anonymous telemetry (if enabled) so you can track how often policies fire across machines.
-### Hook Logging
-Hook processes write structured log output to **stderr**, controlled by two environment variables:
-| Variable | Purpose | Values | Default |
-|----------|---------|--------|---------|
-| `CLAUDEYE_LOG_LEVEL` | Log level threshold for both stderr and file output | `info`, `warn`, `error` | `warn` |
-| `CLAUDEYE_HOOK_LOG_FILE` | Enable file logging | unset/empty = off, `1` or `true` = `~/.claudeye/logs/`, or a custom directory path | disabled |
-#### What gets logged
-| Level | What is logged |
-|-------|---------------|
-| `info` | Event type, enabled policy count, matched policies, evaluation result (decision, policy name, duration), deny/instruct reasons |
-| `warn` | Stdin read failures, JSON payload parse failures, activity persistence failures |
-| `error` | Critical failures |
-Stderr output format: `[claudeye:hook] LEVEL message`
-#### Stderr-only logging (default)
-Set `CLAUDEYE_LOG_LEVEL` in your shell environment before launching Claude Code:
-```bash
-# See all hook activity in Claude Code's stderr
-CLAUDEYE_LOG_LEVEL=info claude
-# Only see warnings and errors (default behavior)
-CLAUDEYE_LOG_LEVEL=warn claude
-```
-#### File logging (opt-in)
-Enable persistent log files via `CLAUDEYE_HOOK_LOG_FILE`:
-```bash
-# Enable file logging to default directory (~/.claudeye/logs/)
-CLAUDEYE_HOOK_LOG_FILE=1 CLAUDEYE_LOG_LEVEL=info claude
-# Enable file logging to a custom directory
-CLAUDEYE_HOOK_LOG_FILE=/var/log/claudeye CLAUDEYE_LOG_LEVEL=info claude
-# In .bashrc or .zshrc for persistent config
-export CLAUDEYE_LOG_LEVEL=info
-export CLAUDEYE_HOOK_LOG_FILE=1
-```
-File logging details:
-- **Active log file:** `hooks.log` in the log directory
-- **Rotation:** Size-based at 500 KB — when `hooks.log` exceeds this, it is renamed to `hooks-{timestamp}.log` and a fresh `hooks.log` is created
-- **Format:** `[ISO timestamp] LEVEL message` (plain text, human-readable)
-- **Write mode:** Synchronous (hook processes are short-lived)
-- **Failure handling:** File logging is best-effort — if writes fail, the hook still completes normally
-### Using Hook Policies with Claude Agents SDK
-Claudeye hook policies work with both **Claude Code** and the **Claude Agents SDK** (Python and TypeScript). The same `claudeye --install-hooks` installation works for both — the difference is how the SDK discovers the hooks.
-#### Why it matters
-When you run `claudeye --install-hooks`, hook entries are written to `~/.claude/settings.json`. Claude Code reads this file automatically. The Claude Agents SDK also supports these shell-command hooks, but **only if you explicitly tell it to load settings**.
-Without this, your Agent SDK apps run with **zero hook protection** — even if you've installed hooks for Claude Code on the same machine.
-#### Python (Claude Agents SDK)
-Add `setting_sources=["user"]` to load hooks from `~/.claude/settings.json`:
-```python
-from claude_agent_sdk import query, ClaudeAgentOptions
-options = ClaudeAgentOptions(
-    setting_sources=["user"],  # Loads ~/.claude/settings.json (includes claudeye hooks)
-)
-for message in query(prompt="Refactor the auth module", options=options):
-    print(message)
-```
-To also load project-level settings (`.claude/settings.json` in the working directory):
-```python
-options = ClaudeAgentOptions(
-    setting_sources=["user", "project"],
-)
-```
-#### TypeScript (Claude Agents SDK)
-```typescript
-import { query } from "@anthropic-ai/claude-agent-sdk";
-for await (const message of query({
-  prompt: "Refactor the auth module",
-  options: {
-    settingSources: ["user"],  // Loads ~/.claude/settings.json (includes claudeye hooks)
-  },
-})) {
-  console.log(message);
-}
-```
-#### What happens under the hood
-The flow is identical to Claude Code:
-1. Agent SDK reads `~/.claude/settings.json` and finds claudeye hook entries
-2. Before a tool executes, the SDK invokes `claudeye --hook PreToolUse` with the tool call payload on stdin
-3. Claudeye evaluates enabled policies and returns allow/deny via stdout
-4. The SDK blocks the tool call if the policy denies it
-The hook response format (`hookSpecificOutput` with `permissionDecision` and `permissionDecisionReason`) is the same protocol used by Claude Code — claudeye doesn't need to know which client is calling it.
-#### Verification
-After installing hooks and configuring `setting_sources`, you can verify by checking the `/policies` activity dashboard. Both Claude Code and Agent SDK hook events appear in the same activity log.
-#### Common Pitfall
-If you installed hooks with `claudeye --install-hooks` but your Agent SDK app isn't blocking anything, check that you've set `setting_sources`. Without it, the SDK ignores `~/.claude/settings.json` entirely — hooks, permissions, and all other settings.
-### 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
-```
-## Enterprise
-The free tier ships 13 built-in policies with more added in every update. For teams that need deeper control, Claudeye Enterprise provides:
-- **Custom hook policies** — define organization-specific rules beyond the built-in set. Block access to internal endpoints, enforce branch naming conventions, restrict tool usage by project, or implement any policy your security team requires.
-- **Failure pattern knowledge base** — an intelligent agent that learns from your agents' past failures. It checks every session against a growing library of known failure patterns — broken tool call sequences, retry loops, permission escalations, misapplied fixes — and flags issues before they compound. The knowledge base improves continuously as your agents encounter new edge cases.
-[Contact us](https://discord.com/invite/zT92CAgvkj) to learn more.
-## 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 |
-| Hook security policies | **Yes** | No | No | No | 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
-- **Cache invalidation hook** - register a custom function via `app.cacheInvalidation()` to invalidate stale cached results based on age, score, or any custom logic
-### Utilize
-- **Hook security policies** - 13 built-in policies (free, with more every update) that block dangerous commands (`sudo`, `rm -rf /`, `.env` reads, `curl | sh`, force-pushes, commits on main, and more) in real time via Claude Code's hook system — before they execute
-- **Hook activity dashboard** - see every policy check at `/hooks`: what was allowed, what was blocked, with filters by decision, event type, and policy name
-- **Hook logging** - structured stderr output for every hook invocation (event type, policy count, decision, duration), plus opt-in file logging with automatic rotation via `CLAUDEYE_HOOK_LOG_FILE`
-- **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` (applies to dashboard server; hooks read `CLAUDEYE_LOG_LEVEL` env var) | `warn` |
-| `--disable-telemetry` | Disable anonymous usage analytics | enabled |
-| `--install-hooks [policies\|custom <path>]` | Install hooks (interactive, or: `all`, `name1 name2 ...`, or `custom <path>` to register a custom hooks JS file) | - |
-| `--remove-hooks [policies\|custom]` | Remove hooks (all, or: `name1 name2 ...` to disable specific, or `custom` to clear the custom hooks path) | - |
-| `--list-hooks` | Show hook policies in a table with enabled status, descriptions, and a separate Beta section | - |
-| `--configure-llm` | Configure LLM provider for smart policies (interactive, or pass flags below) | - |
-| `--llm-api-key <key>` | API key for the LLM provider | - |
-| `--llm-base-url <url>` | Base URL for OpenAI-compatible API | `https://api.openai.com/v1` |
-| `--llm-model <model>` | Model name | `gpt-4o-mini` |
-| `--scope <scope>` | Scope for `--install-hooks` (default: `user`) / `--remove-hooks` (default: `all`): `user`, `project`, `local`, or `all` (remove only) | - |
-| `--cwd <path>` | Working directory for `--scope project`/`local` (default: cwd). No effect with `--scope user`. | cwd |
-| `-h, --help` | Show help | - |
-## 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.cacheInvalidation(fn)`
-Register a cache invalidation hook that runs before serving any cached eval or enrichment result. If the hook returns `true`, the cached entry is discarded and the item re-runs. Only affects evals and enrichments — actions, alerts, and conditions pass through unchanged.
-```ts
-app.cacheInvalidation((ctx) => boolean | Promise<boolean>);
-```
-The `ctx` object includes `itemName`, `itemKind` (`"evals"` or `"enrichments"`), `cachedAt` (ISO timestamp), `cachedValue` (the full cached result), `projectName`, `sessionId`, `contentHash`, `itemCodeHash` (hash from the cached entry), and `currentItemCodeHash` (hash of the current function code).
-```js
-// Invalidate cache entries older than 24 hours
-app.cacheInvalidation(({ cachedAt }) => {
-  const age = Date.now() - new Date(cachedAt).getTime();
-  return age > 24 * 60 * 60 * 1000;
-});
-// Re-run a specific eval when cached score is 0
-app.cacheInvalidation((ctx) => {
-  if (ctx.itemKind === 'evals' && ctx.itemName === 'no-hallucination') {
-    return ctx.cachedValue.score === 0;
-  }
-  return false;
-});
-// Re-run when the eval/enrichment function code has changed
-app.cacheInvalidation(({ itemCodeHash, currentItemCodeHash }) => {
-  return itemCodeHash !== currentItemCodeHash;
-});
-```
----
-### `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.
-- **`options.inputs`** - optional array of `ActionInputField` definitions. When provided, the dashboard renders an inline form before running the action. Collected values are available via `context.inputs`. Actions without inputs work exactly as before.
-#### `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
-  inputs: ActionInputValues;                         // Values collected from the input form (empty object if no inputs defined)
-}
-```
-This means actions can build on prior analysis — check which evals passed, read enrichment data, and combine it with raw session data. When `options.inputs` is defined, `context.inputs` contains the user-provided values keyed by field name.
-#### `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`,
-  };
-});
-// Action with user-defined inputs: prompt for parameters before running
-app.action('custom-summary', ({ stats, evalResults, inputs }) => {
-  const maxLines = inputs.maxLines ?? 20;
-  const includeEvals = inputs.includeEvals ?? true;
-  const lines = [`Session: ${stats.turnCount} turns, ${stats.toolCallCount} tool calls`];
-  if (includeEvals) {
-    const evalNames = Object.keys(evalResults);
-    const passCount = evalNames.filter(n => evalResults[n]?.pass).length;
-    lines.push(`Evals: ${passCount}/${evalNames.length} passed`);
-  }
-  return { output: lines.slice(0, maxLines).join('\n'), status: 'success' };
-}, {
-  inputs: [
-    { name: 'maxLines', type: 'number', label: 'Max lines', default: 20 },
-    { name: 'includeEvals', type: 'boolean', label: 'Include eval results', default: true },
-    { name: 'format', type: 'select', label: 'Output format', options: [
-      { label: 'Plain text', value: 'text' },
-      { label: 'Markdown', value: 'markdown' },
-    ]},
-  ],
-});
-// 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
-- For actions with `inputs`, clicking **Run** (or **Run All**) opens an inline form to collect values before executing. When re-running a completed action, the form is pre-filled with the previous values so the user can review or modify them.
-- 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 ActionInputField {
-  name: string;
-  type: 'string' | 'number' | 'boolean' | 'select';
-  label?: string;              // Display label (defaults to name)
-  required?: boolean;
-  default?: string | number | boolean;
-  options?: Array<{ label: string; value: string }>;  // For 'select' type only
-}
-type ActionInputValues = Record<string, string | number | boolean>;
-interface RegisteredAction {
-  name: string;
-  fn: ActionFunction;
-  condition?: ConditionFunction;
-  scope: EvalScope;           // 'session' | 'subagent' | 'both'
-  subagentType?: string;
-  cache: boolean;             // default: true
-  inputs?: ActionInputField[];
-}
-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
-  inputs?: ActionInputValues; // Snapshot of input values used for this run
-}
-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 for both dashboard server and hook processes: `info`, `warn`, `error` | `warn` |
-| `CLAUDEYE_HOOK_LOG_FILE` | Enable hook file logging: `1` or `true` for default dir (`~/.claudeye/logs/`), or an absolute path for a custom directory | disabled |
-| `CLAUDEYE_DISABLE_PAGES` | Comma-separated pages to hide from nav and block direct access: `policies`, `dashboard`, `projects`. The first non-disabled page (policies → projects → dashboard) becomes the root `/` landing page. | unset |
-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.
-**Hook logging:** `CLAUDEYE_LOG_LEVEL` controls the verbosity of hook stderr output (event type, policy count, evaluation result at `info`; failures at `warn`). When `CLAUDEYE_HOOK_LOG_FILE` is additionally set, hooks write to persistent log files with automatic size-based rotation at 500 KB. See the [Hook Logging](#hook-logging) section for details and examples.
----
-## 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
-```
----
-## Telemetry
-Claudeye collects anonymous, non-PII usage analytics (e.g. `app_started`, `queue_scan_completed`) to understand feature adoption. Events are keyed by a random instance UUID — no project names, session IDs, eval names, or log content are ever sent.
-**Opt out:**
-```bash
-# CLI flag
-claudeye --disable-telemetry
-# Or environment variable
-CLAUDEYE_TELEMETRY_DISABLED=1 claudeye
-```
-When disabled, all telemetry code is zero-cost no-op (no network requests, no dynamic imports).
----
-## 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
-- [Website & Docs](https://claudeye.exosphere.host) - documentation, guides, and examples
-- [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).
+**[github.com/exospherehost/failproofai](https://github.com/exospherehost/failproofai)** | **[befailproof.ai](https://befailproof.ai)**