HyperContext Mode

The other half of the other half. Sandboxed tool output + reversible conversation compression, in one runtime.

HyperContext Mode 把两个互补的项目合并成一个上下文操作系统：

• context-mode — 管「进入上下文的工具输出」：沙箱执行、FTS5 知识库、会话记忆、hooks 路由、MCP 工具。

• billion-context — 管「已经进入上下文的对话历史」：模型 API 代理、增量分层压缩、可逆解压、前缀缓存友好。

合并后的 hctx 不是把两个 CLI 包一层，而是共享策略、存储、检索和生命周期的三层运行时：

┌──────────────────────────────────────────────────────────────┐
│ Client (Claude / Codex / Qoder / WorkBuddy / ... 34)         │
│   ├─ MCP: unified endpoint → ctx_* + hc_*                    │
│   ├─ Hooks: PreToolUse / SessionStart / PreCompact           │
│   └─ Model traffic: base URL / launcher / native plugin      │
└───────────────┬───────────────────────────┬──────────────────┘
                │                           │
        ┌───────▼────────┐          ┌───────▼──────────────┐
        │ Sandbox layer  │          │ Compression layer    │
        │ context-mode   │          │ billion-context      │
        │ - executor     │          │ - API proxy          │
        │ - FTS5 memory  │          │ - ACP summaries      │
        │ - session DB   │          │ - decompress/search  │
        └───────┬────────┘          └───────┬──────────────┘
                │                           │
        ┌───────▼───────────────────────────▼──────────────┐
        │ Control plane: policy · config · federation       │
        │ ~/.hypercontext/{config.json,data,state,logs}     │
        │ hc_search · hc_status · hc_doctor · hctx CLI      │
        └───────────────────────────────────────────────────┘

Windows 一键安装器（推荐小白）

下载 HyperContext-Setup.exe · 安装器源码

原生 WPF，支持 Windows 10/11，不需要管理员权限，不是 Electron。界面按「国际版 / 国内版」分组：

安装器会：

1. 检测 Node.js 22.18+；没有就自动下载便携 Node 24。

2. 如果本机没有项目，自动下载 GitHub 源码到 %LOCALAPPDATA%\HyperContext\app。

3. 安装依赖并构建 context-mode / billion-context。

4. 初始化 ~/.hypercontext。

5. 为选中的客户端生成 MCP / 启动器工件；只对检测到的客户端安装 hooks 或原生插件，并在修改前备份。

6. 启动本地压缩代理，运行 hctx doctor 和 hctx status。

Qoder / WorkBuddy 的客户端 MCP 配置仍需在客户端里手动添加；安装器会生成对应的 mcp.json 并在日志里打印路径。Qoder 的压缩层用 hctx launch qoder 启动。

如果你更喜欢手动安装，继续看下面的章节。

Related MCP server: FrameworkIA MCP Server

目录

• Windows 一键安装器

• 它解决什么问题

• 功能总览

• 快速开始

• 安装

• 客户端接入

• 日常使用

• 统一 MCP 工具

• 配置

• 数据目录与隐私

• 故障排查

• 架构

• 与上游的关系

• 开发与测试

• 卸载

• 许可证

• 路线图

它解决什么问题

一次 MCP 工具调用会把原始数据直接灌进上下文：一个网页快照、20 个 GitHub issue、一份访问日志，可能瞬间吃掉几十 KB。与此同时，长会话的历史会不断膨胀，最终触发宿主压缩，模型忘掉正在改的文件、任务和用户刚才的要求。

两个上游分别解决了一半：

功能总览

已实现

• 统一 MCP 端点：11 个 ctx_* + 3 个 hc_*，一次接入两层能力。

• 统一联邦搜索：hc_search / hctx search 同时检索：

  • 已索引的工具/网页/文件内容（FTS5）

  • 会话事件、决策、错误（SQLite）

  • 压缩摘要与压缩前的原始消息（billion-context index.db）

• 代理侧联邦搜索：search_context 在统一运行时下也会追加沙箱 FTS5 命中。

• 统一状态：hctx status / hc_status 同时显示沙箱节省、压缩块、代理请求、缓存命中率。

• 统一体检：hctx doctor / hc_doctor 检查 Node、引擎构建、代理、存储、更新通道和策略冲突。

• 34 客户端能力矩阵：native plugin、launcher、MCP、proxy fallback 一目了然；Qoder / WorkBuddy 的国内版与国际版分开管理。

