llm-trace 0.1.0 → 0.1.1

package/README.md

@@ -1,74 +1,76 @@
 # llm-trace
 
-When an LLM debugs your code, it can't see what happens at runtime. It reads your source, guesses what went wrong, and asks you to paste error messages. You end up as a middleman — running code, copying output, adding print statements.
+LLMs can read your code but they can't run it in their head. When something breaks, they end up asking you to paste errors and add `console.log` statements one at a time while they guess at what's going on.
 
-llm-trace lets LLMs see runtime behavior directly. They instrument your code with traces, run it, inspect what happened, and fix the bug — without asking you to copy-paste anything.
+llm-trace fixes this. It gives LLMs a way to instrument your code with structured traces, see actual runtime values, and figure out what went wrong without the back-and-forth.
 
-## Setup
+## Try It
 
 ```bash
 npm install llm-trace
 ```
 
-Add the [debugging skill](skills/debugging-with-llm-trace/SKILL.md) to your LLM tool (Claude Code, Codex, etc.) so it knows how to use llm-trace.
+Add the [debugging skill](skills/debugging-with-llm-trace/SKILL.md) to Claude Code (or any LLM coding tool) and ask it to debug something. That's it — the skill teaches it the workflow.
 
-## How It Works
+### What happens next
 
-1. LLM runs `npx llm-trace start` to begin a debugging session
-2. LLM instruments your code with `trace()`, `span()`, and `checkpoint()` calls
-3. You run your code (or LLM runs it)
-4. LLM queries traces with `npx llm-trace list`, `show`, `tail`
-5. LLM reads structured runtime data, identifies root cause, fixes the bug
-6. LLM runs `npx llm-trace stop` to clean up
+You tell the LLM "this endpoint returns 500 sometimes" and it:
 
-Traces are ephemeral — they exist only during the debugging session and are deleted when it ends.
+1. Runs `npx llm-trace start`
+2. Wraps the endpoint in `trace()` with `span()` and `checkpoint()` calls
+3. Triggers the bug
+4. Reads the trace — sees actual values at each step, which span failed, the error
+5. Fixes the root cause based on what it saw
+6. Removes instrumentation, runs `npx llm-trace stop`
 
