@neatlogs/claude-code 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,58 @@
+# @neatlogs/claude-code
+
+Automatic observability for Claude Code sessions. Captures prompts, tool calls, thinking, and LLM responses as traces in Neatlogs via Claude Code hooks.
+
+## Installation
+
+```bash
+npm install -g @neatlogs/claude-code
+```
+
+## Setup
+
+```bash
+neatlogs-claude-code setup --global --api-key YOUR_PROJECT_KEY
+```
+
+This does two things:
+1. Saves your API key to `~/.config/neatlogs/config.json`
+2. Registers hooks in `~/.claude/settings.json` for all Claude Code lifecycle events
+
+That's it. Restart Claude Code and all sessions are automatically traced.
+
+## What gets captured
+
+Each Claude Code session produces a trace with:
+
+- **Workflow span** — root span for the session
+- **Turn spans** — one per user prompt (named with truncated prompt text)
+- **Tool call spans** — Read, Edit, Bash, etc. with inputs, outputs, and duration
+- **LLM spans** — model responses with token counts and thinking content
+- **Subagent spans** — spawned agent work
+
+## Commands
+
+```bash
+neatlogs-claude-code setup [--global|--project] [--api-key KEY]  # Register hooks
+neatlogs-claude-code hook                                         # Process hook event (called by Claude Code)
+neatlogs-claude-code --version                                    # Print version
+```
+
+## Troubleshooting
+
+**Hooks not firing:** Restart Claude Code after running setup.
+
+**Permission error on install:** If you get EACCES, either use `nvm` (which handles permissions automatically) or configure npm to use a user-writable directory:
+```bash
+npm config set prefix ~/.npm-global
+echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+## Uninstall
+
+```bash
+npm uninstall -g @neatlogs/claude-code
+```
+
+Hooks remain in `~/.claude/settings.json` but will be no-ops since the binary is gone. To clean them up, remove the `neatlogs-claude-code` entries from that file.

package/dist/cli.js

@@ -7,6 +7,7 @@ import {
 import { appendFileSync as appendFileSync2 } from "fs";
 
 // src/trace-shipper.ts
+import { createHash } from "crypto";
 import protobuf from "protobufjs";
 
 // src/package-info.ts
@@ -113,6 +114,10 @@ function generateTraceId() {
 function generateSpanId() {
   return randomBytes(8);
 }
+function deterministicId(input, length) {
+  const hash = createHash("sha256").update(input).digest();
+  return new Uint8Array(hash.buffer, hash.byteOffset, length);
+}
 function bytesToHex(bytes) {
   return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
@@ -500,8 +505,8 @@ function ensureSessionTrace(payload, config, shipper) {
   const model = readState(`model_${payload.session_id}`) || void 0;
   const workflowName = deriveWorkflowName(payload);
   writeState(`workflow_${payload.session_id}`, workflowName);
-  const traceId = generateTraceId();
-  const spanId = generateSpanId();
+  const traceId = deterministicId(payload.session_id, 16);
+  const spanId = deterministicId(payload.session_id + ":root", 8);
   const now = nowNanoString();
   const rootSpan = {
     traceId,
@@ -518,6 +523,7 @@ function ensureSessionTrace(payload, config, shipper) {
       attrString("neatlogs.user_id", config.userId),
       attrString("neatlogs.session_id", payload.session_id),
       attrString("neatlogs.workflow_name", workflowName),
+      attrString("neatlogs.llm.effort_level", payload.effort?.level),
       attrString("neatlogs.input.value", payload.prompt),
       attrString("cwd", payload.cwd),
       { key: "neatlogs.sdk.name", value: { stringValue: PACKAGE_NAME } },
@@ -621,6 +627,7 @@ function handleUserPromptSubmit(payload, config, shipper) {
     endTimeUnixNano: now,
     attributes: [
       { key: "neatlogs.span.kind", value: { stringValue: "CHAIN" } },
+      attrString("neatlogs.llm.effort_level", payload.effort?.level),
       attrString("neatlogs.input.value", payload.prompt),
       attrString("cwd", payload.cwd)
     ].filter((a) => a !== void 0)
@@ -652,13 +659,11 @@ function handlePostToolUse(payload, config, shipper, error) {
     error ? { code: SpanStatusCode.ERROR, message: error } : void 0
   );
   shipper.enqueue(span);
-  if (payload.permission_mode === "plan") {
-    const sessionCtx = getSessionTrace(payload.session_id);
-    if (sessionCtx) {
-      const markerNow = nowNanoString();
-      const marker = createSpan("neatlogs.trace.complete", sessionCtx, markerNow, markerNow, []);
-      shipper.enqueue(marker);
-    }
+  const sessionCtx = getSessionTrace(payload.session_id);
+  if (sessionCtx) {
+    const markerNow = nowNanoString();
+    const marker = createSpan("neatlogs.trace.complete", sessionCtx, markerNow, markerNow, []);
+    shipper.enqueue(marker);
   }
 }
 function handleSubagentStart(payload, config, shipper) {

package/dist/index.cjs

@@ -88,6 +88,7 @@ function updateConfig(patch) {
 }
 
 // src/trace-shipper.ts
+var import_crypto = require("crypto");
 var import_protobufjs = __toESM(require("protobufjs"), 1);
 
 // src/package-info.ts
@@ -194,6 +195,10 @@ function generateTraceId() {
 function generateSpanId() {
   return randomBytes(8);
 }
+function deterministicId(input, length) {
+  const hash = (0, import_crypto.createHash)("sha256").update(input).digest();
+  return new Uint8Array(hash.buffer, hash.byteOffset, length);
+}
 function bytesToHex(bytes) {
   return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
@@ -581,8 +586,8 @@ function ensureSessionTrace(payload, config, shipper) {
   const model = readState(`model_${payload.session_id}`) || void 0;
   const workflowName = deriveWorkflowName(payload);
   writeState(`workflow_${payload.session_id}`, workflowName);
-  const traceId = generateTraceId();
-  const spanId = generateSpanId();
+  const traceId = deterministicId(payload.session_id, 16);
+  const spanId = deterministicId(payload.session_id + ":root", 8);
   const now = nowNanoString();
   const rootSpan = {
     traceId,
@@ -599,6 +604,7 @@ function ensureSessionTrace(payload, config, shipper) {
       attrString("neatlogs.user_id", config.userId),
       attrString("neatlogs.session_id", payload.session_id),
       attrString("neatlogs.workflow_name", workflowName),
+      attrString("neatlogs.llm.effort_level", payload.effort?.level),
       attrString("neatlogs.input.value", payload.prompt),
       attrString("cwd", payload.cwd),
       { key: "neatlogs.sdk.name", value: { stringValue: PACKAGE_NAME } },
@@ -702,6 +708,7 @@ function handleUserPromptSubmit(payload, config, shipper) {
     endTimeUnixNano: now,
     attributes: [
       { key: "neatlogs.span.kind", value: { stringValue: "CHAIN" } },
+      attrString("neatlogs.llm.effort_level", payload.effort?.level),
       attrString("neatlogs.input.value", payload.prompt),
       attrString("cwd", payload.cwd)
     ].filter((a) => a !== void 0)
@@ -733,13 +740,11 @@ function handlePostToolUse(payload, config, shipper, error) {
     error ? { code: SpanStatusCode.ERROR, message: error } : void 0
   );
   shipper.enqueue(span);
-  if (payload.permission_mode === "plan") {
-    const sessionCtx = getSessionTrace(payload.session_id);
-    if (sessionCtx) {
-      const markerNow = nowNanoString();
-      const marker = createSpan("neatlogs.trace.complete", sessionCtx, markerNow, markerNow, []);
-      shipper.enqueue(marker);
-    }
+  const sessionCtx = getSessionTrace(payload.session_id);
+  if (sessionCtx) {
+    const markerNow = nowNanoString();
+    const marker = createSpan("neatlogs.trace.complete", sessionCtx, markerNow, markerNow, []);
+    shipper.enqueue(marker);
   }
 }
 function handleSubagentStart(payload, config, shipper) {

package/dist/index.d.cts

@@ -31,6 +31,9 @@ interface HookPayload {
     tool_response?: unknown;
     duration_ms?: number;
     tool_use_id?: string;
+    effort?: {
+        level?: string;
+    };
     error?: string;
     is_interrupt?: boolean;
     last_assistant_message?: string;

package/dist/index.d.ts

@@ -31,6 +31,9 @@ interface HookPayload {
     tool_response?: unknown;
     duration_ms?: number;
     tool_use_id?: string;
+    effort?: {
+        level?: string;
+    };
     error?: string;
     is_interrupt?: boolean;
     last_assistant_message?: string;

package/dist/index.js

@@ -48,6 +48,7 @@ function updateConfig(patch) {
 }
 
 // src/trace-shipper.ts
+import { createHash } from "crypto";
 import protobuf from "protobufjs";
 
 // src/package-info.ts
@@ -154,6 +155,10 @@ function generateTraceId() {
 function generateSpanId() {
   return randomBytes(8);
 }
+function deterministicId(input, length) {
+  const hash = createHash("sha256").update(input).digest();
+  return new Uint8Array(hash.buffer, hash.byteOffset, length);
+}
 function bytesToHex(bytes) {
   return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
@@ -541,8 +546,8 @@ function ensureSessionTrace(payload, config, shipper) {
   const model = readState(`model_${payload.session_id}`) || void 0;
   const workflowName = deriveWorkflowName(payload);
   writeState(`workflow_${payload.session_id}`, workflowName);
-  const traceId = generateTraceId();
-  const spanId = generateSpanId();
+  const traceId = deterministicId(payload.session_id, 16);
+  const spanId = deterministicId(payload.session_id + ":root", 8);
   const now = nowNanoString();
   const rootSpan = {
     traceId,
@@ -559,6 +564,7 @@ function ensureSessionTrace(payload, config, shipper) {
       attrString("neatlogs.user_id", config.userId),
       attrString("neatlogs.session_id", payload.session_id),
       attrString("neatlogs.workflow_name", workflowName),
+      attrString("neatlogs.llm.effort_level", payload.effort?.level),
       attrString("neatlogs.input.value", payload.prompt),
       attrString("cwd", payload.cwd),
       { key: "neatlogs.sdk.name", value: { stringValue: PACKAGE_NAME } },
@@ -662,6 +668,7 @@ function handleUserPromptSubmit(payload, config, shipper) {
     endTimeUnixNano: now,
     attributes: [
       { key: "neatlogs.span.kind", value: { stringValue: "CHAIN" } },
+      attrString("neatlogs.llm.effort_level", payload.effort?.level),
       attrString("neatlogs.input.value", payload.prompt),
       attrString("cwd", payload.cwd)
     ].filter((a) => a !== void 0)
@@ -693,13 +700,11 @@ function handlePostToolUse(payload, config, shipper, error) {
     error ? { code: SpanStatusCode.ERROR, message: error } : void 0
   );
   shipper.enqueue(span);
-  if (payload.permission_mode === "plan") {
-    const sessionCtx = getSessionTrace(payload.session_id);
-    if (sessionCtx) {
-      const markerNow = nowNanoString();
-      const marker = createSpan("neatlogs.trace.complete", sessionCtx, markerNow, markerNow, []);
-      shipper.enqueue(marker);
-    }
+  const sessionCtx = getSessionTrace(payload.session_id);
+  if (sessionCtx) {
+    const markerNow = nowNanoString();
+    const marker = createSpan("neatlogs.trace.complete", sessionCtx, markerNow, markerNow, []);
+    shipper.enqueue(marker);
   }
 }
 function handleSubagentStart(payload, config, shipper) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neatlogs/claude-code",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Neatlogs observability for Claude Code sessions — automatic tracing of prompts, tool calls, thinking, and LLM responses via hooks",
   "license": "MIT",
   "type": "module",