• 自动 hooks：Claude Code、Gemini CLI、Qwen Code 已验证全 6 事件安装（安装前备份、可重复安装）。

• 三档路由：strict / balanced（默认）/ advisory，不再无脑硬拦 WebFetch。

• 双压缩协调：压缩代理启用时，会话记忆只注入最小提示，快照仍入库可搜。

• 自更新默认关闭：不会在后台悄悄覆盖 vendored 引擎。

• 统一存储根：配置、会话、CA、日志、缓存全部收进 ~/.hypercontext。

• 优雅启停：启动探测端口冲突；停止走代理的 flush 流程，外部代理不误杀。

当前边界

• 自动 hooks 安装首版只开放 Claude Code / Gemini CLI / Qwen Code；其余客户端通过统一 MCP + 压缩代理覆盖，不会贸然写配置。

• Qoder / TRAE / CodeBuddy 走 billion-context 的 launcher（证书 MITM）路径，MCP 工件已生成；Qoder 尚未做真实端到端启动验证。

• Windows 安装器已覆盖 Codex、Claude、WorkBuddy 国内/国际、Qoder 国内/国际、DeepSeek Harness、Zcode；Qoder/WorkBuddy 的 MCP 需要在客户端里手动接入。

• 统一 session identity（host session ↔ 沙箱事件 ↔ 压缩会话）仍在路线图中。

• 代理侧沙箱检索暂未按项目过滤，使用跨项目去重。

• 本项目尚未发布到 npm；当前以源码仓库方式使用。

快速开始

要求：Node.js >= 22.18（直接运行 TypeScript）或 Node 24 LTS。

git clone https://github.com/cv-superding/hypercontext-mode.git
cd hypercontext-mode

npm install
npm run setup:engines       # 安装两个引擎的依赖
npm run build:engines       # 构建 context-mode + billion-context

node bin/hctx.mjs init      # 创建 ~/.hypercontext
node bin/hctx.mjs setup --all
node bin/hctx.mjs start     # 启动压缩代理
node bin/hctx.mjs doctor    # 全部检查应通过

Windows 下可以用 bin\hctx.cmd，Git Bash 下用 bin/hctx：

bin\hctx.cmd init
bin\hctx.cmd setup --all
bin\hctx.cmd start
bin\hctx.cmd status

启动客户端：

bin\hctx.cmd launch claude-code
bin\hctx.cmd launch codex
bin\hctx.cmd launch qoder

安装

1. 前置条件

• Node.js >= 22.18（推荐 24 LTS）。本项目直接运行 TypeScript，依赖 Node 的类型剥离能力。

• npm >= 10（随 Node 分发）。

• git（拉取仓库；部分引擎功能也会调用 git）。

• 首次构建需要网络访问 npm registry。

• Windows / macOS / Linux 均可。Windows 建议 PowerShell 或 Git Bash。

检查版本：

node -v
npm -v

2. 拉取并安装

git clone https://github.com/cv-superding/hypercontext-mode.git
cd hypercontext-mode
npm install
npm run setup:engines
npm run build:engines

setup:engines 会在 engines/ 下分别安装两个上游引擎的依赖；build:engines 会构建 context-mode 的服务端/CLI/hooks 和 billion-context 的代理/插件 bundle。

依赖安装默认带 --ignore-scripts，避免上游 postinstall 在你不知情时修改客户端配置。控制面全部使用 Node 内置 node:sqlite，不依赖原生 SQLite 编译。

如果只想先体验，不安装依赖也可以运行控制面命令（hctx init、hctx clients、hctx config），但 start、index、MCP 沙箱工具需要先完成引擎构建。

3. 可选：安装全局 hctx

npm link
hctx --help

npm link 会在 npm 全局 bin 目录创建一个 hctx 软链。若提示找不到命令，把 npm 全局 bin 目录加入 PATH：

• Windows：%APPDATA%\npm

• macOS/Linux：通常是 /usr/local/bin 或 ~/.local/bin

也可以不安装全局命令，直接使用：

node bin/hctx.mjs <command>

4. 初始化

hctx init

这会创建：

~/.hypercontext/
  config.json
  data/
  state/
  bin/

自定义位置：

HYPERCONTEXT_HOME=/path/to/home hctx init

所有命令和生成的客户端工件都会记住该路径。

5. 验证安装

hctx doctor
hctx status

doctor 的期望结果：

[ok] Node.js
[ok] Unified config
[ok] Engines
[ok] Update channels
[ok] Storage
[ok] Store integrity
[ok] Compression proxy