-## API
-
-### `trace(name, fn)` — wrap a complete operation
+## Three Primitives
 
 ```typescript
 import { trace } from "llm-trace";
 
-const result = await trace("handle-request", async (handle) => {
-  // handle.span() and handle.checkpoint() available here
-  return processRequest(req);
-});
-```
+await trace("checkout", async (handle) => {
 
-### `handle.span(name, fn)` — time a step within a trace
+  // span — time a step, nest arbitrarily
+  await handle.span("load-cart", async (h) => {
+    const cart = await db.getCart(userId);
 
-```typescript
-await handle.span("call-llm", async (h) => {
-  const response = await llm.chat(prompt);
-  h.checkpoint("response", response);
-  return response;
+    // checkpoint — snapshot runtime values
+    h.checkpoint("cart", cart);
+
+    return cart;
+  });
 });
 ```
 
-### `handle.checkpoint(name, data?)` — snapshot state at a point in time
+**`trace(name, fn)`** — wraps a complete operation. Captures start, end, duration, errors.
 
-```typescript
-handle.checkpoint("parsed-input", { tokens: 142 });
-```
+**`handle.span(name, fn)`** — a timed step within a trace. Nests to any depth.
 
-Spans nest arbitrarily. Errors are captured automatically. Checkpoint data is truncated at 64KB.
+**`handle.checkpoint(name, data?)`** — snapshots a value (truncated at 64KB).
+
+Errors are captured automatically — if anything throws, the trace records the error and stack.
 
 ## CLI
 
-| Command | Description |
-|---------|-------------|
-| `llm-trace start` | Begin session, start trace server |
-| `llm-trace stop` | End session, delete all traces |
-| `llm-trace status` | Check if a session is active |
-| `llm-trace list` | List traces (`--errors`, `--name <glob>`, `--last <n>`, `--human`) |
-| `llm-trace show <id>` | Show trace tree (`--human` for readable output) |
-| `llm-trace tail` | Stream new traces (`--errors`, `--name <glob>`) |
+```bash
+llm-trace start             # begin session
+llm-trace list              # all traces (JSON by default)
+llm-trace list --errors     # just failures
+llm-trace show <id>         # full trace tree
+llm-trace tail              # watch live
+llm-trace stop              # end session, delete traces
+```
+
+Output is JSON by default (for LLM consumption). Add `--human` for readable output.
+
+## How It Fits Together
+
+The LLM writes `trace()` / `span()` / `checkpoint()` calls into your code. When the code runs, events stream over HTTP to a local server that writes `.ndjson` files. The LLM reads those files via the CLI. After debugging, everything is cleaned up — traces are ephemeral.
 
-Default output is JSON (for LLM consumption). `--human` for readable output.
+No dependencies. No config. Nothing persisted after `stop`.
 
 ## Configuration
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `TRACE_AI_PORT` | `13579` | HTTP server port |
+| `LLM_TRACE_PORT` | `13579` | HTTP server port |

package/dist/cli.cjs

@@ -168,7 +168,7 @@ async function getFormattedList(logDir, options) {
 	}), options.human === true);
 }
 async function runList(options) {
-	const logDir = (0, node_path.join)(process.cwd(), ".trace-ai-logs");
+	const logDir = (0, node_path.join)(process.cwd(), ".llm-trace-logs");
 	if (!(0, node_fs.existsSync)(logDir)) {
 		console.log("No active session.");
 		return;
@@ -179,7 +179,7 @@ async function runList(options) {
 //#endregion
 //#region src/cli/commands/show.ts
 async function runShow(id, options) {
-	const logDir = (0, node_path.join)(process.cwd(), ".trace-ai-logs");
+	const logDir = (0, node_path.join)(process.cwd(), ".llm-trace-logs");
 	if (!(0, node_fs.existsSync)(logDir)) {
 		console.log("No active session.");
 		return;
@@ -191,7 +191,7 @@ async function runShow(id, options) {
 //#endregion
 //#region src/cli/commands/start.ts
 async function startSession(projectDir, options = {}) {
-	const logDir = (0, node_path.join)(projectDir, ".trace-ai-logs");
+	const logDir = (0, node_path.join)(projectDir, ".llm-trace-logs");
 	if ((0, node_fs.existsSync)(logDir)) return {
 		created: false,
 		reason: "already_active"
@@ -199,17 +199,17 @@ async function startSession(projectDir, options = {}) {
 	(0, node_fs.mkdirSync)(logDir, { recursive: true });
 	const gitignorePath = (0, node_path.join)(projectDir, ".gitignore");
 	if ((0, node_fs.existsSync)(gitignorePath)) {
-		if (!(0, node_fs.readFileSync)(gitignorePath, "utf-8").includes(".trace-ai-logs/")) (0, node_fs.appendFileSync)(gitignorePath, "\n.trace-ai-logs/\n");
-	} else (0, node_fs.writeFileSync)(gitignorePath, ".trace-ai-logs/\n");
+		if (!(0, node_fs.readFileSync)(gitignorePath, "utf-8").includes(".llm-trace-logs/")) (0, node_fs.appendFileSync)(gitignorePath, "\n.llm-trace-logs/\n");
+	} else (0, node_fs.writeFileSync)(gitignorePath, ".llm-trace-logs/\n");
 	if (!options.skipServer) {
-		const port = parseInt(process.env.TRACE_AI_PORT || "", 10) || 13579;
+		const port = parseInt(process.env.LLM_TRACE_PORT || "", 10) || 13579;
 		const script = (0, node_path.join)((0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href), "..", "standalone.js");
 		const child = (0, node_child_process.spawn)(process.execPath, [script], {
 			detached: true,
 			stdio: "ignore",
 			env: {
 				...process.env,
-				TRACE_AI_PORT: String(port),
+				LLM_TRACE_PORT: String(port),
 				TRACE_AI_DIR: logDir
 			}
 		});
@@ -234,7 +234,7 @@ async function runStart() {
 //#endregion
 //#region src/cli/commands/status.ts
 function getSessionStatus(projectDir) {
-	const logDir = (0, node_path.join)(projectDir, ".trace-ai-logs");
+	const logDir = (0, node_path.join)(projectDir, ".llm-trace-logs");
 	if (!(0, node_fs.existsSync)(logDir)) return { active: false };
 	const files = (0, node_fs.readdirSync)(logDir).filter((f) => f.endsWith(".ndjson"));
 	let errorCount = 0;
@@ -264,7 +264,7 @@ async function runStatus() {
 //#endregion
 //#region src/cli/commands/stop.ts
 async function stopSession(projectDir) {
-	const logDir = (0, node_path.join)(projectDir, ".trace-ai-logs");
+	const logDir = (0, node_path.join)(projectDir, ".llm-trace-logs");
 	if (!(0, node_fs.existsSync)(logDir)) return {
 		stopped: false,
 		reason: "no_session"
@@ -294,7 +294,7 @@ function summarizeFile(filePath) {
 	}
 }
 async function runTail(options) {
-	const logDir = (0, node_path.join)(process.cwd(), ".trace-ai-logs");
+	const logDir = (0, node_path.join)(process.cwd(), ".llm-trace-logs");
 	if (!(0, node_fs.existsSync)(logDir)) {
 		console.log("No active session.");
 		return;
@@ -343,15 +343,15 @@ function parseCliArgs(argv) {
 
 //#endregion
 //#region src/cli/index.ts
-const HELP = `trace-ai — Structured execution traces for LLM debugging
+const HELP = `llm-trace — Structured execution traces for LLM debugging
 
 Usage:
-  trace-ai start              Begin debugging session
-  trace-ai stop               End session, delete traces
-  trace-ai status             Show session info
-  trace-ai list [--errors] [--name <pattern>] [--last <n>] [--human]
-  trace-ai show <id> [--human]
-  trace-ai tail [--errors] [--name <pattern>]
+  llm-trace start              Begin debugging session
+  llm-trace stop               End session, delete traces
+  llm-trace status             Show session info
+  llm-trace list [--errors] [--name <pattern>] [--last <n>] [--human]
+  llm-trace show <id> [--human]
+  llm-trace tail [--errors] [--name <pattern>]
 `;
 async function main() {
 	const { command, id, options } = parseCliArgs(process.argv.slice(2));
@@ -362,7 +362,7 @@ async function main() {
 		case "list": return runList(options);
 		case "show":
 			if (!id) {
-				console.error("Usage: trace-ai show <id>");
+				console.error("Usage: llm-trace show <id>");
 				process.exit(1);
 			}
 			return runShow(id, options);

package/dist/cli.js

@@ -168,7 +168,7 @@ async function getFormattedList(logDir, options) {
 	}), options.human === true);
 }
 async function runList(options) {
-	const logDir = join(process.cwd(), ".trace-ai-logs");
+	const logDir = join(process.cwd(), ".llm-trace-logs");
 	if (!existsSync(logDir)) {
 		console.log("No active session.");
 		return;
@@ -179,7 +179,7 @@ async function runList(options) {
 //#endregion
 //#region src/cli/commands/show.ts
 async function runShow(id, options) {
-	const logDir = join(process.cwd(), ".trace-ai-logs");
+	const logDir = join(process.cwd(), ".llm-trace-logs");
 	if (!existsSync(logDir)) {
 		console.log("No active session.");
 		return;
@@ -191,7 +191,7 @@ async function runShow(id, options) {
 //#endregion
 //#region src/cli/commands/start.ts
 async function startSession(projectDir, options = {}) {
-	const logDir = join(projectDir, ".trace-ai-logs");
+	const logDir = join(projectDir, ".llm-trace-logs");
 	if (existsSync(logDir)) return {
 		created: false,
 		reason: "already_active"
@@ -199,17 +199,17 @@ async function startSession(projectDir, options = {}) {
 	mkdirSync(logDir, { recursive: true });
 	const gitignorePath = join(projectDir, ".gitignore");
 	if (existsSync(gitignorePath)) {
-		if (!readFileSync(gitignorePath, "utf-8").includes(".trace-ai-logs/")) appendFileSync(gitignorePath, "\n.trace-ai-logs/\n");
-	} else writeFileSync(gitignorePath, ".trace-ai-logs/\n");
+		if (!readFileSync(gitignorePath, "utf-8").includes(".llm-trace-logs/")) appendFileSync(gitignorePath, "\n.llm-trace-logs/\n");
+	} else writeFileSync(gitignorePath, ".llm-trace-logs/\n");
 	if (!options.skipServer) {
-		const port = parseInt(process.env.TRACE_AI_PORT || "", 10) || 13579;
+		const port = parseInt(process.env.LLM_TRACE_PORT || "", 10) || 13579;
 		const script = join(fileURLToPath(import.meta.url), "..", "standalone.js");
 		const child = spawn(process.execPath, [script], {
 			detached: true,
 			stdio: "ignore",
 			env: {
 				...process.env,
-				TRACE_AI_PORT: String(port),
+				LLM_TRACE_PORT: String(port),
 				TRACE_AI_DIR: logDir
 			}
 		});
@@ -234,7 +234,7 @@ async function runStart() {
 //#endregion
 //#region src/cli/commands/status.ts
 function getSessionStatus(projectDir) {
-	const logDir = join(projectDir, ".trace-ai-logs");
+	const logDir = join(projectDir, ".llm-trace-logs");
 	if (!existsSync(logDir)) return { active: false };
 	const files = readdirSync(logDir).filter((f) => f.endsWith(".ndjson"));
 	let errorCount = 0;
@@ -264,7 +264,7 @@ async function runStatus() {
 //#endregion
 //#region src/cli/commands/stop.ts
 async function stopSession(projectDir) {
-	const logDir = join(projectDir, ".trace-ai-logs");
+	const logDir = join(projectDir, ".llm-trace-logs");
 	if (!existsSync(logDir)) return {
 		stopped: false,
 		reason: "no_session"
@@ -294,7 +294,7 @@ function summarizeFile(filePath) {
 	}
 }
 async function runTail(options) {
-	const logDir = join(process.cwd(), ".trace-ai-logs");
+	const logDir = join(process.cwd(), ".llm-trace-logs");
 	if (!existsSync(logDir)) {
 		console.log("No active session.");
 		return;
@@ -343,15 +343,15 @@ function parseCliArgs(argv) {
 
 //#endregion
 //#region src/cli/index.ts
-const HELP = `trace-ai — Structured execution traces for LLM debugging
+const HELP = `llm-trace — Structured execution traces for LLM debugging
 
 Usage:
-  trace-ai start              Begin debugging session
-  trace-ai stop               End session, delete traces
-  trace-ai status             Show session info
-  trace-ai list [--errors] [--name <pattern>] [--last <n>] [--human]
-  trace-ai show <id> [--human]
-  trace-ai tail [--errors] [--name <pattern>]
+  llm-trace start              Begin debugging session
+  llm-trace stop               End session, delete traces
+  llm-trace status             Show session info
+  llm-trace list [--errors] [--name <pattern>] [--last <n>] [--human]
+  llm-trace show <id> [--human]
+  llm-trace tail [--errors] [--name <pattern>]
 `;
 async function main() {
 	const { command, id, options } = parseCliArgs(process.argv.slice(2));
@@ -362,7 +362,7 @@ async function main() {
 		case "list": return runList(options);
 		case "show":
 			if (!id) {
-				console.error("Usage: trace-ai show <id>");
+				console.error("Usage: llm-trace show <id>");
 				process.exit(1);
 			}
 			return runShow(id, options);

package/dist/index.cjs

@@ -157,7 +157,7 @@ function createHttpWriter(serverUrl) {
 			});
 		} catch {
 			if (!warned) {
-				console.warn("[trace-ai] Server not running, traces disabled.");
+				console.warn("[llm-trace] Server not running, traces disabled.");
 				warned = true;
 			}
 		}
@@ -188,7 +188,7 @@ function createHttpWriter(serverUrl) {
 //#endregion
 //#region src/index.ts
 const defaultTracer = createTracer({
-	writer: createHttpWriter(`http://127.0.0.1:${(typeof process !== "undefined" ? parseInt(process.env?.TRACE_AI_PORT || "", 10) : NaN) || 13579}`),
+	writer: createHttpWriter(`http://127.0.0.1:${(typeof process !== "undefined" ? parseInt(process.env?.LLM_TRACE_PORT || "", 10) : NaN) || 13579}`),
 	idGenerator: createCryptoIdGenerator(),
 	clock: createSystemClock()
 });

package/dist/index.js

@@ -156,7 +156,7 @@ function createHttpWriter(serverUrl) {
 			});
 		} catch {
 			if (!warned) {
-				console.warn("[trace-ai] Server not running, traces disabled.");
+				console.warn("[llm-trace] Server not running, traces disabled.");
 				warned = true;
 			}
 		}
@@ -187,7 +187,7 @@ function createHttpWriter(serverUrl) {
 //#endregion
 //#region src/index.ts
 const defaultTracer = createTracer({
-	writer: createHttpWriter(`http://127.0.0.1:${(typeof process !== "undefined" ? parseInt(process.env?.TRACE_AI_PORT || "", 10) : NaN) || 13579}`),
+	writer: createHttpWriter(`http://127.0.0.1:${(typeof process !== "undefined" ? parseInt(process.env?.LLM_TRACE_PORT || "", 10) : NaN) || 13579}`),
 	idGenerator: createCryptoIdGenerator(),
 	clock: createSystemClock()
 });

package/dist/standalone.cjs

@@ -65,7 +65,7 @@ function createTraceServer(logDir) {
 
 //#endregion
 //#region src/server/standalone.ts
-const port = parseInt(process.env.TRACE_AI_PORT || "13579", 10);
+const port = parseInt(process.env.LLM_TRACE_PORT || "13579", 10);
 const logDir = process.env.TRACE_AI_DIR || "";
 if (!logDir) {
 	console.error("TRACE_AI_DIR required");

package/dist/standalone.js

@@ -65,7 +65,7 @@ function createTraceServer(logDir) {
 
 //#endregion
 //#region src/server/standalone.ts
-const port = parseInt(process.env.TRACE_AI_PORT || "13579", 10);
+const port = parseInt(process.env.LLM_TRACE_PORT || "13579", 10);
 const logDir = process.env.TRACE_AI_DIR || "";
 if (!logDir) {
 	console.error("TRACE_AI_DIR required");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-trace",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": false,
   "description": "Structured execution traces for LLM debugging",
   "license": "MIT",