limboo-ai/limboo
GitHub: limboo-ai/limboo
Limboo 是一个本地优先的桌面应用，为多个编码 Agent 提供持久的工程环境——管理仓库状态、项目记忆、权限和搜索索引，使 Agent 所依赖的「世界」可验证且与供应商无关。
Stars: 80 | Forks: 3
# Limboo
**面向 AI 软件开发的操作系统。**
一个本地优先的桌面工作区，为 coding agent 提供其进行真正工程实践所需的一切：projects、sessions、文件监视、repository 索引、git、worktrees、terminal、memory、搜索、权限和 context。Limboo 不是 AI 模型，也不是 agent。它是围绕它们构建的环境——并且支持不止一个 agent。
[](https://github.com/limboo-ai/limboo/releases/latest)
[](https://github.com/limboo-ai/limboo/actions/workflows/ci.yml)
[](https://github.com/limboo-ai/limboo/actions/workflows/security.yml)
[](https://github.com/limboo-ai/limboo/releases/latest)
[](LICENSE)
[下载](#download) ·
[设计初衷](#why-it-exists) ·
[文档](docs/README.md) ·
[架构](docs/architecture/overview.md) ·
[贡献指南](CONTRIBUTING.md) ·
[路线图](ROADMAP.md) ·
[安全](SECURITY.md)
## 什么是 Limboo?
Limboo 是一个桌面应用程序（Electron + React + TypeScript），充当 coding agent 周围的工作区。Agent 本身已经理解编程、调试、规划和 git。Limboo 提供了让它能发挥最高水平的环境：它管理 repository、监视文件系统、运行 terminal、接管数据库、持有持久化的 project memory 并执行严格的安全边界，而 agent 则可以完全专注于编写软件。
它可以与**不止一个 agent** 配合使用。Claude（通过 Claude Agent SDK）和 Cursor（通过 `cursor-agent` CLI）都作为一等公民 provider 运行在一个轻量级的 adapter 接口之后——选择一个模型即选择了 provider，而该接口之上的所有部分在两种情况下表现完全一致。
每个工作单元都是一个 **Session**——它将 repository、branch、聊天历史、agent、terminal 历史、checkpoints、权限、context、memory、任务和生成的文件捆绑在一起。一切都在一个工作区内进行，而无需打开多个窗口。
## 下载
每次发布都会提供 **Windows、macOS 和 Linux** 的安装程序，同时支持 x64 和 arm64 架构。以下所有的下载内容均位于[最新发布版](https://github.com/limboo-ai/limboo/releases/latest)中。
| 平台 | 下载 | 备注 |
| --- | --- | --- |
| **Windows** (x64) | `Limboo-Setup-
-x64.exe` | NSIS installer |
| **Windows** (arm64) | `Limboo-Setup--arm64.exe` | 适用于 Windows on ARM |
| **macOS** (Apple silicon) | `Limboo--arm64.dmg` | |
| **macOS** (Intel) | `Limboo--x64.dmg` | |
| **Linux** — 通用 | `limboo--.AppImage` | 需先执行 `chmod +x`；需要 `libfuse2`（见下文） |
| **Linux** — Debian / Ubuntu | `limboo--.deb` | |
| **Linux** — Fedora / RHEL / openSUSE | `limboo--.rpm` | |
| **Linux** — Arch / Manjaro | `limboo--.pacman` | `sudo pacman -U ` |
| **Linux** — 任意发行版 | `limboo--.tar.gz` | 解压并运行 `./Limboo` |
安装后，应用程序会从发布源自动更新——包括 `.deb`、`.rpm` 和 `.pacman` 构建版本，它们会通过你的系统包管理器应用更新，并会要求输入密码。
### 这些构建版本未签名——这是你会遇到的情况
签名流水线已经实现（macOS 的 Developer ID + 公证，Windows 的 Authenticode，以及一个 Microsoft Store 渠道），但由于凭证尚未配置，目前只能手动开启——因此已发布的构建版本目前未签名，你的操作系统会对此发出警告。这是预期情况，而非下载损坏：
- **Windows** — SmartScreen 提示“Windows 已保护你的电脑”。请选择**更多信息 → 仍要运行**。
- **macOS** — Gatekeeper 会拒绝来自未知开发者的应用。右键点击该应用 → **打开**，或者清除隔离标志：
xattr -dr com.apple.quarantine /Applications/Limboo.app
未签名也意味着 **macOS 无法自动更新**：Squirrel.Mac 会拒绝更新签名无法被验证的应用。Limboo 会检测到这一点，并在“设置 → 更新”中予以说明，而不是提供一个必定会失败的按钮。Windows 和 Linux 可以正常自动更新。
- **Linux** — 这些格式不存在代码签名机制。完整性由下文的校验清单和构建出处来保证。
一旦启用，每种方式带来的好处如下，以便提前明确权衡：macOS Developer ID 会移除 Gatekeeper 提示，*并*开启 macOS 自动更新；自签名的 Windows 证书**不会**移除 SmartScreen 警告（因为它无法链接到受信任的根证书），仅能提供稳定的发布者身份；Microsoft Store 是无需证书且无警告的 Windows 更新途径。详见[代码签名](docs/ci/code-signing.md)。
为了避免让你盲目信任这一切，每个产出物都附带了校验清单和记录在公共透明度日志中的构建出处证明：
```
sha256sum -c SHA256SUMS # integrity
gh attestation verify --repo limboo-ai/limboo # provenance
```
更倾向于自己构建？请查看[快速入门](#quick-start)。
## 设计初衷
现在并不缺少为 coding agent 提供操作界面的方法。它们中的大多数在实现自身设定目标时确实表现出色：同时运行多个 agent、向你展示 diffs、为每个任务分配单独的 branch、保持记录整洁。如果这是你所需要的，目前已有很好的工具能满足你。
Limboo 出发于一个不同的观察——一个你可能已经感受到但未曾命名的东西。
### Agent 推理能力卓越，却记错了东西
让 coding agent 恢复昨天的任务，它会完美地接续对话。它记得自己决定了什么、尝试了什么、你告诉它要避免什么。它*不*记得的是该对话所围绕的那个“世界”。
Sessions 持久化的是对话，而不是文件系统。在此期间，你的队友合并了一次重构。一个 dependency 升级到了大版本。有人对 diff 所在的 branch 进行了 rebase。记录虽然完好无损，但现在却微妙地变得有些脱离实际——并且 agent 会据此自信地提出论断，因为没有人告诉它并非如此。你每次恢复 session 时，都要在前几轮对话中费力地让它回到现实，而最糟糕的情况是你根本没察觉到这些问题。
这不是模型推理的缺陷，而是一个缺失的系统。整个技术栈中，没有任何东西对 agent 行为所依存的*世界*负责。
### 监视 agent 不等于为它提供现实基础
围绕这些 agent 发展起来的工具解决了一个真实且不同的问题：可见性。看板、并行 sessions、隔离的 branch、行内审查——它们让多个 agent 变得*易于被监视*。Limboo 也具备其中的大部分功能，但这些都不是它值得被开发出来的原因。
因为在这些 dashboard 之下，环境依然是隐形的。两轮对话之间发生的任何变化，依然需要 agent 自己去重新发现。每个 provider 都保留着自己的 memory、自己的权限模型和自己的配置。切换 agent 就意味着从头开始：上一个 agent 积累的知识被锁定在那个供应商的格式中，而你精心调校的安全规则也只适用于它们中的一个。
### 因此，Limboo 将环境本身做成了一个系统
我们的理念很简单：**环境理应成为真正的底层基础设施，由应用程序拥有并维护其自身状态——而不是当前运行中的某个 agent 的附带产物。** 由此带来了四个结果，它们才是真正的产出：
**Sessions 在经过验证的 repository 现实中恢复。** 重新打开一个 session，Limboo 会根据该 session 最后一次看到的确切状态重新验证 worktree，然后计算出一个结构化的 *repository delta*：已提交的改动、发生变化的文件（并标记出 dependency manifests 和 migrations）、添加或移除的 symbols，以及哪些文件导入了移动后的内容。这个 delta 会在你的下一次 prompt 之前一次性传递给 agent，因此它能在开始时就进行对账，而不是在执行了三次工具调用后才发现偏移。有界限的、仅限 argv 的 git；绝不会阻止你切换 sessions。
**知识由应用程序接管，因此它的生命周期长于 agent。** 持久化的 project memory 和代码搜索索引是 Limboo 维护的平台级服务——完全离线，使用内置 FTS5/BM25 排序的本地 SQLite，无需调用 embeddings API。两个 agent 通过相同的工具查询*相同*的 memory 和*相同*的索引。你项目中积累的知识并不是某个供应商的资产，并且能够在项目中途切换模型后留存下来。Memory 甚至会链接到 repository symbols，因此当某段代码被删除时，与之相关的指导会自动降权，直到该代码恢复。
**一个授权核心，无论哪个 agent 正在运行。** 每次工具调用——Claude 通过 SDK callback，Cursor 通过每次运行的 hooks bridge——都会进入*相同*的决策函数，拥有相同的风险类别、相同的路径守卫和相同的批准对话框。在其之下是一个与 provider 无关的 OS 级别 sandbox，其不可协商的底线保证了你的 secrets 存储、数据库和设置不可读，无论 agent 被指示做什么。两个 agent，一套你真正编写的规则。
**UI 根本不知道当前正在运行哪个 agent。** Providers 位于一个轻量级的 adapter 接口之后：可执行文件检测、运行调用、wire-format 转换、权限映射、resume tokens。在其之上的所有内容——时间线、批准、计划、memory、搜索、worktrees——在构造上都是与 provider 无关的。添加一个 agent 就是编写一个 adapter，而不是 fork 应用程序。
### 为什么这不是又一个 Claude Code 或 Codex 的克隆
克隆产品会重新实现那些已经非常出色的部分：agent 循环、工具协议、聊天。
Limboo 刻意不拥有它们中的任何一个。它没有模型、没有 agent 循环、也没有自己的推理过程。它不持有你的 API keys——每个 agent 都会像在你的 terminal 中那样自行进行身份验证。哪怕明天直接运行 CLI，它依然有效；这里没有任何东西是一个造成锁定效应的层。
Limboo 拥有的是 agent *不*负责、但每个 agent 都需要的一切：随时间变化的 repository 状态、不属于任何供应商的持久化知识、带有 OS 级别底线的权限模型、隔离的执行 roots，以及让这些功能适用于多个 provider 的转换机制。
用一句话来区分：**wrapper 类工具让 agent 更容易被观看；而 Limboo 让 agent 所依存的世界变得持久、可验证，并且属于你自己。**
并且它在构造上就是**本地优先**的。没有后端、没有 telemetry、也没有云同步。唯一的网络流量就是 agent 与其自身 provider 的通信。项目、其历史记录和 memory 都会保留在你的机器上。
## 核心功能
- **以 Session 为核心的工作区** — repository + branch + 聊天 + agent + terminal + checkpoints + memory，全部集中在一处。
- **两个 agent，一个工作区** — Claude（通过 Claude Agent SDK）和 Cursor（通过 `cursor-agent` CLI）都是一等公民。模型选择器*就是* provider 选择器；adapter 接口之上的所有内容都与 provider 无关。
- **Resume Pipeline** — 重新打开 session 时，会根据它最后一次看到的状态重新验证 repository，并向 agent 传递一个结构化的 **repository delta**（commits、文件、symbols、dependency manifests），使其基于当前现实继续工作，而不是一份陈旧的记录。完全本地化、有界限的 git，绝不阻塞切换。
- **每个 session 独享 Git worktrees** — 每个 session 都能拥有一个真正隔离的 checkout 和 branch，并且该 worktree 是每个子系统（agent、terminal、git、搜索、文件写入）解析时所依赖的唯一执行 root。
- **深度 Git 引擎** — 包含 status、diff、stage、commit、log、branches、tags、blame、fetch、push（使用 `--force-with-lease`，绝不使用 bare force）、pull，以及用于即时恢复的轻量级按 session 划分的 **checkpoints**。仅通过 argv 执行，从不通过 shell。
- **本地 Memory 系统** — 持久化、独立于 provider 的项目知识，具备完全离线的 FTS5 / BM25 检索功能，可注入到当前正在运行的任何一个 agent 中。
- **搜索引擎** — 本地索引文件、symbols 和 import 边缘，既对检索结果进行排序，又作为只读工具回答 agent 自身的查询。
- **三层权限管理** — 两个 provider 共享一个授权核心，进行 provider 原生的权限转换，外加一个与 provider 无关、围绕 secrets、数据库和设置设有不可逾越底线的 **OS 级别 sandbox**。
- **MCP 平台层** — MCP servers 由应用程序统一配置，并由两个 agent 共享，而不是按 provider 分别配置。
- **脚本与服务** 声明在 repo 中的 dev servers 作为 PTY 受到监管，并自动分配 loopback 端口，对于 repo 编写的命令设有明确的信任门槛。
- **集成 Terminal** — 工作区作用域内的 PTY sessions；agent 的命令会同步镜像到 terminal 视图中。
- **文件系统层** — 实时监视 + 索引树 + 受监控的读写操作，将实时的 git status 推送到 session 列表中。
- **统一流式时间线** — 一个连续的、按轮次分组的事件流，涵盖对话、工具调用和状态，其中文件读取和编辑会展开为带有语法高亮的代码。
- **纯黑、仅限暗色模式的 UI** — 一个极简的三栏式 shell，专为真正的 `#000000` 背景色调校。
## 底层原理
上述每一项功能都是主进程中拥有自身文档的一个子系统——你可以从任何地方开始阅读：
| 子系统 | 负责的内容 |
| --- | --- |
| [Resume Pipeline](docs/architecture/subsystems/resume-pipeline.md) | Repository 快照、重新验证以及恢复时注入的结构化 delta |
| [Agent 管理器](docs/architecture/subsystems/agent-manager.md) | Provider adapter 接口、共享授权核心、流式转换 |
| [Worktree 管理器](docs/architecture/subsystems/worktree-manager.md) | 按 session 隔离的 checkouts；session 执行 root 的唯一解析器 |
| [Memory 系统](docs/architecture/subsystems/memory-system.md) | 分层的持久化知识、BM25 检索、提案、symbol 链接 |
| [Git 引擎](docs/architecture/subsystems/git-engine.md) | 仅限 argv 的 git、checkpoints、push/pull、diffs |
| [文件系统层](docs/architecture/subsystems/file-system-layer.md) | 监视、索引、受监控的读写操作 |
| [Terminal 管理器](docs/architecture/subsystems/terminal-manager.md) | PTY sessions 与 agent 命令镜像 |
| [服务管理器](docs/architecture/subsystems/service-manager.md) | 声明在 Repo 中的脚本与受监管的 dev servers |
| [数据库](docs/architecture/subsystems/database.md) | 本地 SQLite、WAL、版本化 schema、仅使用绑定参数 |
**关于安全态势的简述。** Renderer 进程不执行任何操作：所有的文件系统、git、shell 和数据库访问都位于主进程中，受到一个单一的、具有类型定义的 IPC 桥接保护，并带有发送者验证、默认拒绝的 web 权限，且全盘使用参数化 SQL。Git 和所有衍生进程都采用 argv 数组，绝不通过 shell。路径受到保护以防止目录遍历和符号链接逃逸。Secrets 通过 Electron 的 `safeStorage` 处理，并在记录前进行脱敏。详情见 [SECURITY.md](SECURITY.md)。
## 截图
Shell 概览：左侧是 sessions，中间是对话，右侧是活动栏——下面的每一个面板只需在活动栏上点击一次即可打开。
| | |
| --- | --- |
| **Files** — 带有按语言区分图标的已索引工作区树
| **Changes** — 带有每个文件 diff 统计的实时 git status
|
| **Git** — stage、commit、history、branches 和 checkpoints
| **Memory** — 带有分层提案的持久化项目知识
|
| **Tasks** — Agent 实时计划与进度
| **Terminal** — 工作区作用域内的 PTY sessions
|
| **命令面板** — 所有命令都在 Ctrl/Cmd+K 之后
| **全局搜索** — 文件、symbols、文档、memory、commits、sessions
|
**设置** — 在一个模态框中包含通用、外观、agent、git、memory 以及高级 JSON 编辑功能：
## 架构概览
```
Renderer (Chromium + React) UI only — it asks, it never performs
| window.limboo.*
v
Preload (contextBridge) the only bridge; contextIsolation on, sandbox on
| ipcRenderer <-> ipcMain
v
Main (Node.js + OS access) workspaces, sessions, git, terminal, fs, agent,
memory, SQLite — every OS-touching capability
```
Limboo 运行三个具有严格边界的 Electron contexts。Renderer 不包含任何业务逻辑；所有的文件系统、git、shell、数据库和 agent 工作都位于主进程中，并通过一个单一且带有类型定义的 IPC 桥接进行交互。详见 [docs/architecture/overview.md](docs/architecture/overview.md)。
## 技术栈
| 层级 | 选择 |
| ---------------- | ----------------------------------------------- |
| Shell / 桌面端 | Electron 42 (通过 Electron Forge 7) |
| Bundler | Vite 5 (`@electron-forge/plugin-vite`) |
| UI 框架 | React 19 |
| 语言 | TypeScript |
| 样式 | Tailwind CSS v4 (CSS-first，零配置) |
| 状态管理 | Zustand 5 (按领域切分的 stores) |
| 数据库 | better-sqlite3 (WAL, FTS5 + trigram) |
| Terminal | node-pty (Node-API) + xterm |
| 文件监视 | chokidar |
| Coding agents | `@anthropic-ai/claude-agent-sdk` (Claude) · `cursor-agent` CLI (Cursor) |
| 语法高亮 | Shiki (JS RegExp 引擎 — CSP 安全，无 WASM) |
| 打包 | electron-builder (NSIS, dmg, AppImage, deb, rpm) |
| 图标 | lucide-react |
## 快速入门
**前置条件**
- Node.js 20+ 及 npm。
- 用于 `better-sqlite3` 的 C/C++ 构建工具链（根据平台不同，可能是 build-essential / Xcode Command Line Tools / MSVC Build Tools）——如果没有发布匹配的预编译版本，它可能会在安装时进行编译。`node-pty`（锁定在 Node-API `1.2.0-beta` 版本）提供了 ABI 稳定的预编译版本，且从不进行编译。
- **每个 agent 自行管理其身份验证。** Limboo 绝不会要求或存储你的 provider 凭证；它使用的是 agent 现有的登录方式（例如，Claude 使用的 `ANTHROPIC_API_KEY` 或 Claude Code 凭证文件，以及 Cursor 使用的你的 `cursor-agent` CLI 登录状态）。如果你选择设置 Cursor API key，它将通过 Electron 的 `safeStorage` 进行加密，并仅在 spawn 时解密。详见 [docs/guides/using-the-agent.md](docs/guides/using-the-agent.md)。
**在开发环境中运行**
```
npm install # installs deps and compiles native modules
npm start # Electron + Vite dev server (renderer on :5173)
```
没有 `npm run dev` 命令——`npm start` 会同时驱动 Electron 和 Vite。完整的安装说明位于 [docs/getting-started/installation.md](docs/getting-started/installation.md)。
**构建安装程序**
```
npm run package # package the app (no installers)
npm run dist # branded installers for the current OS -> dist/
```
`npm run dist` 会针对你运行它的操作系统进行构建：Windows 上是 NSIS，macOS 上是 dmg/zip，Linux 上是 AppImage/deb/rpm。发布版本由 **tag 驱动**——CI 会在构建时根据 `v*` 标签确定版本号，因此 `package.json` 中的版本号仅仅是一个开发占位符，永远不应手动修改。详见 [docs/operations/release-process.md](docs/operations/release-process.md)。
## 文档
文档是按照子系统进行组织的，而不是单一文件。请从[文档首页](docs/README.md)开始：
- **入门指南** — [安装](docs/getting-started/installation.md)、[快速入门](docs/getting-started/quick-start.md)、[配置](docs/getting-started/configuration.md)。
- **核心概念** — [sessions](docs/concepts/sessions.md)、[workspaces](docs/concepts/workspaces.md)、[本地优先](docs/concepts/local-first.md)、[对话优先的 UI](docs/concepts/conversation-first-ui.md)。
- **指南** — [使用 agent](docs/guides/using-the-agent.md)、[git 工作流](docs/guides/git-workflow.md)、[memory 系统](docs/guides/memory-system.md)、[terminal](docs/guides/terminal.md)、[键盘快捷键](docs/guides/keyboard-shortcuts.md)。
- **深入探讨** — [Resume Pipeline](docs/architecture/subsystems/resume-pipeline.md)（“从你上次离开的地方继续”）以及其他[子系统文档](docs/architecture/subsystems/agent-manager.md)。
- **参考** — [`window.limboo` API](docs/reference/window-limboo-api.md)、[IPC channels](docs/reference/ipc-channels.md)、[设置](docs/reference/settings.md)、[设计 tokens](docs/reference/design-tokens.md)、[命令](docs/reference/commands.md)。
- **架构** — [概览](docs/architecture/overview.md)以及 [docs/architecture/](docs/architecture/overview.md) 下的各子系统文档。
- **运维** — 发布、CI/CD、打包以及位于 [docs/operations/](docs/operations/release-process.md) 的维护指南。
有两份内部参考文档早于此站点存在，并且仍然是供贡献者查阅的最深层的事实来源：[`CLAUDE.md`](CLAUDE.md)（代码级别的工作契约）和 [`project.md`](project.md)（完整的产品和架构愿景）。
## 项目状态
**当前发布版本：`v1.7.0`。** 桌面端基础和平台服务已经构建完成，并已投入日常使用：workspaces、带有按 session 划分的 git worktrees 的 sessions、git 引擎、集成的 terminal、文件系统层、多 agent 编排（Claude 和 Cursor）、本地 Memory 系统、搜索引擎、Resume Pipeline、Work Graph、MCP 平台层、OS 级别 sandbox，以及位于本地 SQLite 之上的硬化 IPC 层。
坦诚地说明一些待完善的粗糙之处，因为你可能会遇到它们：
- **已发布的构建版本未签名。** 签名流水线已存在，但凭证尚未配置，因此请预料到会出现 SmartScreen 和 Gatekeeper 警告——并注意，在未签名状态下 macOS 无法自动更新，因为 Squirrel.Mac 会拒绝更新无法验证其签名的应用。详见[下载](#download)。
- **Cursor 的默认模式是仅建议模式。** 在针对你的确切 CLI 构建验证交互式 hooks bridge 之前，提议的编辑内容将作为你可以批准的审查计划呈现，而不是直接应用。这是一种刻意为之的安全策略。
- **暂不支持 Cursor Cloud Agents 和 ACP** —— 目前仅支持本地 CLI 运行。图片附件仍然仅限 Claude 使用。
计划中的工作——repository 克隆/追踪 UI、独立的权限系统、合并冲突解决、远程管理、stash，以及基于 tree-sitter / vector-embeddings 升级的代码智能层——均在 [ROADMAP.md](ROADMAP.md) 中进行追踪。
## 安全
Limboo 是本地优先的，具有刻意控制的极小攻击面和纵深防御加固措施。如需报告漏洞，请遵循 [SECURITY.md](SECURITY.md) 中的说明——请勿针对安全报告开启公开的 issue。
## 许可证
基于 [MIT License](LICENSE) 发布。Copyright (c) 2026 BotCoder254。标签：AI智能体, AI编程, Electron, 工作流编排, 开发环境, 桌面应用, 网络调试, 自动化, 自动化攻击