如果代理尚未启动，会显示一条 warn，执行 hctx start 即可。

客户端接入

1. 生成工件（所有客户端）

hctx setup --all

会为 34 个客户端生成：

• 统一 MCP 配置片段：~/.hypercontext/state/clients/<client>/mcp.json

• 一键启动器：~/.hypercontext/bin/<client>.cmd 和 <client>.sh

这一步不会修改任何客户端配置。

2. 查看能力矩阵

hctx clients

每一行显示：

client               hooks   mcp   compression    label
claude-code          yes     yes   plugin:claude  Claude Code
qoder-intl           -       yes   launcher:qoder Qoder 国际版
qoder-cn             -       yes   launcher:qoder Qoder 国内版
workbuddy-intl       -       yes   proxy-only     WorkBuddy 国际版
workbuddy-cn         -       yes   proxy-only     WorkBuddy 国内版

• hooks：是否支持自动 hook 路由。

• mcp：是否可接入统一 MCP。

• compression：走 native plugin、launcher，还是只能手动指向代理。

3. Claude Code（推荐完整接入）

hctx setup claude-code --hooks

会：

• 把统一 MCP 配置写到 ~/.hypercontext/state/clients/claude-code/mcp.json

• 在 ~/.claude/settings.json 安装 PreToolUse、PostToolUse、PreCompact、UserPromptSubmit、SessionStart、Stop 六个 hooks

• 修改前自动备份为 settings.json.bak

• 所有 hook 命令都指向统一的 hook-wrapper，并内嵌 HYPERCONTEXT_HOME

手动把 MCP 片段合并进你的 Claude Code 配置，或使用上游插件机制指向：

{
  "mcpServers": {
    "hypercontext": {
      "command": "node",
      "args": ["<repo>/bin/hctx.mjs", "mcp", "--client", "claude-code"],
      "env": { "HYPERCONTEXT_HOME": "<home>/.hypercontext" }
    }
  }
}

4. Gemini CLI / Qwen Code

hctx setup gemini-cli --hooks
hctx setup qwen-code --hooks

同样会安装全 6 事件并备份设置。写入位置分别是 Gemini / Qwen 的 settings.json。

5. Codex CLI

hctx setup codex --plugin

或者直接使用启动器：

hctx launch codex

Codex 的 MCP 片段同样在 ~/.hypercontext/state/clients/codex/mcp.json。

6. Qoder 国内版 / 国际版、WorkBuddy、TRAE、CodeBuddy

Qoder 两个版本共用 billion-context 的 launcher（证书 MITM），但工件分开生成：

hctx setup qoder-cn
hctx setup qoder-intl
hctx launch qoder

WorkBuddy 通过统一 MCP + 本地代理 base URL 接入：

hctx setup workbuddy-cn
hctx setup workbuddy-intl

TRAE / CodeBuddy：

hctx launch trae
hctx launch codebuddy

沙箱层使用统一 MCP，片段在：

~/.hypercontext/state/clients/qoder-intl/mcp.json
~/.hypercontext/state/clients/qoder-cn/mcp.json
~/.hypercontext/state/clients/workbuddy-intl/mcp.json
~/.hypercontext/state/clients/workbuddy-cn/mcp.json

把对应片段加入客户端的 MCP 配置即可。首次使用证书 MITM 时，客户端/系统可能要求信任本地 CA；按 launcher 的提示操作。

Qoder 的 launcher 路径已接好，但当前版本尚未在真实 Qoder 安装上做端到端验证。WorkBuddy 需要手动把生成的 MCP 工件加入客户端配置，并把模型 base URL 指向本地代理。遇到问题请先运行 hctx doctor 并附上 ~/.hypercontext/state/logs/proxy.log。

7. 其他客户端

• 有 launcher 的客户端：hctx launch <client>。

• 只有 MCP 的客户端：把 ~/.hypercontext/state/clients/<client>/mcp.json 合并进客户端配置。

• 只能配置 base URL 的客户端：hctx start 后，把模型 API base URL 指向：

http://127.0.0.1:8787/bili/<上游完整 URL>

或使用客户端自己的代理设置指向 127.0.0.1:8787。

日常使用

启动 / 停止 / 状态

hctx start                # 后台启动压缩代理
hctx start --foreground   # 前台运行，便于调试
hctx start --restart      # 重启
hctx stop                 # 优雅停止（不杀外部代理）
hctx status               # 统一状态
hctx status --json        # 机器可读

