gft-merge 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CoralLips
+
+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

@@ -1,3 +1,86 @@
-# Temporary Holding Version
+<p align="center"><strong>English</strong> · <a href="README_ZH.md">简体中文</a></p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# GFT-Merge
+
+## Carry context between your AI coding sessions.
+
+**Pull sessions from Claude Code and Codex into a pool, then start a new session in either tool with that context already in it.**
+
+You plan something in one Claude Code session, build it in Codex, and debug it in another session. Handing over means copying and pasting by hand. GFT-Merge reads your local sessions, lets you combine the ones that matter, and starts a fresh session whose first message carries them, so the AI picks up where you left off.
+
+It runs on your computer and opens in your browser. A sibling of [GFT-Map](https://github.com/CoralLips/gft-map).
+
+> The interface is in Chinese for now.
+
+## Get started
+
+You'll need **Node.js 22+** and at least one of:
+
+- **Claude Code** in the **Claude desktop app**, signed in. New Claude sessions are brought into the app through its own `claude://` link, so the app is required to see them.
+- **Codex**, the Codex app or CLI, signed in. With the Codex app, new sessions also open there.
+
+Then run:
+
+```sh
+npx gft-merge
+```
+
+Your browser opens `http://127.0.0.1:4319`. Run it again any time; it reuses the running service.
+
+## How it works
+
+The page has two halves. At the top, one column per tool lists your sessions from the last 30 days. Below, your pools on the left and the selected pool's workspace on the right. Everything is done by dragging.
+
+| What you want                     | How                                                                                             |
+| --------------------------------- | ----------------------------------------------------------------------------------------------- |
+| Put a session in a pool           | Drag it from a tool's column into the workspace. It becomes a ball.                             |
+| Combine sessions                  | Drop one ball on another. Any two balls can be fused.                                           |
+| Start a session with that context | Drag a ball up onto a tool's column. A new session starts there, named "merge · pool name".     |
+| Make a big ball smaller           | Click the ball to compress it with a model (see below).                                         |
+| See what a ball holds             | Hover the name under it. Drag a session out of that list to split it off.                       |
+| Move or remove                    | Drop a ball on another pool in the list to move it; drop it outside the workspace to remove it. |
+
+**The number in a ball** is its size in tokens. A single session shows that session's own context size, read from the tool's records. A fused or compressed ball shows what dragging it up would send, counted locally (marked ≈).
+
+**Compression** sends the ball's content to the tool and model chosen under **Settings → 处理工具** (processing tool) and replaces it with the result. While it runs, the ball's ring turns and its name reads "压缩中…" (compressing). A compressed ball can't be split again; you can fuse more sessions onto it or compress it again. Drag it up before compression finishes and the original text is sent.
+
+**The new session's first message** contains the plain conversation of every session in the ball (your messages and the final answer of each turn, without tool output) and asks the AI to report briefly what it understood (what the sessions are about, where things stand, what is decided and open, what comes next), then wait for you. That reply is a real turn, so the session sits at the top of the tool's list. With Codex the page returns at once and the session opens when the reply ends; with Claude the page waits for the reply (several seconds to about a minute), then the session opens in the Claude app.
+
+**Why only new sessions:** Codex refuses other programs writing to a session that is open in the Codex app, and the Claude app shows its own copy of a session, not what another program writes into it. Neither is reliable, so GFT-Merge always starts a new session.
+
+## Where does your data go?
+
+- GFT-Merge reads your local Claude Code and Codex session files. It does not change them, and it does not install hooks or change either tool's settings.
+- Pools are stored in `~/.gft-merge/` on your computer (set `GFT_MERGE_HOME` to move them).
+- A model is called only in two cases, both started by you: dragging a ball up (the new session runs in that tool, on your account) and compressing (one request to the processing tool, on your account).
+- No GFT account, no cloud.
+
+## Commands
+
+```sh
+npx gft-merge          # open the page, starting the service if needed
+npx gft-merge stop     # stop the service
+npx gft-merge status   # show whether it runs, and where the data is
+```
+
+Add `--port <number>` to use another port.
+
+## Project status and feedback
+
+Version 0.1, an early release. Tested on Windows; on macOS and Linux, opening sessions in the desktop apps is not verified yet. Supports Claude Code and Codex.
+
+Share problems or ideas in [Issues](https://github.com/CoralLips/gft-merge/issues).
+
+## Development
+
+```sh
+git clone https://github.com/CoralLips/gft-merge.git
+cd gft-merge
+npm install
+npm test
+node cli.mjs open
+```
+
+## License
+
+MIT

package/README_ZH.md

@@ -0,0 +1,84 @@
+<p align="center"><a href="README.md">English</a> · <strong>简体中文</strong></p>
+
+# GFT-Merge
+
+## 让上下文在 AI 编程会话之间流动。
+
+**把 Claude Code 和 Codex 的会话拉进一个池子，再在任一工具里开一个新会话，上下文已经带在里面。**
+
+你在一个 Claude Code 会话里定方案，在 Codex 里写代码，又在另一个会话里排查问题。每次交接都得手动复制粘贴。GFT-Merge 读取你本机的会话，让你把有用的几段合在一起，然后开一个新会话、把它们作为第一条消息带进去，AI 就能接着往下干。
+
+在你自己的电脑上运行，在浏览器里打开。和 [GFT-Map](https://github.com/CoralLips/gft-map) 是同一系列的工具。
+
+## 开始
+
+需要 **Node.js 22 以上**，以及下面至少一个：
+
+- **Claude 桌面应用里的 Claude Code**，已登录。新建的 Claude 会话要通过桌面应用自己的 `claude://` 链接导入，所以必须有桌面应用才能看到。
+- **Codex**，桌面应用或命令行都可以，已登录。装了 Codex 桌面应用的话，新会话也会在里面打开。
+
+然后运行：
+
+```sh
+npx gft-merge
+```
+
+浏览器会打开 `http://127.0.0.1:4319`。之后随时再运行一次即可，已经在跑的服务会直接复用。
+
+## 怎么用
+
+页面分上下两半。上面每个工具一栏，列出最近 30 天的会话；下面左边是池子列表，右边是选中池子的工作区。所有操作都靠拖。
+
+| 想做什么               | 怎么做                                                               |
+| ---------------------- | -------------------------------------------------------------------- |
+| 把会话放进池子         | 从上面的工具栏拖进工作区，它就成了一个球                             |
+| 合并几个会话           | 把一个球拖到另一个球上，任意两个球都能融合                           |
+| 带着这些上下文开新会话 | 把球往上拖到某个工具的栏上，就在那里新建会话，名为「merge · 池子名」 |
+| 把大球变小             | 点一下球，用模型压缩（见下文）                                       |
+| 看球里有什么           | 鼠标悬停在球下方的名字上；从列表里把某个会话拖出去就能拆开           |
+| 搬走或移出             | 把球拖到左边另一个池子上就搬过去；拖出工作区就移出池子               |
+
+**球里的数字**是 token 数。单个会话的球显示这个会话本身的上下文大小，直接读自工具的记录；融合或压缩过的球显示往上拖时要送出去的量，由本地分词器数出来，前面带 ≈。
+
+**压缩**会把球的内容发给 **设置 → 处理工具** 里选的工具和模型，用结果替换原内容。压缩中球的虚线圈会转，名字处显示“压缩中…”。压完的球不能再拆，但可以继续往上融合新的会话，也可以再压。压缩没完成时往上拖，送出去的是原文。
+
+**新会话的第一条消息**包含球里每个会话的原话（你说的话和 AI 每轮的最终回答，不含工具输出），并请 AI 先简要汇报它的理解（这些会话在做什么、进展到哪、定了什么、没定什么、下一步做什么），然后等你的指示。这一轮是真对话，所以新会话排在工具列表最上面。Codex 那边页面立刻返回，回复结束后在 Codex 里打开；Claude 那边要等回复结束（几秒到一分钟左右），然后在 Claude 桌面应用里打开。
+
+**为什么只做新建：** Codex 会话在 Codex 桌面应用里开着时，Codex 不让别的程序往里写；Claude 桌面应用显示的是它自己保存的会话内容，别的程序写进去的消息它不显示。两条路都靠不住，所以 GFT-Merge 只新建会话。
+
+## 数据去哪了
+
+- GFT-Merge 读取你本机 Claude Code 和 Codex 的会话文件，不修改它们，也不装钩子、不改两家工具的任何设置。
+- 池子存在你电脑上的 `~/.gft-merge/`（可用 `GFT_MERGE_HOME` 改位置）。
+- 只有两种情况会调用模型，都由你触发：往上拖新建会话（在那个工具里、用你的账号额度），以及压缩（向处理工具发一次请求，用你的账号额度）。
+- 不需要 GFT 账号，不上云。
+
+## 命令
+
+```sh
+npx gft-merge          # 打开页面，需要时自动启动服务
+npx gft-merge stop     # 停止服务
+npx gft-merge status   # 查看是否在运行、数据在哪
+```
+
+加 `--port <端口>` 可以换端口。
+
+## 项目状态和反馈
+
+0.1 版，早期版本。在 Windows 上实测过；macOS 和 Linux 上在桌面应用里打开会话还没验证。支持 Claude Code 和 Codex。
+
+问题和想法欢迎提在 [Issues](https://github.com/CoralLips/gft-merge/issues)。
+
+## 开发
+
+```sh
+git clone https://github.com/CoralLips/gft-merge.git
+cd gft-merge
+npm install
+npm test
+node cli.mjs open
+```
+
+## 许可
+
+MIT

package/cli.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+// gft-merge: open | serve | stop | status
+import { spawn } from 'node:child_process';
+import { connect } from 'node:net';
+import { mkdir, open as openFile, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homeDir, readJson, writeJson } from './home.mjs';
+import { DEFAULT_PORT, startServer } from './server.mjs';
+
+// The command may be left out, as in `gft-merge --port 4329`: then it is `open`.
+const args = process.argv.slice(2);
+const command = args[0] && !args[0].startsWith('--') ? args[0] : 'open';
+const portAt = args.indexOf('--port');
+const port =
+  (portAt >= 0 && Number(args[portAt + 1])) || Number(process.env.GFT_MERGE_PORT) || DEFAULT_PORT;
+const url = `http://127.0.0.1:${port}`;
+const serviceFile = path.join(homeDir(), 'service.json');
+const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+const portTaken = () =>
+  new Error(
+    `端口 ${port} 已被其他程序占用，GFT-Merge 没有启动。请换一个端口，例如：npx gft-merge --port ${port + 10}`,
+  );
+
+/** Whether anything listens on the port, without speaking HTTP to it. */
+const listening = () =>
+  new Promise(resolve => {
+    const socket = connect({ host: '127.0.0.1', port }, () => {
+      socket.destroy();
+      resolve(true);
+    });
+    socket.once('error', () => resolve(false));
+    socket.setTimeout(1500, () => {
+      socket.destroy();
+      resolve(true);
+    });
+  });
+
+/** 'ours' when GFT-Merge answers on the port, 'other' when something else holds it, else 'free'. */
+async function probe() {
+  try {
+    const response = await fetch(`${url}/api/state`, { signal: AbortSignal.timeout(1500) });
+    if (response.ok && (await response.json().catch(() => null))?.product === 'gft-merge')
+      return 'ours';
+  } catch {
+    // Not an HTTP answer from us; see whether the port is taken at all.
+  }
+  return (await listening()) ? 'other' : 'free';
+}
+const running = async () => (await probe()) === 'ours';
+
+function openBrowser() {
+  const [file, args] =
+    process.platform === 'win32'
+      ? ['cmd', ['/c', 'start', '', url]]
+      : [process.platform === 'darwin' ? 'open' : 'xdg-open', [url]];
+  spawn(file, args, { detached: true, stdio: 'ignore', windowsHide: true }).unref();
+}
+
+const commands = {
+  async serve() {
+    await startServer({ port }).catch(error => {
+      throw error.code === 'EADDRINUSE' ? portTaken() : error;
+    });
+    await writeJson(serviceFile, { pid: process.pid, port, startedAt: new Date().toISOString() });
+    console.log(`GFT-Merge: ${url}`);
+  },
+
+  async open() {
+    const state = await probe();
+    if (state === 'other') throw portTaken();
+    if (state === 'free') {
+      await mkdir(homeDir(), { recursive: true });
+      const log = await openFile(path.join(homeDir(), 'service.log'), 'a');
+      const script = fileURLToPath(import.meta.url);
+      spawn(process.execPath, [script, 'serve', '--port', String(port)], {
+        detached: true,
+        windowsHide: true,
+        stdio: ['ignore', log.fd, log.fd],
+      }).unref();
+      await log.close();
+      for (let i = 0; i < 50 && !(await running()); i++) await delay(100);
+      if (!(await running()))
+        throw new Error(`启动失败，请查看 ${path.join(homeDir(), 'service.log')}`);
+    }
+    openBrowser();
+    console.log(`GFT-Merge 已打开：${url}`);
+  },
+
+  /** Stops the process this data directory started, as recorded when it began serving. */
+  async stop() {
+    const service = await readJson(serviceFile);
+    const alive = pid => {
+      try {
+        process.kill(pid, 0);
+        return true;
+      } catch {
+        return false;
+      }
+    };
+    if (!service?.pid || !alive(service.pid)) {
+      await rm(serviceFile, { force: true });
+      return console.log('GFT-Merge 没有在运行。');
+    }
+    process.kill(service.pid);
+    await rm(serviceFile, { force: true });
+    console.log('GFT-Merge 已停止。');
+  },
+
+  async status() {
+    console.log(
+      JSON.stringify(
+        {
+          running: await running(),
+          url,
+          data: homeDir(),
+        },
+        null,
+        2,
+      ),
+    );
+  },
+};
+
+if (!commands[command]) {
+  console.error(`用法：gft-merge ${Object.keys(commands).join(' | ')} [--port 端口]`);
+  process.exit(1);
+}
+try {
+  await commands[command]();
+} catch (error) {
+  console.error(error.message);
+  process.exit(1);
+}

package/home.mjs

@@ -0,0 +1,63 @@
+// Where GFT-Merge keeps its files, and small helpers to read and write them safely.
+import { mkdir, readFile, rename, writeFile, appendFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+export const homeDir = () =>
+  path.resolve(process.env.GFT_MERGE_HOME || path.join(os.homedir(), '.gft-merge'));
+
+/** Text placed at the start of everything GFT-Merge writes into a session. */
+export const MARKER = '〔GFT-Merge〕';
+/**
+ * Closes the first message of a session a ball starts: the AI reports what it
+ * understood, so the person can check it before going on, and waits for them.
+ */
+export const BRIEF =
+  '\n\n读完以上内容后，先简要汇报你的理解（几句话即可）：这些会话在做什么、进展到哪一步、已经定下的结论、还没定的问题，以及你认为接下来该做什么。先不要执行任何操作，等我的指示。';
+/** What a processing tool is asked when a ball is compressed; the ball's content follows. */
+export const COMPRESS =
+  '把下面几段会话记录压缩成一份，供另一个 AI 接着工作：保留结论、决定、没定的问题和关键事实，去掉重复和过程，保持原文语言，标明各条来自哪个会话。只输出压缩结果。\n\n';
+
+export async function readJson(file, fallback = null) {
+  try {
+    return JSON.parse(await readFile(file, 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return fallback;
+    throw error;
+  }
+}
+
+const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+/** Writes through a temporary file. Windows briefly refuses renames while a reader holds the file. */
+export async function writeJson(file, value) {
+  await mkdir(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.${Date.now()}.tmp`;
+  await writeFile(temporary, JSON.stringify(value, null, 2));
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await rename(temporary, file);
+    } catch (error) {
+      if (!['EPERM', 'EACCES', 'EBUSY'].includes(error.code) || attempt >= 20) throw error;
+      await delay(Math.min(25 * 2 ** attempt, 250));
+    }
+  }
+}
+
+export async function appendLines(file, values) {
+  if (!values.length) return;
+  await mkdir(path.dirname(file), { recursive: true });
+  await appendFile(file, values.map(value => JSON.stringify(value)).join('\n') + '\n');
+}
+
+export async function readLines(file) {
+  try {
+    return (await readFile(file, 'utf8'))
+      .split('\n')
+      .filter(Boolean)
+      .map(line => JSON.parse(line));
+  } catch (error) {
+    if (error.code === 'ENOENT') return [];
+    throw error;
+  }
+}

package/openLink.mjs

@@ -0,0 +1,11 @@
+// Opens a link with the system's handler, the way a click would, e.g. claude://resume
+// so the Claude app shows a session another program wrote.
+import { spawn } from 'node:child_process';
+
+export function openLink(url) {
+  const [file, args] =
+    process.platform === 'win32'
+      ? ['cmd', ['/c', 'start', '', url]]
+      : [process.platform === 'darwin' ? 'open' : 'xdg-open', [url]];
+  spawn(file, args, { detached: true, stdio: 'ignore', windowsHide: true }).unref();
+}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "gft-merge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Merge AI agent sessions into pools and start a new session from a pool in any tool.",
+  "keywords": [
+    "ai",
+    "agent",
+    "claude-code",
+    "codex",
+    "session",
+    "context",
+    "merge"
+  ],
+  "homepage": "https://github.com/CoralLips/gft-merge#readme",
+  "bugs": {
+    "url": "https://github.com/CoralLips/gft-merge/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CoralLips/gft-merge.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "gft-merge": "cli.mjs"
+  },
+  "files": [
+    "cli.mjs",
+    "home.mjs",
+    "openLink.mjs",
+    "pools.mjs",
+    "server.mjs",
+    "tools/",
+    "web/",
+    "skill/",
+    "README_ZH.md"
+  ],
+  "scripts": {
+    "start": "node cli.mjs open",
+    "test": "node --test \"tests/*.test.mjs\""
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "0.3.270",
+    "gpt-tokenizer": "4.0.0"
+  }
+}