llm-deep-trace 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 llm-deep-trace contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+<div align="center">
+  <img src="public/banner-v2.png" width="900" alt="llm-deep-trace" />
+  <br/><br/>
+  <p>Browse, search, and analyze every conversation your agents have ever had.<br/>All local. No accounts. No cloud.</p>
+</div>
+
+---
+
+## What it is
+
+You use coding agents. They leave behind session logs. Those logs are gold — decisions made, code written, reasoning traced, subagents spawned. But they're just JSONL files buried in `~/.claude/` or `~/.kimi/`.
+
+llm-deep-trace turns those files into a proper interface: threaded conversations, subagent trees, a conversation map, analytics, live tail, and full-text search across everything.
+
+It runs entirely on your machine. It reads your local files. That's it.
+
+---
+
+## Supported agents
+
+| Agent | Sessions | Subagents | Notes |
+|---|---|---|---|
+| **Claude Code** (Anthropic) | ✓ | ✓ | Full support incl. agent teams |
+| **Codex** | ✓ | — | |
+| **Kimi** | ✓ | — | Think-block rendering |
+| **Gemini CLI** (Google) | ✓ | — | |
+| **OpenClaw** | ✓ | ✓ | |
+| **Cursor** | ✓ | — | Partial — some metadata missing |
+| **Aider** | ✓ | — | Chat history format |
+| **Continue.dev** | ✓ | — | |
+| **GitHub Copilot** | ✓ | — | |
+| **Factory Droid** | ✓ | — | |
+| **OpenCode** | ✓ | — | |
+
+---
+
+## Quick start
+
+```bash
+git clone https://github.com/userFRM/llm-deep-trace
+cd llm-deep-trace
+npm install
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000). No config needed — it finds your sessions automatically.
+
+**Requirements:** Node.js 18+
+
+---
+
+## Features
+
+**Session browser**
+- All providers in one sidebar, grouped and searchable
+- Parent sessions show subagent count; click to expand the tree
+- Expand all / collapse all, archive sessions you don't need
+
+**Conversation view**
+- User messages as bubbles, assistant responses as cards
+- Tool call blocks collapsed by default, color-coded by type (bash, edit, web, browser, message, spawn)
+- Thinking blocks (Claude extended thinking, Kimi reasoning) as expandable cards
+- Inline image thumbnails with click-to-lightbox
+- Ctrl+F find with match counter and highlights
+- Skip preamble toggle — jump straight to the actual work
+
+**Subagent tree + conversation map**
+- React Flow visualization of the full session graph
+- Click any node to navigate to that session
+- Reset view, zoom capped at 75%, padding scales with graph size
+
+**Live tail**
+- Follow an active session in real time (3s poll)
+- Green pulsing indicator while tailing
+
+**Analytics**
+- Sessions per day, stacked by provider
+- Provider breakdown, top tools used, token totals
+- Session length distribution
+
+**Search**
+- Full-text search across all sessions and all providers
+
+---
+
+## Running remotely
+
+llm-deep-trace reads files from the machine it runs on. If your agent sessions live on a remote server (VPS, home lab, cloud box), you have a few options:
+
+**SSH tunnel** — forward the port to your local machine:
+```bash
+ssh -L 3000:localhost:3000 user@your-server
+# then open http://localhost:3000 locally
+```
+
+**Tailscale** — start the server bound to your Tailscale IP:
+```bash
+npx next start --hostname <tailscale-ip> --port 3000
+# accessible at http://<tailscale-ip>:3000 from any device on your Tailscale network
+```
+
+**VPS / cloud** — same as SSH tunnel, or bind to a private network interface. Do not expose port 3000 to the public internet — there's no auth.
+
+In all cases: the app runs on the machine where your `~/.claude/`, `~/.kimi/`, etc. directories live.
+
+---
+
+## How to ship it (for contributors)
+
+Right now: clone and run locally. That's the intended workflow for a local devtool.
+
+Planned:
+- `npm install -g llm-deep-trace` + `llm-deep-trace` CLI command
+- Homebrew tap for Mac users who prefer it
+- Docker one-liner for the server crowd
+
+PRs welcome on any of these.
+
+---
+
+## Limitations
+
+Being straight with you:
+
+- **Read-only.** Browse and analyze — you can't resume or fork sessions from here yet. jazzyalex/agent-sessions does this for Codex and Claude Code.
+- **Local files only.** Reads `~/.claude/`, `~/.kimi/`, etc. on the machine it runs on. Remote sessions not supported.
+- **Cursor / Aider / Continue** support is partial. Session formats vary and some metadata is missing.
+- **No mobile UI.** Built for desktop browsers.
+- **Requires Node.js 18+.** Not a zero-dep install.
+
+---
+
+## vs alternatives
+
+[**jazzyalex/agent-sessions**](https://github.com/jazzyalex/agent-sessions) — the closest thing. Native macOS Swift app (macOS 14+), v2.11.2, actively maintained. Supports 7 agents: Codex, Claude Code, Gemini, Copilot, Factory Droid, OpenCode, OpenClaw. Has unified search, analytics, rate limits tracker, image browser, Homebrew install, and — notably — **session resume** (reopen a session directly in your terminal). If you're on a Mac and want a native app, it's worth looking at.
+
+Where llm-deep-trace is different:
+- **Cross-platform** — runs on Mac, Linux, Windows; anything with Node.js. Not macOS-only.
+- **More agents** — 11 vs 7 (adds Kimi, Aider, Continue.dev, Cursor)
+- **Subagent tree** — React Flow visualization of parent → child agent relationships
+- **Conversation map** — full session graph, click-to-navigate
+- **Web-based** — no install, no signing, no notarization; just `npm run dev`
+
+What they have that we don't (yet):
+- Session resume (reopen past sessions in the terminal)
+- Real-time rate limits tracker
+- Native performance + Homebrew cask + auto-updates
+
+---
+
+## Tech stack
+
+Next.js 16 · React 19 · TypeScript · React Flow · Zustand · highlight.js · Marked
+
+---
+
+## License
+
+MIT

package/bin/llm-deep-trace.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+"use strict";
+const { execSync, spawn } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const pkgDir = path.join(__dirname, "..");
+const nextDir = path.join(pkgDir, ".next");
+const port = process.env.PORT || "8340";
+const host = process.env.HOST || "0.0.0.0";
+
+if (!fs.existsSync(nextDir)) {
+  console.log("llm-deep-trace: first run — building (this takes ~30s)...");
+  execSync("npx next build", { cwd: pkgDir, stdio: "inherit" });
+}
+
+const child = spawn(
+  "npx",
+  ["next", "start", "--hostname", host, "--port", port],
+  { cwd: pkgDir, stdio: "inherit" }
+);
+child.on("exit", (code) => process.exit(code ?? 0));
+process.on("SIGINT", () => child.kill("SIGINT"));
+process.on("SIGTERM", () => child.kill("SIGTERM"));

package/next.config.ts

@@ -0,0 +1,8 @@
+import type { NextConfig } from "next";
+import path from "path";
+
+const nextConfig: NextConfig = {
+  outputFileTracingRoot: path.join(__dirname),
+};
+
+export default nextConfig;

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "llm-deep-trace",
+  "version": "0.1.0",
+  "description": "The session browser for coding agents — Claude Code, Codex, Kimi, Gemini CLI, OpenClaw, Cursor, Aider, and more.",
+  "keywords": [
+    "claude-code",
+    "codex",
+    "kimi",
+    "gemini",
+    "ai-agents",
+    "llm",
+    "session-browser",
+    "devtools"
+  ],
+  "homepage": "https://github.com/userFRM/llm-deep-trace",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/userFRM/llm-deep-trace"
+  },
+  "license": "MIT",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint"
+  },
+  "dependencies": {
+    "@xyflow/react": "^12.10.1",
+    "highlight.js": "^11.11.1",
+    "marked": "^17.0.3",
+    "next": "16.1.6",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "zustand": "^5.0.11"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "16.1.6",
+    "typescript": "^5"
+  },
+  "bin": {
+    "llm-deep-trace": "bin/llm-deep-trace.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "public/",
+    "next.config.ts",
+    "tsconfig.json",
+    "postcss.config.mjs",
+    "tailwind.config.ts"
+  ]
+}

package/postcss.config.mjs

@@ -0,0 +1,5 @@
+const config = {
+  plugins: {},
+};
+
+export default config;

package/public/file.svg

@@ -0,0 +1 @@
+<svg fill="none" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg"><path d="M14.5 13.5V5.41a1 1 0 0 0-.3-.7L9.8.29A1 1 0 0 0 9.08 0H1.5v13.5A2.5 2.5 0 0 0 4 16h8a2.5 2.5 0 0 0 2.5-2.5m-1.5 0v-7H8v-5H3v12a1 1 0 0 0 1 1h8a1 1 0 0 0 1-1M9.5 5V2.12L12.38 5zM5.13 5h-.62v1.25h2.12V5zm-.62 3h7.12v1.25H4.5zm.62 3h-.62v1.25h7.12V11z" clip-rule="evenodd" fill="#666" fill-rule="evenodd"/></svg>

package/public/globe.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><g clip-path="url(#a)"><path fill-rule="evenodd" clip-rule="evenodd" d="M10.27 14.1a6.5 6.5 0 0 0 3.67-3.45q-1.24.21-2.7.34-.31 1.83-.97 3.1M8 16A8 8 0 1 0 8 0a8 8 0 0 0 0 16m.48-1.52a7 7 0 0 1-.96 0H7.5a4 4 0 0 1-.84-1.32q-.38-.89-.63-2.08a40 40 0 0 0 3.92 0q-.25 1.2-.63 2.08a4 4 0 0 1-.84 1.31zm2.94-4.76q1.66-.15 2.95-.43a7 7 0 0 0 0-2.58q-1.3-.27-2.95-.43a18 18 0 0 1 0 3.44m-1.27-3.54a17 17 0 0 1 0 3.64 39 39 0 0 1-4.3 0 17 17 0 0 1 0-3.64 39 39 0 0 1 4.3 0m1.1-1.17q1.45.13 2.69.34a6.5 6.5 0 0 0-3.67-3.44q.65 1.26.98 3.1M8.48 1.5l.01.02q.41.37.84 1.31.38.89.63 2.08a40 40 0 0 0-3.92 0q.25-1.2.63-2.08a4 4 0 0 1 .85-1.32 7 7 0 0 1 .96 0m-2.75.4a6.5 6.5 0 0 0-3.67 3.44 29 29 0 0 1 2.7-.34q.31-1.83.97-3.1M4.58 6.28q-1.66.16-2.95.43a7 7 0 0 0 0 2.58q1.3.27 2.95.43a18 18 0 0 1 0-3.44m.17 4.71q-1.45-.12-2.69-.34a6.5 6.5 0 0 0 3.67 3.44q-.65-1.27-.98-3.1" fill="#666"/></g><defs><clipPath id="a"><path fill="#fff" d="M0 0h16v16H0z"/></clipPath></defs></svg>

package/public/next.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 394 80"><path fill="#000" d="M262 0h68.5v12.7h-27.2v66.6h-13.6V12.7H262V0ZM149 0v12.7H94v20.4h44.3v12.6H94v21h55v12.6H80.5V0h68.7zm34.3 0h-17.8l63.8 79.4h17.9l-32-39.7 32-39.6h-17.9l-23 28.6-23-28.6zm18.3 56.7-9-11-27.1 33.7h17.8l18.3-22.7z"/><path fill="#000" d="M81 79.3 17 0H0v79.3h13.6V17l50.2 62.3H81Zm252.6-.4c-1 0-1.8-.4-2.5-1s-1.1-1.6-1.1-2.6.3-1.8 1-2.5 1.6-1 2.6-1 1.8.3 2.5 1a3.4 3.4 0 0 1 .6 4.3 3.7 3.7 0 0 1-3 1.8zm23.2-33.5h6v23.3c0 2.1-.4 4-1.3 5.5a9.1 9.1 0 0 1-3.8 3.5c-1.6.8-3.5 1.3-5.7 1.3-2 0-3.7-.4-5.3-1s-2.8-1.8-3.7-3.2c-.9-1.3-1.4-3-1.4-5h6c.1.8.3 1.6.7 2.2s1 1.2 1.6 1.5c.7.4 1.5.5 2.4.5 1 0 1.8-.2 2.4-.6a4 4 0 0 0 1.6-1.8c.3-.8.5-1.8.5-3V45.5zm30.9 9.1a4.4 4.4 0 0 0-2-3.3 7.5 7.5 0 0 0-4.3-1.1c-1.3 0-2.4.2-3.3.5-.9.4-1.6 1-2 1.6a3.5 3.5 0 0 0-.3 4c.3.5.7.9 1.3 1.2l1.8 1 2 .5 3.2.8c1.3.3 2.5.7 3.7 1.2a13 13 0 0 1 3.2 1.8 8.1 8.1 0 0 1 3 6.5c0 2-.5 3.7-1.5 5.1a10 10 0 0 1-4.4 3.5c-1.8.8-4.1 1.2-6.8 1.2-2.6 0-4.9-.4-6.8-1.2-2-.8-3.4-2-4.5-3.5a10 10 0 0 1-1.7-5.6h6a5 5 0 0 0 3.5 4.6c1 .4 2.2.6 3.4.6 1.3 0 2.5-.2 3.5-.6 1-.4 1.8-1 2.4-1.7a4 4 0 0 0 .8-2.4c0-.9-.2-1.6-.7-2.2a11 11 0 0 0-2.1-1.4l-3.2-1-3.8-1c-2.8-.7-5-1.7-6.6-3.2a7.2 7.2 0 0 1-2.4-5.7 8 8 0 0 1 1.7-5 10 10 0 0 1 4.3-3.5c2-.8 4-1.2 6.4-1.2 2.3 0 4.4.4 6.2 1.2 1.8.8 3.2 2 4.3 3.4 1 1.4 1.5 3 1.5 5h-5.8z"/></svg>

package/public/vercel.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1155 1000"><path d="m577.3 0 577.4 1000H0z" fill="#fff"/></svg>

package/public/window.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.5 2.5h13v10a1 1 0 0 1-1 1h-11a1 1 0 0 1-1-1zM0 1h16v11.5a2.5 2.5 0 0 1-2.5 2.5h-11A2.5 2.5 0 0 1 0 12.5zm3.75 4.5a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5M7 4.75a.75.75 0 1 1-1.5 0 .75.75 0 0 1 1.5 0m1.75.75a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5" fill="#666"/></svg>

package/src/app/api/agent-config/route.ts

@@ -0,0 +1,31 @@
+import { NextResponse, NextRequest } from "next/server";
+import fs from "fs";
+import path from "path";
+
+const HOME = process.env.HOME || "/root";
+const CONFIG_PATH = path.join(HOME, ".llm-deep-trace.json");
+
+export async function GET() {
+  try {
+    if (fs.existsSync(CONFIG_PATH)) {
+      return NextResponse.json(JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8")));
+    }
+  } catch { /* ignore */ }
+  return NextResponse.json({});
+}
+
+export async function POST(req: NextRequest) {
+  try {
+    const body = await req.json();
+    // body: { [agentId]: { binaryPath?: string; sessionsDir?: string } }
+    let existing: Record<string, unknown> = {};
+    try {
+      if (fs.existsSync(CONFIG_PATH)) existing = JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8"));
+    } catch { /* ignore */ }
+    const merged = { ...existing, ...body };
+    fs.writeFileSync(CONFIG_PATH, JSON.stringify(merged, null, 2), "utf8");
+    return NextResponse.json({ ok: true });
+  } catch (e) {
+    return NextResponse.json({ error: String(e) }, { status: 500 });
+  }
+}

package/src/app/api/all-sessions/route.ts

@@ -0,0 +1,9 @@
+import { NextResponse } from "next/server";
+import { getAllSessions } from "@/lib/sessions";
+
+export const dynamic = "force-dynamic";
+
+export async function GET() {
+  const merged = getAllSessions();
+  return NextResponse.json(merged);
+}