@neatlogs/claude-code 0.1.0 → 0.1.1

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

@@ -518,6 +518,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 +622,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 +654,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

@@ -599,6 +599,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 +703,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 +735,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

@@ -559,6 +559,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 +663,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 +695,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.1",
   "description": "Neatlogs observability for Claude Code sessions — automatic tracing of prompts, tool calls, thinking, and LLM responses via hooks",
   "license": "MIT",
   "type": "module",