ccviz 0.2.0 → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dhruv Yadav
+
+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,78 @@
+# ccviz
+
+CLI tool to visualize [Claude Code](https://docs.anthropic.com/en/docs/claude-code) conversations. Opens a browser UI to explore conversation transcripts stored in `~/.claude/`, with focus on debugging MCP tool calls, identifying context bloat, and understanding token/timing patterns.
+
+![npm](https://img.shields.io/npm/v/ccviz)
+
+## Install
+
+```bash
+npm i -g ccviz
+```
+
+## Usage
+
+```bash
+# Start the browser UI
+ccviz
+
+# Custom port
+ccviz --port 8080
+
+# Don't auto-open browser
+ccviz --no-open
+
+# Dump a conversation as JSON (no server)
+ccviz --json ~/.claude/projects/-Users-you-code-myproject/session-id.jsonl
+
+# Open directly to a specific conversation
+ccviz --conversation -Users-you-code-myproject/session-id
+```
+
+## Features
+
+### Project Browser
+- Hierarchical folder tree of all Claude Code projects in `~/.claude/projects/`
+- Most recent conversations shown on the landing page
+- Search/filter conversations by title, model, or session ID
+
+### Conversation View
+
+Five tabs for analyzing a conversation:
+
+**Timeline** — Turn-by-turn view with expandable user/assistant messages. Each turn shows a context contribution bar (green→red heat scale) and expandable tool call cards with full input parameters and result previews.
+
+**Tokens** — Stacked area chart of per-turn token usage (input, output, cache creation, cache read) and cumulative context growth line chart. Interactive tooltips and per-turn breakdown table.
+
+**Tools** — Sortable table of all tool calls with duration, result size, and MCP server info. Aggregation bar charts for call count and result size by tool. Filter by tool name or MCP/native. Click any row to see full input/output.
+
+**Context** — Per-tool stacked bar chart showing exactly which tools cause context spikes at each turn. Click any bar segment to inspect the tool calls. Pie chart of context consumption by tool category — click a slice to drill down and see every call with input params and results. Optimization suggestions flag large results, repeated calls, and oversized reads.
+
+**Subagents** — List of spawned subagents with token usage comparison bars. Click to expand and see the subagent's own timeline.
+
+## Data Source
+
+Reads conversation transcripts from `~/.claude/projects/`. Each project directory contains `.jsonl` files (one per conversation) with the full message history, tool calls, token usage, and subagent transcripts.
+
+## Tech Stack
+
+- **CLI**: Node.js, Commander, `open`
+- **Server**: Express 5
+- **Parser**: Streaming JSONL parser (handles 25MB+ conversations)
+- **UI**: React 19, Vite, Tailwind CSS v4, [visx](https://airbnb.io/visx/) for visualizations
+- **Build**: tsup (server), Vite (UI)
+
+## Development
+
+```bash
+git clone https://github.com/dhruvyad/ccviz.git
+cd ccviz
+npm install
+npm run dev    # Starts Express + Vite dev server with HMR
+npm run build  # Production build
+npm start      # Run production build
+```
+
+## License
+
+[MIT](LICENSE)

package/dist/{chunk-AQM3FQFJ.js → chunk-37WFE64V.js}

@@ -88,6 +88,63 @@ import fs2 from "fs/promises";
 import path2 from "path";
 import { createReadStream } from "fs";
 import readline from "readline";
+function createRecentRouter(claudeDir) {
+  const router = Router2();
+  router.get("/", async (req, res) => {
+    try {
+      const limit = Math.min(parseInt(req.query.limit) || 20, 50);
+      const projectsDir = path2.join(claudeDir, "projects");
+      const projectFolders = await fs2.readdir(projectsDir, {
+        withFileTypes: true
+      });
+      const all = [];
+      for (const folder of projectFolders) {
+        if (!folder.isDirectory()) continue;
+        const projectDir = path2.join(projectsDir, folder.name);
+        let files;
+        try {
+          files = await fs2.readdir(projectDir);
+        } catch {
+          continue;
+        }
+        const jsonlFiles = files.filter((f) => f.endsWith(".jsonl"));
+        for (const file of jsonlFiles) {
+          const filePath = path2.join(projectDir, file);
+          try {
+            const stat = await fs2.stat(filePath);
+            all.push({
+              sessionId: file.replace(".jsonl", ""),
+              projectEncoded: folder.name,
+              filePath,
+              sizeBytes: stat.size,
+              lastModified: stat.mtime.toISOString(),
+              mtimeMs: stat.mtimeMs
+            });
+          } catch {
+          }
+        }
+      }
+      all.sort((a, b) => b.mtimeMs - a.mtimeMs);
+      const top = all.slice(0, limit);
+      const results = await Promise.all(
+        top.map(async (entry) => {
+          const summary = await quickScan(entry.filePath);
+          return {
+            sessionId: entry.sessionId,
+            projectEncoded: entry.projectEncoded,
+            sizeBytes: entry.sizeBytes,
+            lastModified: entry.lastModified,
+            ...summary
+          };
+        })
+      );
+      res.json(results);
+    } catch {
+      res.status(500).json({ error: "Failed to list recent conversations" });
+    }
+  });
+  return router;
+}
 function createConversationsRouter(claudeDir) {
   const router = Router2();
   router.get("/:encodedPath/conversations", async (req, res) => {
@@ -528,10 +585,12 @@ function createServer({ claudeDir, isDev }) {
   app.use("/api/projects", createProjectsRouter(claudeDir));
   app.use("/api/projects", createConversationsRouter(claudeDir));
   app.use("/api/conversations", createConversationRouter(claudeDir));
+  app.use("/api/recent", createRecentRouter(claudeDir));
   if (!isDev) {
     const uiDir = path6.join(__dirname, "ui");
     app.use(express.static(uiDir));
-    app.get("/{*splat}", (_req, res) => {
+    app.get("/{*splat}", (req, res, next) => {
+      if (req.path.startsWith("/api/")) return next();
       res.sendFile(path6.join(uiDir, "index.html"));
     });
   }

package/dist/cli.js

@@ -2,7 +2,7 @@
 import {
   createServer,
   parseConversation
-} from "./chunk-AQM3FQFJ.js";
+} from "./chunk-37WFE64V.js";
 
 // src/cli.ts
 import { Command } from "commander";

package/dist/server/index.js

@@ -1,6 +1,6 @@
 import {
   createServer
-} from "../chunk-AQM3FQFJ.js";
+} from "../chunk-37WFE64V.js";
 export {
   createServer
 };