gft-merge 0.0.0-stage → 0.1.0

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,71 @@
-# 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
+
+Pull sessions from different AI coding tools into a **pool**, then start a new session in any of them from that pool. Runs locally; your data stays on your machine.
+
+Works with **Claude Code** and **Codex** today.
+
+## Get started
+
+You need Node.js 22 or newer, and Claude Code and/or Codex installed and signed in.
+
+```bash
+npx gft-merge
+```
+
+Your browser opens `http://127.0.0.1:4319`. You can also install it globally and run `gft-merge`.
+
+## How it works
+
+- **Top**: one bucket per tool, listing the last 30 days of sessions. The Claude list matches the Claude app: archived and deleted sessions are left out and names follow the app; sessions started in a terminal are marked "CLI".
+- **Bottom**: your pools on the left, the selected pool's workspace on the right.
+- **Drag down to add**: a session dropped into the workspace becomes a ball; dropped on a ball, it fuses into it.
+- **Drop a ball on a ball to fuse**: any two balls can be fused.
+- **Drag up to start a session**: drop a ball on a tool's bucket to start a new session there whose first message is the ball's content.
+- **Click a ball to compress**: one model call, using the tool and model chosen as the processor in settings. While it runs the ball's dashed ring turns and its name reads "压缩中…". The result is one piece that 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 number in a ball**: a single session shows that session's own context size, read from the tool's records; a fused or compressed ball shows how many tokens dragging it up would send, counted locally (≈).
+- **Names and contents**: the label under a ball lists its sessions, each prefixed with its tool. Hover the label to see the contents; drag a session out of that list to split it off.
+- **Move and remove**: drop a ball on another pool in the list to move it; drop it outside the workspace to remove it.
+
+## What happens when you drag up
+
+GFT-Merge starts a session in that tool (named "merge · pool name"), sends the content as its first message, 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) and then wait for you. That is a real turn, so the new session sits at the top of the tool's list. No hooks are installed, no tool settings are changed, and nothing runs inside the tools' own processing.
+
+- **Codex**: returns as soon as the message is sent; once the reply ends, the session opens in the Codex app through its own `codex://` link.
+- **Claude Code**: waits for Claude's reply (from several seconds to a minute or so, depending on length), then imports and opens the session in the Claude app through its own `claude://resume` link.
+- The new session opens in the project most of its sources came from.
+
+Why not send into an existing session: Codex refuses other programs writing to a session that is open in the Codex app, and the Claude app shows its own cached copy, not what another program writes into a session file. Neither path is reliable, so only new sessions are supported.
+
+Notes:
+
+- What is sent is the plain conversation: your messages and the final answer of each turn, without intermediate steps or tool logs. A model is called only when you compress, and that uses your quota.
+- Uncompressed content is sent in full; a long pool can fill the new session's context, so compress it first.
+- Tested on Windows so far; opening the desktop apps' links on macOS and Linux is not verified.
+
+## Commands
+
+`open` (default) · `serve` · `stop` · `status`, with an optional `--port`.
+
+## Data
+
+Stored in `~/.gft-merge/` (set `GFT_MERGE_HOME` to change):
+
+- `pools/<id>.json`: the pool's name, its balls, and each ball's sessions and compacts.
+- `pools/<id>.jsonl`: the pool's messages, one per line. When sessions are compressed their messages are removed and only the compact remains; the original sessions in each tool are untouched.
+- `settings.json`: which tools are enabled, and the processor's tool and model.
+
+Everything GFT-Merge sends starts with `〔GFT-Merge〕`; merging skips such messages, so content does not snowball back and forth.
+
+## Development
+
+```bash
+npm install
+npm test
+node cli.mjs open
+```
+
+## License
+
+MIT

package/README_ZH.md

