@pi-claudian/auto-save-to-markdown 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 licongy
+
+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,137 @@
+# @pi-claudian/auto-save-to-markdown
+
+[![npm version](https://img.shields.io/npm/v/@pi-claudian/auto-save-to-markdown?style=flat&colorA=222222&colorB=CB3837)](https://www.npmjs.com/package/@pi-claudian/auto-save-to-markdown)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+[English](README.md) | [中文](README.zh.md)
+
+A [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) extension
+that automatically saves every completed conversation turn as a markdown file
+with YAML frontmatter — one file per session-tree branch.
+
+## Why
+
+Pi records sessions internally as JSONL trees, which are great for resuming but
+terrible for reading, searching, or archiving. This extension mirrors the
+conversation into plain markdown files as you work, so every exchange is
+preserved in a format any editor, note app, or grep can consume — with the
+model, cost, tokens, and session metadata right in the frontmatter.
+
+## Installation
+
+```
+pi install npm:@pi-claudian/auto-save-to-markdown
+```
+
+## Usage
+
+Automatic: after every settled agent turn (`agent_settled`), the current
+conversation branch is written to `<cwd>/<folder>/<title>-<tree>-<time>.md`.
+
+Manual: run `/save-conversation` to save the current branch immediately and
+report the file path.
+
+## Configuration
+
+The target folder is controlled by the `PI_SAVE_CONVERSATION_DIR` environment
+variable (Pi has no per-extension settings API):
+
+| Value       | Location                            |
+| ----------- | ----------------------------------- |
+| unset       | `<cwd>/ai-conversations/` (default) |
+| `.` or `""` | `<cwd>/` directly                   |
+| `notes/ai`  | `<cwd>/notes/ai/`                   |
+| `/abs/path` | that absolute path                  |
+
+```bash
+PI_SAVE_CONVERSATION_DIR=notes/ai pi
+```
+
+## File naming and frontmatter
+
+Filename: `<title>-<tree>-<time>.md`
+
+- `<title>` — the session name (`/name`), or a slug of the first user message
+  when the session is unnamed
+- `<tree>` — the id of the deepest message entry at file creation (the branch key)
+- `<time>` — local file-creation time, `YYYYMMDD-HHmmss`
+
+```markdown
+---
+title: "Fix login redirect loop"
+session_id: "d0a4f541-976d-4d1b-8e1c-30a1f2b3c4d5"
+tree: "a1b2c3d4"
+model: "claude-sonnet-4-5"
+provider: "anthropic"
+cost: 0.023401
+tokens: 18745
+tokens_input: 15230
+tokens_output: 3515
+messages: 8
+created: "2026-08-29T05:05:12.000Z"
+updated: "2026-08-29T05:42:10.000Z"
+cwd: "/Users/me/project"
+session_file: "~/.pi/agent/sessions/--Users-me-project-20260829-050500_ab12.jsonl"
+---
+
+# Fix login redirect loop
+
+## User · 13:05:12
+
+The login page redirects in a loop after the auth refactor...
+
+## Assistant · 13:05:40 · claude-sonnet-4-5
+
+<details>
+<summary>Thinking</summary>
+
+Let me check the redirect chain...
+
+</details>
+
+I'll trace the middleware order first.
+
+**Tool calls**
+
+- `read` — {"filePath":"/Users/me/project/src/auth/middleware.ts"}
+
+> **Tool · read** /Users/me/project/src/auth/middleware.ts — 120 lines …
+```
+
+The body renders user and assistant messages in full (assistant thinking is
+kept in a collapsible `<details>` block) and summarizes each tool call and
+result in one line, so the file stays readable while still showing what the
+agent did.
+
+## Branch behavior
+
+Pi sessions are trees: `/tree` navigates to an earlier point and a new prompt
+forks a new branch. Each markdown file records exactly **one branch** — the
+root-to-leaf path that branch sees.
+
+- **Same branch, next turn** → new messages are _appended_ to the existing
+  file, and the frontmatter (`cost`, `tokens`, `messages`, `updated`, title,
+  model) is refreshed.
+- **`/tree` + new prompt (a different branch)** → a _new file_ is created
+  containing the full new branch (the shared prefix plus the new exchange).
+- **Forking at the current tip** → the existing file continues (its content is
+  already an exact prefix of the new branch), so no duplicate file is created.
+- **Resuming later** (restart, `/resume`, `/fork`, `/clone`) → the branch is
+  recognized and its file continues where it left off.
+
+Branch identity is persisted inside the session tree itself via extension
+custom entries (never sent to the LLM, not rendered in the TUI), so state
+survives restarts and navigation without any sidecar files.
+
+Compacted sessions still export their **full original history** — the archive
+always contains the complete conversation, not the compacted context.
+
+## Debug
+
+```bash
+PI_CLAUDIAN_DEBUG=1 pi
+```
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,123 @@
+# @pi-claudian/auto-save-to-markdown
+
+[![npm version](https://img.shields.io/npm/v/@pi-claudian/auto-save-to-markdown?style=flat&colorA=222222&colorB=CB3837)](https://www.npmjs.com/package/@pi-claudian/auto-save-to-markdown)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+[English](README.md) | [中文](README.zh.md)
+
+一个 [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) 扩展：每轮对话完成后，自动把当前对话分支保存为带 YAML frontmatter 的 markdown 文件——每个会话树分支一个文件。
+
+## 为什么需要它
+
+Pi 内部以 JSONL 树的形式记录会话，便于恢复却不便于阅读、检索和归档。本扩展在你工作的同时把对话镜像成普通 markdown 文件，每轮交流都以任何编辑器、笔记软件或 grep 都能处理的格式留存，且模型、费用、token 数等元数据都写在 frontmatter 里。
+
+## 安装
+
+```
+pi install npm:@pi-claudian/auto-save-to-markdown
+```
+
+## 用法
+
+自动：每个 agent 轮次完全结束（`agent_settled`，含自动重试与压缩全部完成）后，当前对话分支写入 `<cwd>/<文件夹>/<标题>-<tree>-<时间>.md`。
+
+手动：运行 `/save-conversation` 立即保存当前分支并显示文件路径。
+
+## 配置
+
+目标文件夹由环境变量 `PI_SAVE_CONVERSATION_DIR` 控制（Pi 没有扩展设置 API）：
+
+| 取值        | 保存位置                          |
+| ----------- | --------------------------------- |
+| 未设置      | `<cwd>/ai-conversations/`（默认） |
+| `.` 或 `""` | 直接保存在 `<cwd>/`               |
+| `notes/ai`  | `<cwd>/notes/ai/`                 |
+| `/绝对路径` | 该绝对路径                        |
+
+```bash
+PI_SAVE_CONVERSATION_DIR=notes/ai pi
+```
+
+## 文件名与 frontmatter
+
+文件名：`<标题>-<tree>-<时间>.md`
+
+- `<标题>` — 会话名称（`/name`）；未命名时取第一条用户消息的摘要
+- `<tree>` — 建文件时分支上最深一条消息的 entry id（分支标识）
+- `<时间>` — 建文件的本地时间，格式 `YYYYMMDD-HHmmss`
+
+```markdown
+---
+title: "修复登录重定向死循环"
+session_id: "d0a4f541-976d-4d1b-8e1c-30a1f2b3c4d5"
+tree: "a1b2c3d4"
+model: "claude-sonnet-4-5"
+provider: "anthropic"
+cost: 0.023401
+tokens: 18745
+tokens_input: 15230
+tokens_output: 3515
+messages: 8
+created: "2026-08-29T05:05:12.000Z"
+updated: "2026-08-29T05:42:10.000Z"
+cwd: "/Users/me/project"
+session_file: "~/.pi/agent/sessions/--Users-me-project-20260829-050500_ab12.jsonl"
+---
+
+# 修复登录重定向死循环
+
+## User · 13:05:12
+
+auth 重构之后登录页一直重定向死循环……
+
+## Assistant · 13:05:40 · claude-sonnet-4-5
+
+<details>
+<summary>Thinking</summary>
+
+先看中间件的执行顺序……
+
+</details>
+
+我先追踪一下中间件链。
+
+**Tool calls**
+
+- `read` — {"filePath":"/Users/me/project/src/auth/middleware.ts"}
+
+> **Tool · read** /Users/me/project/src/auth/middleware.ts — 120 lines …
+```
+
+正文完整渲染 user / assistant 消息（assistant 的 thinking 放在可折叠的
+`<details>` 块中），每个工具调用和结果各压缩成一行摘要，既可读又能看出
+agent 做了什么。
+
+## 分支行为
+
+Pi 会话是树：`/tree` 导航到更早的位置后再提问就分出新的分支。每个
+markdown 文件只记录**一个分支**——即该分支看到的 root→leaf 完整路径。
+
+- **同一分支继续对话** → 新消息*追加*到已有文件，frontmatter（`cost`、
+  `tokens`、`messages`、`updated`、标题、模型）同步刷新。
+- **`/tree` 后重新提问（不同分支）** → _另存新文件_，内容为新分支的完整
+  路径（共享前缀 + 新对话）。
+- **在当前末端分叉** → 已有文件继续追加（其内容恰好是新分支的精确前缀），
+  不会产生重复文件。
+- **之后恢复会话**（重启、`/resume`、`/fork`、`/clone`）→ 分支被识别，
+  对应文件从上次的位置继续。
+
+分支状态以扩展 custom entry 的形式持久化在会话树内部（不进 LLM 上下文、
+不在 TUI 渲染），因此无需任何辅助文件即可在重启和导航后恢复状态。
+
+被压缩（compaction）过的会话导出的仍是**完整原始历史**——归档永远是全量
+对话，而不是压缩后的上下文。
+
+## 调试
+
+```bash
+PI_CLAUDIAN_DEBUG=1 pi
+```
+
+## 许可
+
+MIT

package/debug.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared debug logging for all @pi-claudian extensions.
+ *
+ * Enable by setting the PI_CLAUDIAN_DEBUG environment variable to any truthy
+ * value (e.g. "1"). Output goes to stderr via console.error, so it never mixes
+ * with pi's stdout and can be captured separately:
+ *
+ *   PI_CLAUDIAN_DEBUG=1 pi            # show inline
+ *   PI_CLAUDIAN_DEBUG=1 pi 2>debug.log  # capture to a file
+ *
+ * This is a source-only module (Pi loads it via jiti). Each @pi-claudian
+ * package vendors its own copy and imports it, keeping packages independent —
+ * the shared contract is the PI_CLAUDIAN_DEBUG env var name, not a shared
+ * npm dependency.
+ */
+
+const TAG = "[pi-claudian]";
+const enabled = Boolean(process.env.PI_CLAUDIAN_DEBUG);
+
+/** Log a debug message when PI_CLAUDIAN_DEBUG is set. */
+export function debug(...args: unknown[]): void {
+  if (!enabled) return;
+  console.error(TAG, ...args);
+}

package/index.ts

@@ -0,0 +1,599 @@
+/**
+ * @pi-claudian/auto-save-to-markdown
+ *
+ * Automatically saves the current conversation to a markdown file after every
+ * completed agent turn, with session metadata in a YAML frontmatter block.
+ *
+ * Behavior:
+ *
+ * - Trigger: `agent_settled` — fires once per user prompt, after the turn is
+ *   fully done (including automatic retries and compaction), so each save
+ *   captures a settled state of the conversation.
+ * - Location: a subfolder of the session's working directory (`ctx.cwd`, the
+ *   directory the session was started in), defaulting to `ai-conversations`.
+ *   Override with the PI_SAVE_CONVERSATION_DIR environment variable; set it to
+ *   "." or "" to save directly into the working directory.
+ * - Filename: `<title>-<tree>-<time>.md`, where <title> is the session name
+ *   (or a slug of the first user message when unnamed), <tree> is the 8-hex id
+ *   of the deepest message entry at file creation, and <time> is the local
+ *   file-creation timestamp (YYYYMMDD-HHmmss).
+ * - Frontmatter: title, session id, tree (branch key), model, provider,
+ *   cumulative cost and tokens, message count, created/updated timestamps,
+ *   cwd and session file.
+ * - Branching: each file records exactly ONE branch (the root→leaf path
+ *   returned by sessionManager.getBranch()). State is persisted via
+ *   `pi.appendEntry()` custom entries, which are part of the session tree
+ *   itself — they are not sent to the LLM and not rendered in the TUI. On
+ *   every save the extension finds the file whose latest saved position is the
+ *   deepest entry still on the current path; if the tree moved elsewhere
+ *   (e.g. /tree navigation followed by a new prompt), no file matches and a
+ *   new file is created with the full current branch. Continuing an existing
+ *   branch appends only the messages that are new since the last save.
+ * - Compaction: files archive the ORIGINAL messages (getBranch() returns the
+ *   raw tree path, not the compaction-aware context), so a compacted session
+ *   still exports its complete history.
+ *
+ * Manual command: `/save-conversation` saves the current branch immediately
+ * and reports the file path.
+ *
+ * Installation:
+ *   pi install npm:@pi-claudian/auto-save-to-markdown
+ *
+ * Debug:
+ *   PI_CLAUDIAN_DEBUG=1 pi
+ */
+
+import type {
+  AgentSettledEvent,
+  ExtensionAPI,
+  ExtensionCommandContext,
+  ExtensionContext,
+  SessionEntry,
+  SessionMessageEntry,
+} from "@earendil-works/pi-coding-agent";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { debug } from "./debug.js";
+
+const CUSTOM_TYPE = "pi-claudian-auto-save-markdown";
+const ENV_SUBDIR = "PI_SAVE_CONVERSATION_DIR";
+const DEFAULT_SUBDIR = "ai-conversations";
+const COMMAND = "save-conversation";
+const NOTIFY_TAG = "[AutoSave]";
+
+const MAX_TITLE_LENGTH = 60;
+const TITLE_FALLBACK_LENGTH = 40;
+const TOOL_RESULT_PREVIEW = 300;
+const TOOL_ARGS_PREVIEW = 160;
+
+type AgentMessage = SessionMessageEntry["message"];
+type UserMessage = Extract<AgentMessage, { role: "user" }>;
+type AssistantMessage = Extract<AgentMessage, { role: "assistant" }>;
+type ToolResultMessage = Extract<AgentMessage, { role: "toolResult" }>;
+
+/**
+ * Per-save state persisted in the session tree via pi.appendEntry().
+ * `file` is the bare filename inside the target directory, so changing the
+ * configured directory (env var) moves future saves without breaking
+ * resolution — the file is simply recreated from the full branch if missing.
+ */
+interface SaveState {
+  branchKey: string;
+  lastSavedEntryId: string | null;
+  file: string;
+}
+
+function isSaveState(v: unknown): v is SaveState {
+  if (typeof v !== "object" || v === null) return false;
+  const s = v as Record<string, unknown>;
+  return (
+    typeof s.branchKey === "string" &&
+    s.branchKey.length > 0 &&
+    (s.lastSavedEntryId === null || typeof s.lastSavedEntryId === "string") &&
+    typeof s.file === "string" &&
+    s.file.length > 0
+  );
+}
+
+interface SaveResult {
+  message: string;
+  /** A file was actually written (created or appended). */
+  wrote: boolean;
+  /** The write created a brand-new file (vs appending to an existing one). */
+  created: boolean;
+  file: string | null;
+}
+
+interface BranchMeta {
+  title: string;
+  sessionId: string | null;
+  sessionFile: string | null;
+  tree: string;
+  model: string | null;
+  provider: string | null;
+  cost: number;
+  tokensInput: number;
+  tokensOutput: number;
+  messages: number;
+  created: string;
+  updated: string;
+  cwd: string;
+}
+
+export default function (pi: ExtensionAPI) {
+  /**
+   * Resolve the target directory. The env var may hold a relative folder name
+   * (resolved against the session cwd), an absolute path, or "." / "" for the
+   * working directory itself. When unset, the default subfolder is used.
+   */
+  function targetDir(ctx: ExtensionContext): string {
+    const env = process.env[ENV_SUBDIR];
+    if (env === undefined) return path.join(ctx.cwd, DEFAULT_SUBDIR);
+    const raw = env.trim();
+    if (raw === "" || raw === ".") return ctx.cwd;
+    return path.resolve(ctx.cwd, raw);
+  }
+
+  // ---------- formatting helpers ----------
+
+  function pad(n: number): string {
+    return String(n).padStart(2, "0");
+  }
+
+  /** Local-time filename timestamp: YYYYMMDD-HHmmss. */
+  function fileTimestamp(d: Date): string {
+    return (
+      `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}` +
+      `-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`
+    );
+  }
+
+  /** Local-time clock label for a message entry: HH:MM:SS. */
+  function clock(iso: string): string {
+    const d = new Date(iso);
+    return `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+  }
+
+  /** Make a string safe for use as a filename component. */
+  function sanitizeFilenamePart(s: string): string {
+    return s
+      .replace(/[\u0000-\u001f\u007f]/g, "")
+      .replace(/[\\/:*?"<>|]/g, "-")
+      .replace(/\s+/g, " ")
+      .trim()
+      .replace(/\s/g, "-")
+      .replace(/-+/g, "-")
+      .replace(/^[-.]+|[-.]+$/g, "")
+      .slice(0, MAX_TITLE_LENGTH)
+      .replace(/[-.]+$/g, "");
+  }
+
+  /** Extract the plain text of a user message content (string or blocks). */
+  function userText(content: UserMessage["content"]): string {
+    if (typeof content === "string") return content;
+    return content
+      .map((b) =>
+        b.type === "text" ? b.text : `_[image: ${"mimeType" in b ? b.mimeType : "unknown"}]_`,
+      )
+      .join("\n\n");
+  }
+
+  function firstUserText(messages: SessionMessageEntry[]): string | undefined {
+    for (const e of messages) {
+      if (e.message.role === "user") return userText(e.message.content) || undefined;
+    }
+    return undefined;
+  }
+
+  /** Title for the filename: session name, else a slug of the first user message. */
+  function titleForFilename(ctx: ExtensionContext, firstUser: string | undefined): string {
+    const name = ctx.sessionManager.getSessionName()?.trim();
+    if (name) return sanitizeFilenamePart(name) || "untitled";
+    if (firstUser) {
+      const slug = sanitizeFilenamePart(firstUser.slice(0, TITLE_FALLBACK_LENGTH));
+      if (slug) return slug;
+    }
+    return "untitled";
+  }
+
+  /** Title for the frontmatter / document heading. */
+  function displayTitle(ctx: ExtensionContext, firstUser: string | undefined): string {
+    const name = ctx.sessionManager.getSessionName()?.trim();
+    if (name) return name;
+    if (firstUser) {
+      const snippet = firstUser.replace(/\s+/g, " ").trim().slice(0, MAX_TITLE_LENGTH);
+      if (snippet) return snippet;
+    }
+    return "untitled";
+  }
+
+  function previewArgs(args: unknown): string {
+    let s: string;
+    try {
+      s = JSON.stringify(args) ?? "";
+    } catch {
+      s = String(args);
+    }
+    s = s.replace(/\s+/g, " ").trim();
+    return s.length > TOOL_ARGS_PREVIEW ? s.slice(0, TOOL_ARGS_PREVIEW) + " …" : s;
+  }
+
+  // ---------- markdown rendering ----------
+
+  function renderAssistant(m: AssistantMessage, t: string): string {
+    const texts: string[] = [];
+    const thinkings: string[] = [];
+    const calls: string[] = [];
+    for (const b of m.content) {
+      if (b.type === "text") texts.push(b.text);
+      else if (b.type === "thinking") thinkings.push(b.thinking);
+      else if (b.type === "toolCall") calls.push(`- \`${b.name}\` — ${previewArgs(b.arguments)}`);
+    }
+
+    const header = `## Assistant · ${t}${m.model ? ` · ${m.model}` : ""}`;
+    const parts: string[] = [];
+    if (texts.length) parts.push(texts.join("\n\n"));
+    if (thinkings.length) {
+      parts.push(
+        `<details>\n<summary>Thinking</summary>\n\n${thinkings.join("\n\n")}\n\n</details>`,
+      );
+    }
+    if (calls.length) parts.push(`**Tool calls**\n\n${calls.join("\n")}`);
+    if (m.errorMessage) parts.push(`> Error: ${m.errorMessage.replace(/\s+/g, " ").trim()}`);
+    if (parts.length === 0) parts.push("_(empty response)_");
+    return `${header}\n\n${parts.join("\n\n")}`;
+  }
+
+  function renderToolResult(m: ToolResultMessage): string {
+    const texts: string[] = [];
+    for (const b of m.content) {
+      if (b.type === "text") texts.push(b.text);
+      else texts.push(`_[image: ${b.mimeType}]_`);
+    }
+    const flat = texts.join(" ").replace(/\s+/g, " ").trim();
+    const capped =
+      flat.length > TOOL_RESULT_PREVIEW ? flat.slice(0, TOOL_RESULT_PREVIEW) + " …" : flat;
+    const status = m.isError ? " (error)" : "";
+    const line = `> **Tool · ${m.toolName}${status}** ${capped}`.trim();
+    return line;
+  }
+
+  /** Render a chronological list of message entries as markdown blocks. */
+  function renderEntries(entries: SessionMessageEntry[]): string {
+    const blocks: string[] = [];
+    for (const e of entries) {
+      const m = e.message;
+      const t = clock(e.timestamp);
+      if (m.role === "user") {
+        blocks.push(`## User · ${t}\n\n${userText(m.content)}`);
+      } else if (m.role === "assistant") {
+        blocks.push(renderAssistant(m, t));
+      } else if (m.role === "toolResult") {
+        blocks.push(renderToolResult(m));
+      }
+      // Other roles (custom, bashExecution, branchSummary, compactionSummary)
+      // are not part of the rendered conversation record.
+    }
+    return blocks.join("\n\n");
+  }
+
+  // ---------- frontmatter ----------
+
+  function yamlQuote(s: string): string {
+    const safe = s.replace(/[\r\n]+/g, " ");
+    return `"${safe.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+  }
+
+  function frontmatter(meta: BranchMeta): string {
+    const lines: string[] = ["---"];
+    lines.push(`title: ${yamlQuote(meta.title)}`);
+    if (meta.sessionId) lines.push(`session_id: ${yamlQuote(meta.sessionId)}`);
+    lines.push(`tree: ${yamlQuote(meta.tree)}`);
+    if (meta.model) lines.push(`model: ${yamlQuote(meta.model)}`);
+    if (meta.provider) lines.push(`provider: ${yamlQuote(meta.provider)}`);
+    lines.push(`cost: ${meta.cost.toFixed(6)}`);
+    lines.push(`tokens: ${meta.tokensInput + meta.tokensOutput}`);
+    lines.push(`tokens_input: ${meta.tokensInput}`);
+    lines.push(`tokens_output: ${meta.tokensOutput}`);
+    lines.push(`messages: ${meta.messages}`);
+    lines.push(`created: ${yamlQuote(meta.created)}`);
+    lines.push(`updated: ${yamlQuote(meta.updated)}`);
+    lines.push(`cwd: ${yamlQuote(meta.cwd)}`);
+    if (meta.sessionFile) lines.push(`session_file: ${yamlQuote(meta.sessionFile)}`);
+    lines.push("---");
+    return lines.join("\n");
+  }
+
+  /** Recover the original creation timestamp from an existing frontmatter block. */
+  function parseCreated(content: string): string | undefined {
+    const m = content.match(/^created: "(.*)"$/m);
+    if (!m) return undefined;
+    const iso = m[1].replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+    return Number.isNaN(Date.parse(iso)) ? undefined : iso;
+  }
+
+  function computeMeta(
+    ctx: ExtensionContext,
+    pathMessages: SessionMessageEntry[],
+    branchKey: string,
+    created: string | undefined,
+  ): BranchMeta {
+    let model: string | null = null;
+    let provider: string | null = null;
+    let cost = 0;
+    let tokensInput = 0;
+    let tokensOutput = 0;
+    for (const e of pathMessages) {
+      const m = e.message;
+      if (m.role === "assistant") {
+        model = m.model;
+        provider = m.provider;
+        cost += m.usage?.cost?.total ?? 0;
+        tokensInput += m.usage?.input ?? 0;
+        tokensOutput += m.usage?.output ?? 0;
+      } else if (m.role === "toolResult" && m.usage) {
+        cost += m.usage.cost?.total ?? 0;
+        tokensInput += m.usage.input ?? 0;
+        tokensOutput += m.usage.output ?? 0;
+      }
+    }
+    const now = new Date().toISOString();
+    return {
+      title: displayTitle(ctx, firstUserText(pathMessages)),
+      sessionId: ctx.sessionManager.getSessionId(),
+      sessionFile: ctx.sessionManager.getSessionFile() ?? null,
+      tree: branchKey,
+      model,
+      provider,
+      cost,
+      tokensInput,
+      tokensOutput,
+      messages: pathMessages.length,
+      created: created ?? now,
+      updated: now,
+      cwd: ctx.cwd,
+    };
+  }
+
+  // ---------- save planning ----------
+
+  interface SavePlan {
+    dir: string;
+    filename: string;
+    branchKey: string;
+    /** Write the full branch content (new branch, or target file missing). */
+    fullCreate: boolean;
+    /** Entries to append when continuing an existing file. */
+    appendEntries: SessionMessageEntry[];
+    /** Full root→leaf message list of the current branch (for meta/full renders). */
+    pathMessages: SessionMessageEntry[];
+    /** State of the file being continued, when not a full create. */
+    state: SaveState | null;
+  }
+
+  function isMessageEntry(e: SessionEntry): e is SessionMessageEntry {
+    return e.type === "message";
+  }
+
+  /**
+   * Decide which file the current branch belongs to and what to write.
+   *
+   * Every save appends a custom entry recording {branchKey, lastSavedEntryId,
+   * file}. Those entries live in the session tree, so a branch's own latest
+   * state is always recoverable — including after resume, /tree navigation,
+   * or /fork. The file to continue is the one whose most recent saved position
+   * is the deepest entry still on the current root→leaf path; when the tree
+   * moved (navigation + re-ask), no position matches and a new file starts.
+   */
+  function computePlan(ctx: ExtensionContext): SavePlan | null {
+    const pathEntries = ctx.sessionManager.getBranch();
+    const pathMessages = pathEntries.filter(isMessageEntry);
+    if (pathMessages.length === 0) return null;
+
+    const pos = new Map<string, number>();
+    pathEntries.forEach((e, i) => pos.set(e.id, i));
+
+    const latestForFile = new Map<string, SaveState>();
+    for (const e of ctx.sessionManager.getEntries()) {
+      if (e.type === "custom" && e.customType === CUSTOM_TYPE && isSaveState(e.data)) {
+        latestForFile.set(e.data.file, e.data);
+      }
+    }
+
+    let bestState: SaveState | null = null;
+    let bestPos = -1;
+    for (const st of latestForFile.values()) {
+      if (!st.lastSavedEntryId) continue;
+      const p = pos.get(st.lastSavedEntryId);
+      if (p === undefined) continue;
+      if (p > bestPos) {
+        bestPos = p;
+        bestState = st;
+      }
+    }
+
+    const dir = targetDir(ctx);
+    if (bestState) {
+      const appendEntries = pathMessages.filter((e) => (pos.get(e.id) ?? -1) > bestPos);
+      debug(
+        "continuing branch file:",
+        bestState.file,
+        "saved-up-to:",
+        bestState.lastSavedEntryId,
+        "new entries:",
+        appendEntries.length,
+      );
+      return {
+        dir,
+        filename: bestState.file,
+        branchKey: bestState.branchKey,
+        fullCreate: false,
+        appendEntries,
+        pathMessages,
+        state: bestState,
+      };
+    }
+
+    const branchKey = pathMessages[pathMessages.length - 1].id;
+    const title = titleForFilename(ctx, firstUserText(pathMessages));
+    const filename = `${title}-${branchKey}-${fileTimestamp(new Date())}.md`;
+    debug("new branch file:", filename, "branchKey:", branchKey);
+    return {
+      dir,
+      filename,
+      branchKey,
+      fullCreate: true,
+      appendEntries: [],
+      pathMessages,
+      state: null,
+    };
+  }
+
+  // ---------- writing ----------
+
+  async function atomicWrite(file: string, content: string): Promise<void> {
+    const tmp = file + ".save-tmp";
+    await fs.writeFile(tmp, content, "utf-8");
+    await fs.rename(tmp, file);
+  }
+
+  function replaceFrontmatter(existing: string, fm: string): string {
+    if (/^---\r?\n[\s\S]*?\r?\n---\r?\n/.test(existing)) {
+      return existing.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, fm + "\n");
+    }
+    return `${fm}\n\n${existing}`;
+  }
+
+  async function saveConversation(ctx: ExtensionContext, plan: SavePlan): Promise<SaveResult> {
+    const filePath = path.join(plan.dir, plan.filename);
+    let fullCreate = plan.fullCreate;
+    if (!fullCreate) {
+      const exists = await fs
+        .access(filePath)
+        .then(() => true)
+        .catch(() => false);
+      if (!exists) {
+        debug("target file missing — recreating from full branch:", filePath);
+        fullCreate = true;
+      }
+    }
+
+    await fs.mkdir(plan.dir, { recursive: true });
+
+    if (fullCreate) {
+      const meta = computeMeta(ctx, plan.pathMessages, plan.branchKey, undefined);
+      const body = renderEntries(plan.pathMessages);
+      const content = `${frontmatter(meta)}\n\n# ${meta.title}\n\n${body}\n`;
+      await atomicWrite(filePath, content);
+      debug("created conversation file:", filePath);
+      return {
+        message: `saved ${plan.filename} (${plan.pathMessages.length} messages)`,
+        wrote: true,
+        created: true,
+        file: filePath,
+      };
+    }
+
+    if (plan.appendEntries.length === 0) {
+      debug("nothing new since last save:", plan.filename);
+      return {
+        message: `already up to date (${plan.filename})`,
+        wrote: false,
+        created: false,
+        file: filePath,
+      };
+    }
+
+    const existing = await fs.readFile(filePath, "utf-8");
+    const meta = computeMeta(ctx, plan.pathMessages, plan.branchKey, parseCreated(existing));
+    const appended = renderEntries(plan.appendEntries);
+    let updated = replaceFrontmatter(existing, frontmatter(meta));
+    if (!updated.endsWith("\n")) updated += "\n";
+    updated += `\n${appended}\n`;
+    await atomicWrite(filePath, updated);
+    debug("appended", plan.appendEntries.length, "entries to:", filePath);
+    return {
+      message: `appended ${plan.appendEntries.length} messages to ${plan.filename}`,
+      wrote: true,
+      created: false,
+      file: filePath,
+    };
+  }
+
+  function recordState(plan: SavePlan, leafId: string | null): void {
+    pi.appendEntry(CUSTOM_TYPE, {
+      branchKey: plan.branchKey,
+      lastSavedEntryId: leafId,
+      file: plan.filename,
+    });
+  }
+
+  function relativeForUser(ctx: ExtensionContext, file: string): string {
+    const rel = path.relative(ctx.cwd, file);
+    return rel && !rel.startsWith("..") ? rel : file;
+  }
+
+  // Serialize saves: agent_settled and the manual command must not interleave.
+  let chain: Promise<unknown> = Promise.resolve();
+  function schedule<T>(fn: () => Promise<T>): Promise<T> {
+    const run = chain.then(fn, fn);
+    chain = run.then(
+      () => undefined,
+      () => undefined,
+    );
+    return run;
+  }
+
+  /** Full save cycle: write the file, then persist the branch state entry. */
+  async function runSave(ctx: ExtensionContext): Promise<SaveResult> {
+    const plan = computePlan(ctx);
+    if (!plan) {
+      return {
+        message: "no conversation content to save yet",
+        wrote: false,
+        created: false,
+        file: null,
+      };
+    }
+    const result = await saveConversation(ctx, plan);
+    if (result.wrote) {
+      const leafId = ctx.sessionManager.getLeafId();
+      recordState(plan, leafId);
+      debug("recorded state entry — branchKey:", plan.branchKey, "leaf:", leafId);
+    }
+    return result;
+  }
+
+  // 1. Automatic: save after every settled agent turn.
+  pi.on("agent_settled", async (_event: AgentSettledEvent, ctx: ExtensionContext) => {
+    debug("agent_settled — saving conversation");
+    try {
+      const r = await schedule(() => runSave(ctx));
+      if (r.wrote && r.created && ctx.hasUI && r.file) {
+        ctx.ui.notify(`${NOTIFY_TAG} ${relativeForUser(ctx, r.file)}`, "info");
+      }
+    } catch (e) {
+      debug("auto-save failed:", String(e));
+      if (ctx.hasUI) ctx.ui.notify(`${NOTIFY_TAG} save failed: ${String(e)}`, "error");
+    }
+  });
+
+  // 2. Manual: force a save now and report where it went.
+  pi.registerCommand(COMMAND, {
+    description:
+      "Save the current conversation branch to a markdown file now (auto-save-to-markdown)",
+    handler: async (_args: string, ctx: ExtensionCommandContext) => {
+      try {
+        debug("manual /" + COMMAND + " invoked");
+        const r = await schedule(() => runSave(ctx));
+        if (ctx.hasUI) {
+          const target = r.file ? relativeForUser(ctx, r.file) : "";
+          ctx.ui.notify(`${NOTIFY_TAG} ${r.message}${target ? ` → ${target}` : ""}`, "info");
+        }
+      } catch (e) {
+        debug("/" + COMMAND + " failed:", String(e));
+        if (ctx.hasUI) ctx.ui.notify(`${NOTIFY_TAG} save failed: ${String(e)}`, "error");
+      }
+    },
+  });
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@pi-claudian/auto-save-to-markdown",
+  "version": "0.1.0",
+  "description": "Pi extension that automatically saves each completed conversation turn as a markdown file with YAML frontmatter, one file per session-tree branch.",
+  "type": "module",
+  "license": "MIT",
+  "author": {
+    "name": "Licong Yang",
+    "email": "licong.yang@icloud.com",
+    "url": "https://github.com/licongy"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/licongy/pi-claudian.git",
+    "directory": "packages/auto-save-to-markdown"
+  },
+  "homepage": "https://github.com/licongy/pi-claudian/tree/master/packages/auto-save-to-markdown#readme",
+  "bugs": {
+    "url": "https://github.com/licongy/pi-claudian/issues"
+  },
+  "keywords": [
+    "pi",
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "pi-claudian",
+    "markdown",
+    "conversation",
+    "session",
+    "export",
+    "auto-save",
+    "archive"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "files": [
+    "index.ts",
+    "debug.ts",
+    "README.md",
+    "README.zh.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.82.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.82.1",
+    "@types/node": "^22.10.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  }
+}