索引内容

hctx index ./src                 # 索引目录
hctx index ./docs/a.md           # 索引单个文件
hctx index https://...           # 由 context-mode 的抓取工具处理

索引时注意项目根：

hctx index ./notes.md --project "$PWD"

--project 决定内容库属于哪个项目；MCP 会话默认使用当前工作目录作为项目根。两者一致时，ctx_search 和 hc_search 才能命中同一份内容。

搜索

hctx search "refresh token"
hctx search "retry race" --scope sandbox
hctx search "compression" --scope compression
hctx search "needle" --all-projects
hctx search "needle" --json

默认只搜当前项目；--all-projects 放宽到所有项目库。

统计

hctx stats
hctx stats --json

输出包括沙箱返回/避免字节、估算节省 token、压缩块数、压缩 token、代理请求与缓存命中率。

客户端启动

hctx launch claude-code
hctx launch codex
hctx launch qoder
hctx launch opencode

也可以直接运行生成的启动器：

~/.hypercontext/bin/claude-code.cmd
~/.hypercontext/bin/qoder.cmd

配置

hctx config path                       # 配置文件路径
hctx config show                       # 当前配置
hctx config set compression.port 9000
hctx config set sandbox.routing advisory
hctx config set sandbox.memoryInjection auto

统一 MCP 工具

在 context-mode 的 11 个工具之外，新增：

hc_search 参数：

{
  "query": "refresh token",
  "scope": "all",
  "limit": 10,
  "all_projects": false
}

结果会标注：

• [sandbox/content]：FTS5 索引内容

• [sandbox/session-event]：会话事件/决策

• [compression/compression-summary]：压缩摘要（带 ref，可用于 decompress）

• [compression/compression-message]：压缩前原始消息

沙箱子进程不可用时，hc_* 仍然可用；ctx_* 会返回明确的修复提示，不会拖垮整个 MCP。

手动 MCP 配置（通用）

{
  "mcpServers": {
    "hypercontext": {
      "command": "node",
      "args": ["/absolute/path/to/hypercontext-mode/bin/hctx.mjs", "mcp", "--client", "your-client"],
      "env": { "HYPERCONTEXT_HOME": "/home/you/.hypercontext" }
    }
  }
}

配置

默认配置 ~/.hypercontext/config.json：

{
  "version": 1,
  "profile": "balanced",
  "sandbox": {
    "enabled": true,
    "routing": "balanced",
    "memoryInjection": "auto",
    "autoIndexSessionEvents": true
  },
  "compression": {
    "enabled": true,
    "host": "127.0.0.1",
    "port": 8787,
    "autoUpdate": false,
    "advisoryCheck": false,
    "releaseNotesCheck": false
  },
  "memory": { "retentionDays": 30 },
  "clients": {},
  "update": { "auto": false },
  "telemetry": { "enabled": false }
}

字段说明

路由模式

环境变量

一般不需要手动设置；hctx 会把统一环境传给两个引擎。

数据目录与隐私

~/.hypercontext/
  config.json
  data/
    context-mode/
      sessions/<projectHash>.db       # 会话事件/快照
      content/<projectHash>.db        # FTS5 知识库
    compression/
      config.json                     # 合并受管更新字段
      sessions/index.db               # 压缩摘要/消息/块
    xdg/billion-context/ca/           # 按需生成的 MITM CA
  state/
    daemon.json
    logs/proxy.log
    logs/mcp-child.log
    clients/<id>/mcp.json
  bin/<client>.cmd|.sh

• 默认不启用遥测。

• 代理默认绑定 127.0.0.1，管理端点仅 loopback。

• 若绑定非 loopback 地址，hctx status / doctor 会明确警告：代理没有认证。

• hooks / 客户端配置只在显式 --apply / --hooks / --plugin 时修改，并在修改前备份。

• 会话数据保留期由 context-mode / billion-context 各自策略控制；彻底清理可删除 ~/.hypercontext（会丢历史，先备份）。

故障排查

Engine build missing

npm run setup:engines
npm run build:engines

代理启动失败或端口被占用

hctx status
hctx doctor

换端口：

hctx config set compression.port 9000
hctx start --restart

若端口上已经有健康的 billion-context 代理，hctx 会把它识别为 external 并复用；hctx stop 不会杀外部代理。

hctx 命令找不到

• 使用 node bin/hctx.mjs ... 或 bin/hctx.cmd ...。

• 或执行 npm link 并把 npm 全局 bin 加入 PATH。

