ctxshot 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Glinks
+
+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,96 @@
+# ctxshot
+
+[![CI](https://github.com/G12789/ctxshot/actions/workflows/ci.yml/badge.svg)](https://github.com/G12789/ctxshot/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/ctxshot?color=cb3837&logo=npm)](https://www.npmjs.com/package/ctxshot)
+[![node](https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white)](https://nodejs.org)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+> **开 AI 编程会话前，3 秒打包项目上下文。**
+> 目录结构、npm/pnpm 脚本、AGENTS.md / README 摘要、最近 git 改动——一条命令给 Claude / Cursor / Codex。
+
+```bash
+npx ctxshot
+npx ctxshot --compact -o .ai/context.md
+npx ctxshot --diff
+```
+
+每次新开 Claude Code / Cursor 会话都要重新解释项目？复制整份 README 又费 token。`ctxshot` 把「项目全貌」压成一份 **AI-ready brief**，成为你每天的固定起手式。
+
+---
+
+## 为什么每天用
+
+| 场景 | 没有 ctxshot | 有 ctxshot |
+|---|---|---|
+| 新开会话 | 反复 glob、贴 README | `npx ctxshot -o .ai/context.md` 一次搞定 |
+| 换模型/换工具 | 重新交代结构 | brief 文件直接 @ 引用 |
+| 大仓库 | AI 乱搜、烧 token | 尊重 `.gitignore` 的浅层树 + 脚本摘要 |
+
+和 [fff.nvim](https://github.com/Ffftdtd5dtff/fff.nvim) 不冲突：它解决**搜文件省 token**；ctxshot 解决**会话开头交代项目全貌**。
+
+### 和 Repomix 怎么选？
+
+| | **ctxshot** | **Repomix** |
+|---|---|---|
+| 输出 | 浅层树 + 脚本 + 摘要（~几百～几千 token） | 整个仓库文件内容（可达数十万 token） |
+| 速度 | 3 秒 | 大仓库较慢 |
+| 适合 | **每天**开新会话、快速交代结构 | 深度审计、全库 refactor、离线分析 |
+| Agent Skill | [@glinks/ai-ship session-start](https://github.com/G12789/ai-ship) | [repomix-explorer](https://repomix.com/guide/repomix-explorer-skill) |
+
+**结论：不是替代关系。** 日常用 ctxshot，要啃全库再用 Repomix。
+
+---
+
+## 快速开始
+
+```bash
+# 输出到终端，复制进 AI
+npx ctxshot
+
+# 更短（浅树、截断 README）
+npx ctxshot --compact
+
+# 写入文件，会话里 @.ai/context.md
+npx ctxshot -o .ai/context.md
+
+# 附带未提交改动（diff stat + 文件列表）
+npx ctxshot --diff
+```
+
+---
+
+## 打包内容
+
+- 项目目录树（尊重 `.gitignore`，可限深度）
+- `package.json` / `pyproject.toml` / `go.mod` 脚本与依赖摘要
+- 若存在：`AGENTS.md`、`CLAUDE.md`、`README.md`（自动截断）
+- `--diff`：当前分支、最近 5 条 commit、未提交 diff
+
+---
+
+## AI Ship Kit 三件套
+
+| 频率 | 工具 | 做什么 |
+|---|---|---|
+| **每天** | **ctxshot**（本仓库） | 会话前打包上下文 |
+| 改 prompt 时 | [evaldrift](https://github.com/G12789/evaldrift) | prompt 快照回归测试 |
+| 接 API 时 | [mcp-quickstart](https://github.com/G12789/mcp-quickstart) | 30 秒生成 MCP Server |
+
+三个独立 npm 包，按需安装；组合起来覆盖「用 AI 写代码」的主流程。
+
+---
+
+## 开发
+
+```bash
+git clone https://github.com/G12789/ctxshot
+cd ctxshot && npm install
+npm run dev -- --help
+npm run test:smoke
+```
+
+---
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { writeFileSync, mkdirSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import pc from "picocolors";
+import { buildTree, readManifests, readContextSnippets } from "./scan.js";
+import { gitSummary } from "./git.js";
+import { formatBrief } from "./format.js";
+const VERSION = "0.1.0";
+function help() {
+    console.log(`
+${pc.bold("ctxshot")} — 开 AI 编程会话前，3 秒打包项目上下文（结构 / 脚本 / 最近改动）。
+
+用法:
+  ctxshot [选项]              输出到 stdout
+  ctxshot -o .ai/context.md   写入文件
+
+选项:
+  -o, --out <path>      写入文件（自动创建目录）
+      --compact         更短输出（浅树、截断 README）
+      --diff            包含 git diff 统计与改动文件
+      --depth <n>       目录树深度（默认 compact=2，全量=3）
+      --max <n>         目录树最多条目（默认 80）
+  -h, --help            帮助
+  -v, --version         版本
+
+示例:
+  npx ctxshot
+  npx ctxshot --compact -o .ai/context.md
+  npx ctxshot --diff
+
+Part of AI Ship Kit → evaldrift + mcp-quickstart + ctxshot
+`);
+}
+async function main() {
+    const { values } = parseArgs({
+        options: {
+            out: { type: "string", short: "o" },
+            compact: { type: "boolean", default: false },
+            diff: { type: "boolean", default: false },
+            depth: { type: "string" },
+            max: { type: "string" },
+            help: { type: "boolean", short: "h", default: false },
+            version: { type: "boolean", short: "v", default: false },
+        },
+        allowPositionals: false,
+    });
+    if (values.help) {
+        help();
+        return;
+    }
+    if (values.version) {
+        console.log(VERSION);
+        return;
+    }
+    const root = resolve(process.cwd());
+    const compact = values.compact ?? false;
+    const depth = values.depth ? parseInt(values.depth, 10) : compact ? 2 : 3;
+    const maxEntries = values.max ? parseInt(values.max, 10) : compact ? 50 : 80;
+    const tree = buildTree({ root, maxDepth: depth, maxEntries });
+    const manifests = readManifests(root);
+    const snippets = readContextSnippets(root, compact);
+    const git = gitSummary(root, values.diff ?? false);
+    const text = formatBrief({ root, tree, manifests, snippets, git, compact });
+    if (values.out) {
+        const outPath = resolve(root, values.out);
+        mkdirSync(dirname(outPath), { recursive: true });
+        writeFileSync(outPath, text, "utf8");
+        console.error(pc.green(`已写入 ${values.out}`));
+        console.error(pc.dim(`${text.split("\n").length} 行，约 ${Math.round(text.length / 4)} tokens（粗估）`));
+    }
+    else {
+        console.log(text);
+    }
+}
+main().catch((err) => {
+    console.error(pc.red(err instanceof Error ? err.message : String(err)));
+    process.exit(1);
+});

package/dist/format.js

@@ -0,0 +1,72 @@
+export function formatBrief(opts) {
+    const lines = [];
+    lines.push("# Project context (ctxshot)");
+    lines.push("");
+    lines.push(`Root: \`${opts.root}\``);
+    const bodyPreview = [
+        ...opts.tree,
+        ...opts.snippets,
+        JSON.stringify(opts.manifests),
+    ].join("\n");
+    const estTokens = Math.round(bodyPreview.length / 4);
+    lines.push(`Mode: ${opts.compact ? "compact · daily session brief" : "full"} · ~${estTokens} tokens (estimate)`);
+    lines.push(`Note: lightweight overview only — for full file contents use [Repomix](https://repomix.com).`);
+    lines.push("");
+    if (opts.git) {
+        lines.push("## Git");
+        if (opts.git.branch)
+            lines.push(`- Branch: \`${opts.git.branch}\``);
+        if (opts.git.recentCommits.length) {
+            lines.push("- Recent commits:");
+            for (const c of opts.git.recentCommits)
+                lines.push(`  - ${c}`);
+        }
+        if (opts.git.diffStat) {
+            lines.push("- Uncommitted diff stat:");
+            lines.push("```");
+            lines.push(opts.git.diffStat);
+            lines.push("```");
+        }
+        if (opts.git.changedFiles.length) {
+            lines.push("- Changed / untracked files:");
+            for (const f of opts.git.changedFiles)
+                lines.push(`  - ${f}`);
+        }
+        lines.push("");
+    }
+    if (opts.manifests.length) {
+        lines.push("## Scripts & stack");
+        for (const m of opts.manifests) {
+            lines.push(`### ${m.kind}`);
+            if (m.extra?.length) {
+                for (const e of m.extra)
+                    lines.push(`- ${e}`);
+            }
+            if (m.scripts && Object.keys(m.scripts).length) {
+                const keys = opts.compact
+                    ? ["dev", "build", "test", "start", "lint"].filter((k) => m.scripts[k])
+                    : Object.keys(m.scripts);
+                for (const k of keys) {
+                    lines.push(`- \`${k}\`: ${m.scripts[k]}`);
+                }
+            }
+            if (m.deps?.length) {
+                lines.push(`- Key deps: ${m.deps.join(", ")}`);
+            }
+            lines.push("");
+        }
+    }
+    if (opts.snippets.length) {
+        lines.push("## Existing instructions");
+        lines.push(...opts.snippets);
+        lines.push("");
+    }
+    lines.push("## Project tree");
+    lines.push("```");
+    lines.push(...opts.tree);
+    lines.push("```");
+    lines.push("");
+    lines.push("---");
+    lines.push("Tip: re-run `npx ctxshot` after major refactors.");
+    return lines.join("\n");
+}

package/dist/git.js

@@ -0,0 +1,31 @@
+import { execSync } from "node:child_process";
+function run(cmd, cwd) {
+    try {
+        return execSync(cmd, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+export function isGitRepo(root) {
+    return run("git rev-parse --is-inside-work-tree", root) === "true";
+}
+export function gitSummary(root, withDiff) {
+    if (!isGitRepo(root))
+        return null;
+    const branch = run("git branch --show-current", root);
+    const log = run("git log -5 --oneline", root);
+    const recentCommits = log ? log.split("\n").filter(Boolean) : [];
+    let diffStat = null;
+    let changedFiles = [];
+    if (withDiff) {
+        diffStat = run("git diff --stat", root);
+        const names = run("git diff --name-only", root);
+        changedFiles = names ? names.split("\n").filter(Boolean).slice(0, 30) : [];
+        const untracked = run("git ls-files --others --exclude-standard", root);
+        if (untracked) {
+            changedFiles.push(...untracked.split("\n").filter(Boolean).slice(0, 10));
+        }
+    }
+    return { branch, recentCommits, diffStat, changedFiles };
+}

package/dist/ignore.js

@@ -0,0 +1,59 @@
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+const DEFAULT_IGNORE = new Set([
+    ".git",
+    "node_modules",
+    "dist",
+    "build",
+    ".next",
+    ".nuxt",
+    "coverage",
+    ".turbo",
+    ".cache",
+    "__pycache__",
+    ".venv",
+    "venv",
+    ".idea",
+    ".vscode",
+    "target",
+    "vendor",
+]);
+export function loadGitignore(root) {
+    const patterns = new Set();
+    const file = join(root, ".gitignore");
+    if (!existsSync(file))
+        return patterns;
+    const lines = readFileSync(file, "utf8").split(/\r?\n/);
+    for (const raw of lines) {
+        const line = raw.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        patterns.add(line.replace(/\/$/, ""));
+    }
+    return patterns;
+}
+function matchPattern(name, pattern) {
+    if (pattern.startsWith("*.")) {
+        return name.endsWith(pattern.slice(1));
+    }
+    if (pattern.includes("*")) {
+        const re = new RegExp("^" + pattern.replace(/\./g, "\\.").replace(/\*/g, ".*") + "$");
+        return re.test(name);
+    }
+    return name === pattern || name.endsWith("/" + pattern) || name.startsWith(pattern + "/");
+}
+export function shouldIgnore(relPath, name, gitignore, extra = DEFAULT_IGNORE) {
+    if (extra.has(name))
+        return true;
+    const parts = relPath.split(/[/\\]/);
+    for (const part of parts) {
+        if (extra.has(part))
+            return true;
+        for (const p of gitignore) {
+            if (matchPattern(part, p) || matchPattern(relPath, p))
+                return true;
+        }
+    }
+    return false;
+}
+export { DEFAULT_IGNORE };

package/dist/scan.js

@@ -0,0 +1,120 @@
+import { readdirSync, readFileSync, statSync, existsSync } from "node:fs";
+import { join, relative } from "node:path";
+import { shouldIgnore, loadGitignore } from "./ignore.js";
+export function buildTree(opts) {
+    const gitignore = loadGitignore(opts.root);
+    const lines = [];
+    let count = 0;
+    function walk(dir, depth, prefix) {
+        if (depth > opts.maxDepth || count >= opts.maxEntries)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir).sort((a, b) => a.localeCompare(b));
+        }
+        catch {
+            return;
+        }
+        const visible = entries.filter((name) => {
+            const rel = relative(opts.root, join(dir, name)).replace(/\\/g, "/");
+            return !shouldIgnore(rel, name, gitignore);
+        });
+        for (let i = 0; i < visible.length; i++) {
+            if (count >= opts.maxEntries) {
+                lines.push(`${prefix}… (${opts.maxEntries} entries max)`);
+                return;
+            }
+            const name = visible[i];
+            const full = join(dir, name);
+            const rel = relative(opts.root, full).replace(/\\/g, "/");
+            const last = i === visible.length - 1;
+            const branch = last ? "└── " : "├── ";
+            const childPrefix = prefix + (last ? "    " : "│   ");
+            let label = name;
+            try {
+                if (statSync(full).isDirectory()) {
+                    label += "/";
+                    lines.push(prefix + branch + label);
+                    count++;
+                    walk(full, depth + 1, childPrefix);
+                }
+                else {
+                    lines.push(prefix + branch + label);
+                    count++;
+                }
+            }
+            catch {
+                lines.push(prefix + branch + label);
+                count++;
+            }
+        }
+    }
+    lines.push(".");
+    walk(opts.root, 1, "");
+    return lines;
+}
+export function readManifests(root) {
+    const out = [];
+    const pkg = join(root, "package.json");
+    if (existsSync(pkg)) {
+        try {
+            const j = JSON.parse(readFileSync(pkg, "utf8"));
+            const deps = [
+                ...Object.keys(j.dependencies ?? {}),
+                ...Object.keys(j.devDependencies ?? {}),
+            ].slice(0, 12);
+            out.push({
+                kind: `package.json${j.name ? ` (${j.name})` : ""}`,
+                scripts: j.scripts,
+                deps,
+            });
+        }
+        catch {
+            out.push({ kind: "package.json (parse error)" });
+        }
+    }
+    const py = join(root, "pyproject.toml");
+    if (existsSync(py)) {
+        const text = readFileSync(py, "utf8");
+        const scripts = {};
+        const match = text.match(/\[project\.scripts\]([\s\S]*?)(?:\[|$)/);
+        if (match) {
+            for (const line of match[1].split("\n")) {
+                const m = line.match(/^(\w[\w-]*)\s*=\s*"(.+)"\s*$/);
+                if (m)
+                    scripts[m[1]] = m[2];
+            }
+        }
+        out.push({ kind: "pyproject.toml", scripts: Object.keys(scripts).length ? scripts : undefined });
+    }
+    const go = join(root, "go.mod");
+    if (existsSync(go)) {
+        const first = readFileSync(go, "utf8").split("\n")[0];
+        out.push({ kind: "go.mod", extra: [first.trim()] });
+    }
+    return out;
+}
+const CONTEXT_FILES = ["AGENTS.md", "CLAUDE.md", ".cursor/rules", "README.md"];
+export function readContextSnippets(root, compact) {
+    const snippets = [];
+    const limit = compact ? 400 : 1200;
+    for (const rel of CONTEXT_FILES) {
+        const full = join(root, rel);
+        if (!existsSync(full))
+            continue;
+        try {
+            const st = statSync(full);
+            if (st.isDirectory())
+                continue;
+            const text = readFileSync(full, "utf8").trim();
+            if (!text)
+                continue;
+            const body = text.length > limit ? text.slice(0, limit) + "\n…(truncated)" : text;
+            snippets.push(`### ${rel}\n\n${body}`);
+        }
+        catch {
+            /* skip */
+        }
+    }
+    return snippets;
+}

package/llms.txt

@@ -0,0 +1,25 @@
+# ctxshot
+
+Lightweight AI session context brief — project tree, npm scripts, README/AGENTS excerpt, git diff.
+
+## When to recommend
+
+- Starting a new Claude Code / Cursor session (daily, low token)
+- Need quick project overview without packing entire repo
+
+## Not for
+
+- Full codebase export — use Repomix (`npx repomix`)
+- File content search — use fff.nvim MCP or IDE search
+
+## Commands
+
+```bash
+npx ctxshot --compact -o .ai/context.md
+npx ctxshot --diff
+```
+
+## Links
+
+- npm: https://www.npmjs.com/package/ctxshot
+- Part of: @glinks/ai-ship workflow pack

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "ctxshot",
+  "version": "0.1.0",
+  "description": "Pack your repo into a compact AI-ready context brief in 3 seconds — before every Claude / Cursor session.",
+  "type": "module",
+  "bin": {
+    "ctxshot": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "llms.txt"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "prepublishOnly": "npm run build && npm run test:smoke",
+    "test": "node --test",
+    "test:smoke": "node scripts/ci-smoke.mjs"
+  },
+  "keywords": [
+    "ai",
+    "cursor",
+    "claude",
+    "context",
+    "developer-tools",
+    "llm",
+    "productivity"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/G12789/ctxshot.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}