agent-postflight 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bharath Natarajan
+
+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,84 @@
+# postflight
+
+**read your agent's run back.**
+
+vercel shipped agent observability into deploys this week. langsmith, langfuse, braintrust,
+helicone all did it before them. the dashboard is table stakes now. it was never the point.
+
+the point of a run is to make the *next* run better. postflight is a tiny, local, harness-neutral
+CLI that turns an agent transcript into a **flight review + the skill to extract** — not a chart to
+stare at.
+
+```
+npx agent-postflight
+```
+
+no signup, no SDK, no platform. it reads your most recent Claude Code run and tells you where the
+loop leaked.
+
+## the demo is the argument
+
+run it on a real session:
+
+```
+$ npx agent-postflight
+
+# postflight — flight review
+
+**725 tool calls** across 1,434 turns · 20 distinct tools · 3d 8h (resumed) · 1,319,024 tokens generated
+
+> worth a look: 26 tool errors (4%) · ~57,015 tokens re-reading the same things · 8 redundant read patterns · 8 retry loops
+
+## redundant work — the agent re-derived the same thing
+- `Read` × 27 — `site/agent-worker/src/index.ts` · ~29,128 tokens
+- `Read` × 8  — `README.md` · ~1,344 tokens
+- `Read` × 7  — `site/index.html` · ~9,396 tokens
+
+## the skill to extract →
+the agent ran `Read` on index.ts 27× — re-deriving the same thing instead of remembering it.
+capture its durable facts once (a skill, or a line in CLAUDE.md), and the next run reads it once.
+```
+
+that `Read × 27` is a real number from a real session. the agent read the same file twenty-seven
+times because nothing told it to remember. that's not a model problem. it's a missing loop — and a
+missing loop is a skill waiting to be written.
+
+## what it finds
+
+- **redundant work** — the same file read, the same command run, the same search repeated. with a
+  rough token cost for the re-reads.
+- **retry loops** — a tool that errored, then got tried again (and whether it ever recovered).
+- **heaviest turns** — where the output tokens actually went.
+- **run shape** — the dominant tool-to-tool pattern.
+- **the skill to extract** — the one thing repeated enough that it should be captured once.
+  `--skill` writes a `SKILL.md` scaffold for it. that's the loop, closed.
+
+## usage
+
+```
+postflight                    review your latest Claude Code run
+postflight path/to/run.jsonl  review a specific transcript
+postflight --list             list recent runs
+postflight --json             findings as JSON (pipe it anywhere)
+postflight --skill            write the proposed skill to .claude/skills/<name>/SKILL.md
+```
+
+## harness-neutral by design
+
+the Claude Code JSONL reader is the first adapter. the analysis never sees the format — so
+OpenAI Agents SDK, LangGraph, and raw-log adapters are additive, not rewrites. (Claude Code
+first because it's where the transcripts already live on disk. more adapters next.)
+
+## the honest caveat
+
+if your runs are short and tight, postflight will tell you so and find nothing to fix — that's a
+good run, not a failure. and the loop-closing (`--skill`) gives you a *scaffold*, not a finished
+skill; you still write the durable facts. the value is that it points at exactly the right thing to
+capture. it will not fabricate a problem to look useful.
+
+## why this exists
+
+built by [Bharath Natarajan](https://bharath.sh) — this is loop engineering as a tool: a run should
+teach the next run. observability shows you the run. postflight closes the loop.
+
+MIT.

package/bin/postflight.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+// postflight — read your agent's run back.
+// usage: postflight [transcript.jsonl] [--json] [--skill] [--list]
+// with no path, it finds your most recent Claude Code transcript.
+
+import { readdirSync, statSync, existsSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { parseTranscript } from "../lib/parse.js";
+import { analyze } from "../lib/analyze.js";
+import { toMarkdown, skillMarkdown } from "../lib/report.js";
+
+const args = process.argv.slice(2);
+const flags = new Set(args.filter((a) => a.startsWith("--")));
+const positional = args.filter((a) => !a.startsWith("--"));
+
+function findTranscripts() {
+  const base = join(homedir(), ".claude", "projects");
+  if (!existsSync(base)) return [];
+  const out = [];
+  for (const proj of readdirSync(base)) {
+    const dir = join(base, proj);
+    let st;
+    try {
+      st = statSync(dir);
+    } catch {
+      continue;
+    }
+    if (!st.isDirectory()) continue;
+    for (const f of readdirSync(dir)) {
+      if (f.endsWith(".jsonl")) {
+        const p = join(dir, f);
+        try {
+          out.push({ path: p, mtime: statSync(p).mtimeMs, project: proj });
+        } catch {}
+      }
+    }
+  }
+  return out.sort((a, b) => b.mtime - a.mtime);
+}
+
+function main() {
+  if (flags.has("--help") || flags.has("-h")) {
+    console.log(
+      `postflight — read your agent's run back.\n\n` +
+        `usage:\n` +
+        `  postflight [transcript.jsonl]   review a run (default: your latest Claude Code run)\n` +
+        `  postflight --list               list recent runs\n` +
+        `  postflight --json               emit findings as JSON\n` +
+        `  postflight --skill              write the proposed skill to .claude/skills/<name>/SKILL.md\n`
+    );
+    return;
+  }
+
+  const transcripts = findTranscripts();
+
+  if (flags.has("--list")) {
+    if (!transcripts.length) return console.log("no Claude Code transcripts found under ~/.claude/projects");
+    for (const t of transcripts.slice(0, 15)) {
+      console.log(`${new Date(t.mtime).toISOString().slice(0, 16).replace("T", " ")}  ${t.project}`);
+    }
+    return;
+  }
+
+  let path = positional[0];
+  if (!path) {
+    if (!transcripts.length) {
+      console.error(
+        "postflight: no transcript given and none found under ~/.claude/projects.\n" +
+          "pass a path: postflight path/to/run.jsonl"
+      );
+      process.exit(1);
+    }
+    path = transcripts[0].path;
+  }
+  if (!existsSync(path)) {
+    console.error(`postflight: no such file: ${path}`);
+    process.exit(1);
+  }
+
+  const parsed = parseTranscript(path);
+  if (!parsed.toolCalls.length) {
+    console.error("postflight: no tool calls found in that transcript (nothing to review).");
+    process.exit(1);
+  }
+  const a = analyze(parsed);
+
+  if (flags.has("--json")) {
+    console.log(JSON.stringify(a, null, 2));
+    return;
+  }
+
+  process.stdout.write(toMarkdown(a, { source: path }));
+
+  if (flags.has("--skill")) {
+    if (!a.skill) {
+      console.error("\npostflight: nothing repeated enough to extract a skill from this run.");
+      return;
+    }
+    const dir = join(process.cwd(), ".claude", "skills", a.skill.name);
+    mkdirSync(dir, { recursive: true });
+    const out = join(dir, "SKILL.md");
+    writeFileSync(out, skillMarkdown(a.skill) + "\n");
+    console.error(`\npostflight: wrote proposed skill → ${out} (review before using)`);
+  }
+}
+
+main();

package/lib/analyze.js

@@ -0,0 +1,127 @@
+// analyze.js — the flight review. Takes the harness-neutral parse output and finds
+// the loops: redundant read-like calls, error/retry chains, and the dominant
+// repeated workflow worth extracting into a skill. No dashboards — findings + a fix.
+
+const APPROX_TOKENS_PER_CHAR = 0.27; // ~4 chars/token, for rough "re-read" cost
+
+function slug(s) {
+  return (
+    (s || "pattern")
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 40) || "pattern"
+  );
+}
+
+export function analyze(parsed) {
+  const { toolCalls } = parsed;
+
+  // --- tool histogram ---
+  const histogram = {};
+  for (const c of toolCalls) histogram[c.name] = (histogram[c.name] || 0) + 1;
+
+  // --- redundant read-like calls (same tool + same target, seen >1x) ---
+  const sigCount = new Map(); // sig -> { name, target, count, wastedChars }
+  for (const c of toolCalls) {
+    if (!c.readLike || !c.target) continue;
+    const sig = `${c.name}::${c.target}`;
+    const e = sigCount.get(sig) || { name: c.name, target: c.target, count: 0, chars: 0 };
+    e.count++;
+    e.chars += c.resultLen || 0;
+    sigCount.set(sig, e);
+  }
+  const redundant = [...sigCount.values()]
+    .filter((e) => e.count > 1)
+    .map((e) => ({
+      name: e.name,
+      target: e.target,
+      count: e.count,
+      // wasted = the repeats (count-1) worth of re-read result payload
+      wastedTokens: Math.round(((e.chars * (e.count - 1)) / e.count) * APPROX_TOKENS_PER_CHAR),
+    }))
+    .sort((a, b) => b.count - a.count || b.wastedTokens - a.wastedTokens);
+
+  // --- error / retry chains: an errored call followed by same-tool calls nearby ---
+  const errors = toolCalls.filter((c) => c.isError);
+  const retryChains = [];
+  for (let i = 0; i < toolCalls.length; i++) {
+    const c = toolCalls[i];
+    if (!c.isError) continue;
+    // look ahead up to 3 calls for a same-tool retry
+    let j = i + 1;
+    const chain = [c];
+    while (j < toolCalls.length && j <= i + 4) {
+      const n = toolCalls[j];
+      if (n.name === c.name) {
+        chain.push(n);
+        if (!n.isError) break; // recovered
+      }
+      j++;
+    }
+    if (chain.length > 1) {
+      retryChains.push({
+        name: c.name,
+        target: c.target,
+        attempts: chain.length,
+        recovered: !chain[chain.length - 1].isError,
+        atSeq: c.seq,
+      });
+      i = j; // skip past this chain
+    }
+  }
+
+  // --- heaviest turns by output tokens ---
+  const heaviest = [...parsed.heavy].sort((a, b) => b.outputTokens - a.outputTokens).slice(0, 3);
+
+  // --- run shape: the most common consecutive tool bigram (a separate stat) ---
+  const bigrams = new Map();
+  for (let i = 1; i < toolCalls.length; i++) {
+    const k = `${toolCalls[i - 1].name} → ${toolCalls[i].name}`;
+    bigrams.set(k, (bigrams.get(k) || 0) + 1);
+  }
+  const topBigram = [...bigrams.entries()].sort((a, b) => b[1] - a[1])[0];
+
+  // --- the skill to extract: the most re-derived read target, framed coherently ---
+  // if the agent re-read the same thing 3+ times, it never remembered it — that's a
+  // skill (or a CLAUDE.md fact) waiting to be written. This is the loop-closing move.
+  let skill = null;
+  const topRepeat = redundant[0];
+  if (topRepeat && topRepeat.count >= 3) {
+    const subject = topRepeat.target.split(/[\/\s]/).filter(Boolean).slice(-1)[0] || topRepeat.target;
+    skill = {
+      name: slug(`${subject}-context`),
+      kind: topRepeat.name,
+      target: topRepeat.target,
+      count: topRepeat.count,
+      why:
+        `the agent ran \`${topRepeat.name}\` on this **${topRepeat.count}×** — re-deriving the same thing ` +
+        `instead of remembering it. capture its durable facts once (a skill, or a line in CLAUDE.md/AGENTS.md), ` +
+        `and the next run reads it once.`,
+    };
+  }
+
+  const wastedTokens = redundant.reduce((a, r) => a + r.wastedTokens, 0);
+
+  return {
+    summary: {
+      toolCalls: toolCalls.length,
+      distinctTools: Object.keys(histogram).length,
+      assistantTurns: parsed.assistantTurns,
+      errorCount: errors.length,
+      errorRate: toolCalls.length ? errors.length / toolCalls.length : 0,
+      // honest token accounting: output = real generation. context re-read (cache)
+      // is reported separately — you can't sum per-turn input, it re-sends context.
+      outputTokens: parsed.usage.output,
+      contextReadTokens: parsed.usage.cacheRead,
+      wastedTokens,
+      durationMs: parsed.durationMs,
+      runShape: topBigram ? { pair: topBigram[0], count: topBigram[1] } : null,
+    },
+    histogram,
+    redundant: redundant.slice(0, 8),
+    retryChains: retryChains.slice(0, 8),
+    heaviest,
+    skill,
+  };
+}

package/lib/parse.js

@@ -0,0 +1,135 @@
+// parse.js — turn a Claude Code JSONL transcript into an ordered list of tool
+// calls + token usage. Harness-neutral by design: the Claude Code reader is the
+// first adapter; the shape it returns (a flat `events`/`toolCalls` model) is what
+// every other adapter will produce, so analyze/report never learn the format.
+
+import { readFileSync } from "node:fs";
+
+// Normalize a tool call's input into a stable signature target, so "read the same
+// file twice" collapses to one signature regardless of incidental key order.
+function targetOf(name, input) {
+  input = input || {};
+  switch (name) {
+    case "Read":
+    case "Edit":
+    case "Write":
+    case "NotebookEdit":
+      return input.file_path || input.path || "";
+    case "Bash":
+      return (input.command || "").trim().replace(/\s+/g, " ");
+    case "Grep":
+      return `${input.pattern || ""} :: ${input.path || input.glob || ""}`;
+    case "Glob":
+      return input.pattern || "";
+    case "WebFetch":
+      return input.url || "";
+    case "WebSearch":
+      return input.query || "";
+    case "Task":
+    case "Agent":
+      return (input.description || input.subagent_type || "").trim();
+    default: {
+      try {
+        return JSON.stringify(input).slice(0, 200);
+      } catch {
+        return "";
+      }
+    }
+  }
+}
+
+// Tools that READ state and should be idempotent — repeating them verbatim is the
+// smell postflight looks for. Repeating an Edit/Write is often legitimate.
+const READ_LIKE = new Set(["Read", "Grep", "Glob", "Bash", "WebFetch", "WebSearch"]);
+
+export function parseTranscript(path) {
+  const raw = readFileSync(path, "utf8");
+  const lines = raw.split("\n");
+
+  const toolCalls = []; // ordered
+  const resultsById = new Map(); // tool_use_id -> { isError, len }
+  const usage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+  let assistantTurns = 0;
+  let userTurns = 0;
+  let firstTs = null;
+  let lastTs = null;
+  let seq = 0;
+  const heavy = []; // { seq, outputTokens, firstToolAfter }
+
+  for (const line of lines) {
+    const s = line.trim();
+    if (!s) continue;
+    let d;
+    try {
+      d = JSON.parse(s);
+    } catch {
+      continue;
+    }
+    if (d.timestamp) {
+      const t = Date.parse(d.timestamp);
+      if (!Number.isNaN(t)) {
+        firstTs = firstTs === null ? t : Math.min(firstTs, t);
+        lastTs = lastTs === null ? t : Math.max(lastTs, t);
+      }
+    }
+    const msg = d.message;
+    if (!msg || typeof msg !== "object") continue;
+
+    if (d.type === "assistant") {
+      assistantTurns++;
+      const u = msg.usage;
+      if (u) {
+        usage.input += u.input_tokens || 0;
+        usage.output += u.output_tokens || 0;
+        usage.cacheRead += u.cache_read_input_tokens || 0;
+        usage.cacheWrite += u.cache_creation_input_tokens || 0;
+        heavy.push({ turn: assistantTurns, outputTokens: u.output_tokens || 0 });
+      }
+    } else if (d.type === "user") {
+      userTurns++;
+    }
+
+    const content = msg.content;
+    if (!Array.isArray(content)) continue;
+    for (const b of content) {
+      if (!b || typeof b !== "object") continue;
+      if (b.type === "tool_use") {
+        toolCalls.push({
+          seq: seq++,
+          id: b.id || null,
+          name: b.name || "?",
+          target: targetOf(b.name, b.input),
+          readLike: READ_LIKE.has(b.name),
+          ts: d.timestamp ? Date.parse(d.timestamp) : null,
+        });
+      } else if (b.type === "tool_result") {
+        const id = b.tool_use_id;
+        if (id) {
+          let len = 0;
+          const c = b.content;
+          if (typeof c === "string") len = c.length;
+          else if (Array.isArray(c))
+            len = c.reduce((a, x) => a + (typeof x?.text === "string" ? x.text.length : 0), 0);
+          resultsById.set(id, { isError: !!b.is_error, len });
+        }
+      }
+    }
+  }
+
+  // attach results to their calls
+  for (const call of toolCalls) {
+    const r = call.id ? resultsById.get(call.id) : null;
+    call.isError = r ? r.isError : false;
+    call.resultLen = r ? r.len : 0;
+  }
+
+  return {
+    path,
+    toolCalls,
+    usage,
+    assistantTurns,
+    userTurns,
+    durationMs: firstTs !== null && lastTs !== null ? lastTs - firstTs : null,
+    heavy,
+  };
+}

package/lib/report.js

@@ -0,0 +1,110 @@
+// report.js — render the flight review as markdown (the human-readable argument)
+// and the proposed skill as an extractable SKILL.md scaffold.
+
+function fmt(n) {
+  return Math.round(n).toLocaleString("en-US");
+}
+function dur(ms) {
+  if (ms == null) return "unknown";
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ${s % 60}s`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ${m % 60}m`;
+  const d = Math.floor(h / 24);
+  return `${d}d ${h % 24}h (resumed)`;
+}
+
+export function toMarkdown(a, meta = {}) {
+  const s = a.summary;
+  const L = [];
+  L.push(`# postflight — flight review`);
+  if (meta.source) L.push(`\n\`${meta.source}\``);
+  L.push("");
+  L.push(
+    `**${fmt(s.toolCalls)} tool calls** across ${fmt(s.assistantTurns)} turns · ` +
+      `${fmt(s.distinctTools)} distinct tools · ${dur(s.durationMs)} · ` +
+      `${fmt(s.outputTokens)} tokens generated`
+  );
+
+  const flags = [];
+  if (s.errorCount) flags.push(`${s.errorCount} tool errors (${(s.errorRate * 100).toFixed(0)}%)`);
+  if (s.wastedTokens) flags.push(`~${fmt(s.wastedTokens)} tokens re-reading the same things`);
+  if (a.redundant.length) flags.push(`${a.redundant.length} redundant read patterns`);
+  if (a.retryChains.length) flags.push(`${a.retryChains.length} retry loops`);
+  if (flags.length) L.push(`\n> **worth a look:** ${flags.join(" · ")}`);
+  else L.push(`\n> clean run — no redundant reads or retry loops detected.`);
+
+  if (a.redundant.length) {
+    L.push(`\n## redundant work — the agent re-derived the same thing`);
+    for (const r of a.redundant) {
+      const w = r.wastedTokens ? ` · ~${fmt(r.wastedTokens)} tokens` : "";
+      L.push(`- \`${r.name}\` × **${r.count}** — \`${trunc(r.target, 76)}\`${w}`);
+    }
+  }
+
+  if (a.retryChains.length) {
+    L.push(`\n## retry loops — errored, then tried again`);
+    for (const c of a.retryChains) {
+      const ok = c.recovered ? "recovered" : "**never recovered**";
+      L.push(`- \`${c.name}\` — ${c.attempts} attempts, ${ok} — \`${trunc(c.target, 60)}\``);
+    }
+  }
+
+  if (a.heaviest.length) {
+    L.push(`\n## heaviest turns (by output tokens)`);
+    for (const h of a.heaviest) L.push(`- turn ${h.turn} — ${fmt(h.outputTokens)} tokens`);
+  }
+
+  const shape = s.runShape ? ` · run shape: \`${s.runShape.pair}\` ×${s.runShape.count}` : "";
+  L.push(`\n## tool mix`);
+  L.push(
+    Object.entries(a.histogram)
+      .sort((x, y) => y[1] - x[1])
+      .map(([n, c]) => `${n} ${c}`)
+      .join(" · ") + shape
+  );
+
+  L.push(`\n## the skill to extract →`);
+  if (a.skill) {
+    L.push(a.skill.why);
+    L.push("\n```markdown");
+    L.push(skillMarkdown(a.skill));
+    L.push("```");
+    L.push(
+      `\n_close the loop: save that as \`.claude/skills/${a.skill.name}/SKILL.md\` (or drop the facts into ` +
+        `CLAUDE.md), and the next run stops rediscovering it._`
+    );
+  } else {
+    L.push(`nothing repeated ≥3× this run — nothing worth extracting. that's a tight run.`);
+  }
+
+  return L.join("\n") + "\n";
+}
+
+export function skillMarkdown(skill) {
+  const subject = skill.target.split(/[\/\s]/).filter(Boolean).slice(-1)[0] || skill.target;
+  return [
+    `---`,
+    `name: ${skill.name}`,
+    `description: Use when you need to know about ${subject}. postflight saw the agent ${skill.kind} it ${skill.count}× in one run — capture it once here so it isn't re-derived.`,
+    `---`,
+    ``,
+    `# ${skill.name}`,
+    ``,
+    `\`${skill.target}\``,
+    ``,
+    `The agent re-read this ${skill.count} times in a single run. Write its durable facts here —`,
+    `what it is, the 3-5 things worth knowing, the gotchas — so the next run reads it once:`,
+    ``,
+    `- <key fact 1>`,
+    `- <key fact 2>`,
+    `- <gotcha>`,
+  ].join("\n");
+}
+
+function trunc(s, n) {
+  s = String(s || "");
+  return s.length > n ? s.slice(0, n - 1) + "…" : s;
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "agent-postflight",
+  "version": "0.1.0",
+  "description": "Read your agent's run back. A harness-neutral CLI that turns an agent transcript into a flight review + a skill to extract — so the next run is better, not just observed.",
+  "type": "module",
+  "bin": {
+    "agent-postflight": "bin/postflight.js",
+    "postflight": "bin/postflight.js"
+  },
+  "scripts": {
+    "test": "node test/run.mjs"
+  },
+  "keywords": [
+    "agents",
+    "ai-agents",
+    "claude-code",
+    "observability",
+    "loop-engineering",
+    "agent-experience",
+    "cli",
+    "skills",
+    "mcp"
+  ],
+  "author": "Bharath Natarajan <hi@bharath.sh> (https://bharath.sh)",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "README.md",
+    "LICENSE"
+  ]
+}