Node 版本过低

本项目需要 Node >= 22.18。升级 Node 后重新执行 npm install 与控制面命令即可。

hooks 没生效

• 只有 Claude Code / Gemini / Qwen 支持自动 hooks。

• 检查 hctx setup <client> --hooks 的输出与备份文件。

• 检查客户端设置里的 hook 命令是否指向 packages/runtime/src/hook-wrapper.ts。

• 运行一次 hook 命令，确认退出码为 0；wrapper 设计为 fail-open，不会阻塞宿主。

Qoder / 证书 MITM

• 首次使用 launcher 可能需要信任本地 CA。

• 如果客户端不认代理，先运行 hctx doctor，再查看 ~/.hypercontext/state/logs/proxy.log。

• 也可只使用统一 MCP（沙箱层），压缩层稍后再接。

搜索没有结果

• 确认索引时的 --project 与 MCP 会话的当前工作目录一致。

• 先 hctx search ... --all-projects 排除项目作用域问题。

• 中文/短词查询会走 trigram/LIKE 回退；极短查询可能无结果。

SQLite 相关错误

• 本项目优先使用 Node 内置 node:sqlite，不需要原生编译。

• 如果看到锁/损坏提示，hctx doctor 会列出无法读取的库；备份后移走对应 .db 文件即可重建。

架构

详见 docs/ARCHITECTURE.md。核心设计：

• 入站沙箱层：工具输出不进上下文，索引后可检索。

• 历史压缩层：代理在模型请求前折叠历史，模型可 decompress 恢复。

• 控制面：统一配置/策略/存储/搜索/状态/安装器。

• 统一 MCP：本进程提供 hc_*，把 ctx_* 转发给 context-mode 子进程。

• 冲突解决：压缩开启时最小记忆注入、单一工具面、单一更新通道、单一存储根。

与上游的关系

• engines/context-mode：vendored 源码 + 3 个最小补丁（路由模式、最小记忆注入、关闭版本检查）。

• engines/billion-context：vendored 源码 + 1 个新增桥接模块和 1 处输出追加（HYPERCONTEXT=1 时启用）。

• 上游 commit、补丁清单、同步流程见 docs/UPSTREAM.md。

• 许可证与归属见 NOTICE.md 和 LICENSE。

开发与测试

npm run typecheck      # 控制面类型检查
npm test               # 联邦搜索/策略/路由/CLI/桥接测试
npm run build:engines  # 重建两个引擎

端到端冒烟（需要先构建引擎）：

export HYPERCONTEXT_HOME="$PWD/.tmp-home"
node bin/hctx.mjs init
node bin/hctx.mjs start
node tests/mcp-smoke.mjs
node bin/hctx.mjs stop

测试全部使用临时目录；不会修改真实客户端配置。

卸载

hctx stop
npm unlink -g hypercontext-mode   # 如果执行过 npm link
rm -rf ~/.hypercontext            # 删除全部本地数据（不可恢复）

然后删除仓库目录即可。

许可证

本项目是合并作品：

• engines/context-mode：Elastic License 2.0（ELv2），Copyright 2026 Mert Koseoğlu。

• engines/billion-context：MIT + 上游“产品署名”附加条款，Copyright (c) 2026 ranxianglei。

• 新增控制面代码：按 ELv2 分发，以匹配合并作品。

合并作品整体不是 MIT。ELv2 适用于本仓库的重要部分：不得把本软件作为托管/管理服务向第三方提供其大部分功能，必须保留版权与许可证声明。详见 LICENSE、NOTICE.md 与 LICENSES/。

本地和内部使用是当前版本的目标场景；对外发布、托管服务或商业分发前请做单独的许可证审查。

路线图

• 统一 session identity：host session id ↔ 沙箱事件 ↔ 压缩会话。

• 自动 hooks 扩展到 Cursor、Copilot 系、Zed、Kiro、Antigravity、Kimi、OpenClaw。

• 代理侧沙箱检索按项目过滤。

• 压缩摘要携带沙箱引用（summary → ctx:// 句柄）。

• Qoder / TRAE / CodeBuddy 原生插件适配。

• MCP HTTP transport 与多客户端复用。

• 客户端配置自动探测与回滚 UI。

• 合并回归矩阵（双引擎测试集）。

致谢

• mksglu/context-mode

• ranxianglei/billion-context

如果这个项目帮你省下了上下文和 token，欢迎 Star、提 Issue 或 PR。