@@ -0,0 +1,71 @@
+<p align="center"><a href="README.md">English</a> · <strong>简体中文</strong></p>
+
+# GFT-Merge
+
+把不同 AI 工具里的会话合进一个**池子**，再拿池子在任一工具里开一个新会话接着干。本地运行，数据只在本机。
+
+目前支持 **Claude Code** 和 **Codex**。
+
+## 开始
+
+需要 Node.js 22 以上，以及已经装好并登录的 Claude Code 和/或 Codex。
+
+```bash
+npx gft-merge
+```
+
+浏览器会打开 `http://127.0.0.1:4319`。也可以全局安装后运行 `gft-merge`。
+
+## 用法
+
+- **上面**：每个工具一栏，列出最近 30 天的会话。Claude 的列表跟桌面端一致：已归档、已删除的不列，名字用桌面端的；终端里开的会话标「CLI」。
+- **下面**：左边是池子列表，右边是选中池子的工作区。
+- **往下拖＝放进池子**：会话拖进工作区就成一个球；拖到已有的球上就融合进去。
+- **球拖到球上＝融合**：任意两个球都能融合。
+- **往上拖＝新建**：把一个球拖到某个工具的区域上，就在那个工具里新建一个会话，第一条消息就是这个球的内容。
+- **点一下球＝压缩**：用设置里选的“处理工具”（哪个工具的哪个模型）调一次模型，把球的内容压成一份。压缩中球的虚线圈会转，名字处显示“压缩中…”。压完成为一个整体，不能再拆；可以继续往上融合新的会话，也可以再压。压缩没完成时拖出去，送的是原文。
+- **球上的数字**：单个会话的球显示这个会话本身的上下文大小（直接读自工具的记录）；融合或压缩过的球显示拖出去要送的内容的 token 数，由本地分词器数出来，前面带 ≈。
+- **名字和成分**：球下方写着里面的会话，前面带工具名；鼠标悬停在名字上显示成分，从列表里把某个会话拖出去就能拆开。
+- **移动和移出**：把球拖到左边另一个池子就搬过去；拖出工作区就移出池子。
+
+## 往上拖时会发生什么
+
+GFT-Merge 在那个工具里新建会话（名为「merge · 池子名」），把内容作为第一条消息发进去，并请 AI 先简要汇报它的理解（在做什么、进展到哪、定了什么、没定什么、下一步），然后等你的指示。这是一轮真对话，所以新会话排在工具列表最上面。不装钩子、不改各工具的配置、不插手它们的处理过程。
+
+- **Codex**：新建并发出后立刻返回；回复结束后用 Codex 桌面端自己的 `codex://` 链接打开这个会话。
+- **Claude Code**：等 Claude 回完（几秒到一分钟左右，看内容长短），再用桌面端自己的 `claude://resume` 链接把会话导入桌面端并打开。
+- 新会话放在来源会话最多的那个项目目录。
+
+为什么不支持发进已有会话：Codex 会话在 Codex 桌面端里开着时，Codex 不让别的程序往里写；Claude 桌面端显示的是自己缓存的内容，别的程序写进会话文件的消息它不显示。两条路都靠不住，所以只做新建。
+
+注意：
+
+- 送的是精简原话：你说的话和 AI 每轮的最终回答，不含中间过程和工具日志。只有你点了压缩，才会调用模型、花你的额度。
+- 没压缩的内容全文送；很长时会占满对方的上下文，可以先压缩。
+- 目前只在 Windows 上实测过；macOS 和 Linux 上打开桌面端的链接没有验证。
+
+## 命令
+
+`open`（默认）· `serve` · `stop` · `status`，可加 `--port`。
+
+## 数据
+
+默认在 `~/.gft-merge/`（可用 `GFT_MERGE_HOME` 改）：
+
+- `pools/<id>.json`：池子名、里面的球、每个球里的会话和压缩块。
+- `pools/<id>.jsonl`：池子里的消息，一行一条。被压缩的会话，原消息随之移除，只留压缩块；原会话本身在各工具里不受影响。
+- `settings.json`：启用哪些工具、处理工具用哪个工具的哪个模型。
+
+送出的内容以 `〔GFT-Merge〕` 开头；再次合并时会跳过这类消息，防止来回同步越滚越大。
+
+## 开发
+
+```bash
+npm install
+npm test
+node cli.mjs open
+```
+
+## 许可
+
+MIT

package/cli.mjs

@@ -0,0 +1,132 @@
+#!/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';
+
+const [command = 'open', ...rest] = process.argv.slice(2);
+const port =
+  Number(rest[rest.indexOf('--port') + 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 没有启动。请换一个端口，例如：node cli.mjs open --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.0",
+  "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"
+  }
+}