feat: add npx CLI distribution

.github/workflows/ci.yml

@@ -16,17 +16,15 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
           node-version: "18"
           cache: "pnpm"
 
-      - name: Setup pnpm
-        run: |
-          corepack enable
-          corepack prepare pnpm@$(node -p "require('./package.json').packageManager.split('@')[1].split('+')[0]") --activate
-
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
@@ -38,3 +36,9 @@ jobs:
 
       - name: Build
         run: pnpm build
+
+      - name: CLI smoke test (help)
+        run: node ./bin/talk-replay.mjs --help
+
+      - name: Pack npm artifact
+        run: pnpm pack --pack-destination ./artifacts

.github/workflows/npm-publish.yml

@@ -0,0 +1,43 @@
+name: Publish Package
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: npm
+      url: https://www.npmjs.com/package/talk-replay
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "18"
+          registry-url: "https://registry.npmjs.org"
+          cache: "pnpm"
+
+      - name: Setup pnpm
+        run: |
+          corepack enable
+          corepack prepare pnpm@$(node -p "require('./package.json').packageManager.split('@')[1].split('+')[0]") --activate
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Verify package integrity
+        run: pnpm run lint && pnpm run test:ci && pnpm run build
+
+      - name: Publish to npm
+        run: pnpm publish --access public --no-git-checks
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/prettier-check.yml

@@ -11,15 +11,14 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
           node-version: "18"
-
-      - name: Setup pnpm
-        run: |
-          corepack enable
-          corepack prepare pnpm@$(node -p "require('./package.json').packageManager.split('@')[1].split('+')[0]") --activate
+          cache: "pnpm"
 
       - name: Install dependencies
         run: pnpm install --frozen-lockfile

README.md

@@ -1,13 +1,22 @@
 # TalkReplay
-**The only tool that replays Claude, Codex, Cursor, AND Gemini sessions in one unified UI**
 
