@faithfulalabi/agent-lens 0.4.0 → 0.4.1

package/README.md

@@ -1,11 +1,31 @@
 # agent-lens
 
-A local-first tracing platform for coding agents. Run one command, open a local UI, and read back
-everything a Claude Code session did — prompts, tool calls, sub-agents, inputs and outputs — so you
-can see where a session went and steer the next one better.
+[![npm version](https://img.shields.io/npm/v/%40faithfulalabi%2Fagent-lens?label=npm)](https://www.npmjs.com/package/@faithfulalabi/agent-lens)
+[![node-current](https://img.shields.io/node/v/%40faithfulalabi%2Fagent-lens)](https://nodejs.org)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![CI](https://github.com/faithfulalabi/agent-lens/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/faithfulalabi/agent-lens/actions/workflows/ci.yml)
 
-It reads the transcripts Claude Code already writes to disk. There is nothing to add to your
-harness and nothing to configure.
+**Read back everything a Claude Code session did — prompts, reasoning, tool calls, sub-agents,
+inputs and outputs — in a local UI, long after the session ended.**
+
+Claude Code expires its own transcripts. agent-lens keeps a verbatim copy of every session you have
+ever run, on your machine, searchable after the source is gone. It reads the files the harness
+already writes to disk: no account, no API key, and nothing added to your agent or your
+application.
+
+![The agent-lens session list, showing every archived session with its model, turn count, tokens and estimated cost](https://raw.githubusercontent.com/faithfulalabi/agent-lens/main/docs/images/01-sessions.png)
+
+## Questions it answers
+
+- **What did I actually ask for three weeks ago?** The archive still holds the session even once
+  Claude Code has expired its copy.
+- **Where did that session go wrong?** Read the session back in order: every tool call, its real
+  input, its real output, where it happened.
+- **What did the sub-agent do?** Open the `Agent` call and read the sub-agent's own transcript —
+  its reasoning, its tools, and what it reported back.
+- **Which session touched this file?** Full-text search across prompts, tool payloads and output
+  too large to sit inline.
+- **What is it costing?** Tokens and estimated cost, rolled up per session, per turn and per call.
 
 ## Quickstart
 
@@ -18,7 +38,48 @@ are there; new ones show up as they happen.
 
 Requires Node.js `>=24`.
 
-## The durability contract — read this before you delete anything
+## A short tour
+
+**Every call, with its real payload.** The session reads back as a conversation, with the tool calls
+tucked into activity groups between the messages. Open one and it shows what actually went in and
+what actually came back.
+
+![A session read as a conversation: a prompt, Claude's reply, and an open activity group showing a Read call with its input and its output](https://raw.githubusercontent.com/faithfulalabi/agent-lens/main/docs/images/thread-tool-call.png)
+
+**Sub-agents keep their own transcript.** An `Agent` call links straight to the session the
+sub-agent ran, with its own messages, its own tool calls and its own cost — and a way back to the
+parent.
+
+![A sub-agent's own session: a back link to the parent session, the sub-agent's opening message, its Glob and Grep calls with payloads, and the findings it reported](https://raw.githubusercontent.com/faithfulalabi/agent-lens/main/docs/images/thread-subagent.png)
+
+**Search reaches the payloads, not just the prompts.** Hits land on the event that carried them, and
+the match is highlighted in place. The screen below is search scoped to one open session; search
+across the whole archive is reached from the session list.
+
+![In-session search results, each hit showing the matched run highlighted inside a prompt or tool payload](https://raw.githubusercontent.com/faithfulalabi/agent-lens/main/docs/images/10-search.png)
+
+## How it compares
+
+LangSmith, Langfuse and Arize Phoenix are tracing platforms for applications you are building, and
+all three now also ship a Claude Code plugin. Each posture below was read from that tool's own
+current documentation.
+
+| Tool              | What it needs from you                                                                                                                                                           | Where the data lives                                                            | What it reads                                                                                                                         |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| **LangSmith**     | An account and an API key. Tracing comes from its SDK in your application, from OpenTelemetry, or from its Claude Code plugin.                                                   | LangChain's cloud by default. Self-hosted and BYOC are Enterprise-plan options. | Spans your application emits, or the turns its Claude Code plugin reports while a session runs.                                       |
+| **Langfuse**      | An account — cloud or self-hosted — and a key pair. Tracing comes from its SDK, from OpenTelemetry, or from its Claude Code plugin.                                              | Langfuse Cloud by default. Self-hosting is documented and open source.          | Spans your application emits. Its Claude Code plugin reads each turn's transcript as that turn completes.                             |
+| **Arize Phoenix** | A Phoenix instance to send to — the documented default is a local one, which needs no account. Tracing comes from OpenInference / OpenTelemetry, or from its Claude Code plugin. | Your own machine or infrastructure by default.                                  | OpenTelemetry spans your application emits, or the turns its Claude Code plugin reports while a session runs.                         |
+| **agent-lens**    | One command. No account, no key, nothing added to your application or your agent.                                                                                                | Your machine only, under `~/.agent-lens`.                                       | The transcript files Claude Code has already written to disk — including sessions that ran before agent-lens was ever on the machine. |
+
+The last column is the difference. The other three observe a session as it happens, so the record
+starts when you set them up. agent-lens reads what the harness already wrote, so the first run shows
+you work you did before you had it — and keeps that work after Claude Code expires its own copy.
+
+## What you keep — the durability contract
+
+The reason to run this is the archive. Claude Code expires `~/.claude/projects` on its own
+schedule; the archive is the copy that outlives it, and past that cliff it is the only copy there
+is. Which makes the next part worth reading before you delete anything.
 
 Three directories, three completely different promises.
 
@@ -128,8 +189,9 @@ people: on a shared machine, the agent being traced can read the trace API too.
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, the render loop against a real corpus, and the
-one-door rule every change to transcript reading has to satisfy.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, the render loop against a real corpus, the
+command that regenerates the screenshots on this page, and the one-door rule every change to
+transcript reading has to satisfy.
 
 ## License
 

package/bin/agent-lens.js

@@ -32,6 +32,8 @@ if (!Number.isInteger(major) || major < MIN_NODE_MAJOR) {
   process.exitCode = 1;
 } else {
   // Dynamic, so the guard above runs first — a static import would hoist past it.
+  // The generated archive wrapper guards an install on this specifier — keep
+  // BUILT_CLI_ENTRY in step with it.
   const { main } = await import('../dist/src/cli/index.js');
   // Setting the code and returning, rather than terminating the process here:
   // the abrupt form truncates piped stdout mid-write. Exit codes 0/1/3 from

package/dist/src/cli/commands/schedule.js

@@ -9,6 +9,7 @@ export const SCHEDULE_LABEL = 'com.agent-lens.archive';
 export const LEGACY_LABEL = 'com.faithful.agent-lens.archive';
 const START_INTERVAL_SECONDS = 900;
 export const CRON_STAMP_FORMAT = '+%Y-%m-%dT%H:%M:%S%z';
+export const BUILT_CLI_ENTRY = 'dist/src/cli/index.js';
 export const WAKE_TIME_CAVEAT = 'a wall-clock schedule does not fire while the machine is asleep — treat the interval as a bound on wake time, not on elapsed time';
 export const LINGER_CAVEAT = 'a systemd user timer does not run while you are logged out unless lingering is on for your user';
 export const SYSTEMD_UNIT_BASE = 'agent-lens-archive';
@@ -93,6 +94,9 @@ export function buildWrapperScript(opts) {
     const run = kind === 'source'
         ? '"$NODE" --import tsx "$ROOT/src/cli/index.ts" archive --dataDir "$DATA_DIR"'
         : '"$NODE" "$ROOT/bin/agent-lens.js" archive --dataDir "$DATA_DIR"';
+    const requirement = kind === 'source'
+        ? '[ -d "$ROOT/node_modules" ] || { say "FATAL node_modules missing — run npm install in $ROOT"; exit 1; }'
+        : `[ -f "$ROOT/${BUILT_CLI_ENTRY}" ] || { say "FATAL built CLI missing: $ROOT/${BUILT_CLI_ENTRY} — reinstall @faithfulalabi/agent-lens"; exit 1; }`;
     return `#!/bin/sh
 # agent-lens archive — unattended pass, invoked by the launchd agent
 # ${SCHEDULE_LABEL} every ${START_INTERVAL_SECONDS / 60} minutes.
@@ -130,7 +134,7 @@ say() { printf '%s %s\\n' "$(stamp)" "$1" >>"$LOG"; }
 [ -d "$ROOT" ]              || { say "FATAL package root missing: $ROOT"; exit 1; }
 [ -x "$NODE" ]              || { say "FATAL node missing: $NODE"; exit 1; }
 [ -e "${entry}" ] || { say "FATAL entry missing: ${entry}"; exit 1; }
-[ -d "$ROOT/node_modules" ] || { say "FATAL node_modules missing — run npm install in $ROOT"; exit 1; }
+${requirement}
 
 cd "$ROOT" || { say "FATAL cannot cd to $ROOT"; exit 1; }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faithfulalabi/agent-lens",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Local-first agentic tracing platform: inspect everything your agent did in a session.",
   "type": "module",
   "license": "MIT",
@@ -38,6 +38,7 @@
     "dev": "tsx src/dev/server.ts",
     "dev:ui": "npm --prefix ui run dev",
     "render-gate": "tsx src/render-gate/index.ts",
+    "demo:capture": "node --import tsx scripts/capture-screenshots.mjs",
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.node.json --noEmit && npm --prefix ui run typecheck",
     "build": "rm -rf dist && tsc -p tsconfig.build.json && npm --prefix ui run build",