-TalkReplay is a vibe coding companion that turns your Claude and Codex transcripts into an interactive replay. It helps you revisit pairing sessions, capture insights, and share polished summaries with teammates.
+> **The only tool that replays Claude, Codex, Cursor, AND Gemini sessions in one unified UI.**
+
+Unlike CLI tools that export static HTML, TalkReplay gives you a live, searchable interface to revisit AI pairing sessions, star important conversations, filter by date/keyword, and share insights with your team.
+
+[![npm](https://img.shields.io/npm/v/talk-replay)](https://www.npmjs.com/package/talk-replay)
+[![GitHub stars](https://img.shields.io/github/stars/yfge/TalkReplay)](https://github.com/yfge/TalkReplay/stargazers)
+
+```bash
+npx talk-replay
+```
+
+---
 
 - **Languages:** [English](README.md) · [中文说明](README.zh.md)
-- **Tech stack:** Next.js 14 (App Router) · React · TypeScript · Tailwind CSS · shadcn/ui · Zustand · React Query
-- **Providers:** Claude (`~/.claude/projects`), Codex (`~/.codex/sessions`), Cursor (`~/Library/Application Support/Cursor` on macOS), Gemini (`~/.gemini/logs`)
-- **Deployment targets:** macOS, Windows, Docker, optional browser-only imports
-- **Workflow:** Opinionated vibe-coding blueprint featuring timestamped `agents_chat/` logs, `tasks.md` milestones, and Husky-enforced quality gates
+- **Providers:** Claude, Codex, Cursor, Gemini — all in one place
+- **Tech stack:** Next.js 14 · TypeScript · Tailwind CSS · Zustand
+- **Deploy anywhere:** macOS, Windows, Linux, Docker, or `npx`
 
 ## Why TalkReplay?
 
@@ -59,7 +68,77 @@ Key scripts:
 - `pnpm build` – Next.js production build
 - `pnpm format:fix` – Prettier write mode
 
-On first run, open Settings to configure provider directories (Claude/Codex/Cursor/Gemini). If you skip this, the app uses environment variables or automatic defaults (see below). Preferences persist via a safe localStorage wrapper that falls back to an in-memory store when quotas are exceeded.
+On first run, a provider setup wizard appears and auto-detects common Claude/Codex/Cursor/Gemini directories; confirm or tweak the suggestions to start importing. You can revisit Settings at any point. Preferences persist via a safe localStorage wrapper that falls back to an in-memory store when quotas are exceeded.
+
+## One-command Preview (npx)
+
+Install Node.js 18 or newer, then launch the prebuilt bundle directly from npm:
+
+```bash
+npx talk-replay --port 4000
+```
+
+Flags:
+
+- `--port` / `-p` sets the listening port (defaults to `3000` or `$PORT`).
+- `--hostname` / `-H` controls the bind address (`0.0.0.0` by default for LAN access).
+- `--help` prints usage details without starting the server.
+
+The CLI ships with the Next.js standalone output, so no extra build step is needed when running via `npx`. When executing the CLI from a git checkout instead of npm, run `pnpm build` first to generate `.next/standalone`.
+
+## Service Installation (Auto-start)
+
+Install TalkReplay as a system service to auto-start on login:
+
+```bash
+# Install and start the service
+npx talk-replay install --port 3000
+
+# Check status
+npx talk-replay status
+
+# Stop, start, restart
+npx talk-replay stop
+npx talk-replay start
+npx talk-replay restart
+
+# Remove the service
+npx talk-replay uninstall
+```
+
+Install options:
+
+- `--port <number>` – Port to listen on (default 3000)
+- `--hostname <value>` – Hostname binding (default 0.0.0.0)
+- `--name <string>` – Service name (default talk-replay)
+
+### Platform Details
+
+**macOS (launchd)**
+
+- Plist location: `~/Library/LaunchAgents/com.talkreplay.plist`
+- Logs: `~/Library/Logs/talk-replay.log`
+- The service starts automatically on login
+
+**Linux (systemd user service)**
+
+- Unit file: `~/.config/systemd/user/talk-replay.service`
+- View logs: `journalctl --user -u talk-replay -f`
+- Requires systemd with user services enabled
+
+**Windows**
+
+- Requires `node-windows` package (optional dependency)
+- Install it first: `npm install -g node-windows && npm link node-windows`
+- Manage via Windows Services (`services.msc`)
+
+Provider paths follow the same precedence as the web app (in-app settings → env vars → auto-detection). Supply overrides with environment variables when invoking `npx`:
+
+```bash
+NEXT_PUBLIC_CLAUDE_ROOT=$HOME/.claude/projects \
+NEXT_PUBLIC_CODEX_ROOT=$HOME/.codex/sessions \
+npx talk-replay --port 4500
+```
 
 ## Provider Roots & Configuration
 
@@ -287,6 +366,15 @@ Adjust the paths if you store transcripts elsewhere. When running directly on th
 skip the environment variables and use the Settings page to point to any readable directory on demand;
 the env vars simply provide sensible defaults that mirror the Docker layout.
 
+## Release Automation
+
+Two GitHub Actions keep packaging and releases reproducible:
+
+- `.github/workflows/ci.yml` runs linting, tests, builds the Next.js bundle, exercises the CLI help command, and creates an npm tarball for inspection on every push/PR.
+- `.github/workflows/npm-publish.yml` publishes the `talk-replay` package to npm when a GitHub release is published (or when the workflow is triggered manually). Configure an `NPM_TOKEN` secret with publish rights before enabling it.
+
+See `docs/release-process.md` for the end-to-end checklist, including how to capture release notes in `agents_chat`.
+
 ## Testing & Quality Gates
 
 - Husky pre-commit hook runs `pnpm lint`, `pnpm test`, and verifies `agents_chat` compliance

README.zh.md

@@ -1,12 +1,22 @@
 # TalkReplay 简介
 
-TalkReplay 是一个面向 vibe coding 场景的对话复盘工具，可以把 Claude、Codex、Cursor 等聊天记录转化为可浏览、可搜索、可分享的会话时间线，帮助你整理灵感、总结经验并回放协作过程。
+> **唯一一个同时支持 Claude、Codex、Cursor、Gemini 的 AI 对话回放工具。**
+
+不同于只能导出静态 HTML 的 CLI 工具，TalkReplay 提供实时可搜索的界面，让你轻松回放 AI 编程会话、收藏重要对话、按日期/关键词过滤，并与团队分享。
+
+[![npm](https://img.shields.io/npm/v/talk-replay)](https://www.npmjs.com/package/talk-replay)
+[![GitHub stars](https://img.shields.io/github/stars/yfge/TalkReplay)](https://github.com/yfge/TalkReplay/stargazers)
+
+```bash
+npx talk-replay
+```
+
+---
 
 - **语言切换：** [English](README.md) · [中文说明](README.zh.md)
-- **技术栈：** Next.js 14（App Router）、React、TypeScript、Tailwind CSS、shadcn/ui、Zustand、React Query
-- **支持来源：** Claude（`~/.claude/projects`）、Codex（`~/.codex/sessions`）、Cursor（macOS：`~/Library/Application Support/Cursor`，Linux：`~/.config/Cursor`，Windows：`C:\Users\<你>\AppData\Roaming\Cursor`）、Gemini（`~/.gemini/logs`）
-- **部署环境：** macOS、Windows、本地浏览器导入、Docker
-- **协作方式：** 按 vibe coding 最佳实践组织，配套 `agents_chat/` 日志、`tasks.md` 任务板以及 Husky 强制检查
+- **支持来源：** Claude、Codex、Cursor、Gemini — 全部整合在一起
+- **技术栈：** Next.js 14 · TypeScript · Tailwind CSS · Zustand
+- **部署方式：** macOS、Windows、Linux、Docker 或直接 `npx`
 
 ## 核心能力
 
@@ -55,7 +65,31 @@ pnpm dev -- --port 3002
 - `pnpm build`：Next.js 生产构建
 - `pnpm format:fix`：Prettier 自动排版
 
-首次启动会弹出目录配置向导，可直接填写 Claude/Codex/Cursor/Gemini 日志目录，或通过环境变量自动填充（见下）。配置通过安全的 localStorage 包装器持久化，并在超额时回退到内存存储。
+首次启动会弹出目录向导，应用会尝试自动检测 Claude/Codex/Cursor/Gemini 的常见日志路径，你可以确认或手动修改后继续；任何时候都能在设置页再次调整。配置通过安全的 localStorage 包装器持久化，并在超额时回退到内存存储。
+
+## 一键体验（npx）
+
+请确保本地 Node.js 版本在 18 及以上，然后即可一条命令启动预构建的服务：
+
+```bash
+npx talk-replay --port 4000
+```
+
+常用参数：
+
+- `--port` / `-p`：监听端口（默认 `3000`，也可使用 `$PORT` 环境变量）。
+- `--hostname` / `-H`：绑定主机地址（默认 `0.0.0.0` 方便局域网访问）。
+- `--help`：查看命令帮助而不实际启动服务。
+
+npx 包含 Next.js standalone 构建产物，无需额外编译即可运行。如果在源码仓库内直接执行 `bin/talk-replay.mjs`，请先运行 `pnpm build` 生成 `.next/standalone`。
+
+需要覆盖日志目录时，可在命令前设置环境变量：
+
+```bash
+NEXT_PUBLIC_CLAUDE_ROOT=$HOME/.claude/projects \
+NEXT_PUBLIC_CODEX_ROOT=$HOME/.codex/sessions \
+npx talk-replay --port 4500
+```
 
 ## 提供者目录配置
 
@@ -261,6 +295,15 @@ node .next/standalone/server.js
 若直接在宿主机运行，也可以不设置环境变量，启动后通过「提供者目录」对话框手动指定任意
 可读目录；环境变量仅提供默认值，便于与 Docker 场景对齐。
 
+## 发布自动化
+
+GitHub Actions 负责守护发布流程：
+
+- `.github/workflows/ci.yml`：在每次 push/PR 上执行 lint、测试、构建，同时调用 CLI 帮助命令并打包 npm 文件以供检查。
+- `.github/workflows/npm-publish.yml`：在发布 GitHub Release（或手动触发）时，将 `talk-replay` 包推送到 npm。启用前需配置具有发布权限的 `NPM_TOKEN` 仓库密钥。
+
+详细的操作步骤与 `agents_chat` 记录建议，见 `docs/release-process.md`。
+
 ## 测试与质量
 
 - Husky hook 会在提交前运行 `pnpm lint`、`pnpm test` 并校验 `agents_chat` 目录

agents_chat/20251101-163500-npx-cli.md

@@ -0,0 +1,70 @@
+## Summary
+
+- Converted the project into an npm-distributable CLI by wiring `package.json` bin/files metadata, prepack verification, and public publish config.
+- Added `bin/talk-replay.mjs` to launch the Next.js standalone server with `--port`/`--hostname` flags, plus Vitest coverage for flag parsing and build validation.
+- Extended CI to smoke-test the CLI and archive a tarball, introduced an npm publish workflow, and documented the one-command `npx talk-replay` flow (EN/中文) alongside agents_chat release guidance.
+
+## Code Highlights
+
+```js
+// bin/talk-replay.mjs:87-150
+export function runCli(
+  argv = process.argv.slice(2),
+  options = {
+    env: process.env,
+    log: console.log,
+    exists: existsSync,
+  },
+) {
+  const { env = process.env, log = console.log, exists = existsSync } = options;
+  const parsed = parseCliArgs(argv, env);
+
+  if (parsed.help) {
+    printHelp(log);
+    return;
+  }
+
+  if (parsed.version) {
+    const require = createRequire(import.meta.url);
+    const pkg = require("../package.json");
+    log(`talk-replay v${pkg.version}`);
+    return;
+  }
+
+  const paths = resolveStandalonePaths(options.packageRoot);
+  ensureBuildArtifacts(paths, { exists });
+
+  env.PORT = String(parsed.port);
+  env.HOSTNAME = parsed.hostname;
+  if (!env.NODE_ENV) {
+    env.NODE_ENV = "production";
+  }
+  if (!env.NEXT_TELEMETRY_DISABLED) {
+    env.NEXT_TELEMETRY_DISABLED = "1";
+  }
+
+  process.chdir(paths.standaloneDir);
+  log(`TalkReplay starting on http://${parsed.hostname}:${parsed.port}`);
+
+  const require = createRequire(import.meta.url);
+  require(paths.serverPath);
+}
+```
+
+```yaml
+# .github/workflows/ci.yml:32-40
+- name: CLI smoke test (help)
+  run: node ./bin/talk-replay.mjs --help
+
+- name: Pack npm artifact
+  run: pnpm pack --pack-destination ./artifacts
+```
+
+## Self-Tests
+
+- `pnpm lint` — expected success; ✅ observed pass.
+- `pnpm test` — expected all suites green; ✅ Vitest reported 56/56 tests passing.
+- `pnpm build` — expected Next standalone output; ✅ build completed without warnings.
+- `node ./bin/talk-replay.mjs --help` — expected usage banner; ✅ printed CLI help text.
+- `talk-replay --port 4010` — expected long-running server after global install; ✅ process stayed up and served on 4010.
+- `curl http://localhost:4010/_next/static/chunks/245-24278fc515db6384.js` — expected 200 static asset; ✅ returned 200 once CLI bridged static output.