asuramaya/neo

# neo

网站 · Dashboard 面板 · 安全说明

## 功能简介 - **直接读取本地 Claude Code 产出物**：从 `~/.claude/` 和 `~/.neo/` 读取，而不是依赖会剥离证据的导出接口 - **区分测量、估算和推断的声明**：确保行数与启发式算法和异常标签区分开来 - **提供本地操作面板**：通过浏览器 Dashboard、终端命令以及在 Claude Code 中注册的 MCP server 进行交互 - **让本地开销可见化**：呈现提醒注入、sidechain、压缩抖动、保留的遥测行以及 UI 未突出显示的其他痕迹 ## 安装说明 **推荐 — `pipx`：** ``` pipx install neo-harnesster neo ``` **使用 `pip`：** ``` pip install neo-harnesster neo ``` **直接从仓库安装：** ``` git clone https://github.com/asuramaya/neo.git cd neo python3 neo.py ``` 以上任何一种方法都可以一步完成 setup + ingest + dashboard，并打开 `http://127.0.0.1:7777`。 首次运行后请重启 Claude Code，以便安装的 hooks 开始捕获 事件。 ## CLI ``` neo # setup + ingest + dashboard neo --setup # install hooks + register MCP server neo --ingest # ingest data only neo --dashboard # dashboard only neo --dashboard --no-open # serve without opening a browser neo --port 8888 # custom port ``` ``` neo-tokens # data accounting in the terminal neo-states diagram # state machine diagram ``` 实时事件流： ``` tail -f ~/.neo/harness_log.jsonl ``` ## MCP 接口 neo 作为**每台主机一个共享 daemon** 运行。该进程在 `http://127.0.0.1:7777/mcp` 通过 HTTP 提供 dashboard *和* MCP 协议服务，并由每台主机的 bearer token 保护。`neo --setup` 会将其在 `~/.claude.json` 中注册为 `http` MCP server（而不是基于会话的 stdio 子进程）， 因此每个 Claude Code 会话都会连接到同一个 URL — 每台主机只有一个 neo 进程， 没有基于会话的扩展，也没有版本偏差。在下一次会话启动时， Claude Code 会自动连接并本地打开 dashboard。 Setup 还会安装一个 `systemd --user` 服务 (`neo.service`) 来保持 daemon 持续运行 — 登录时自动启动，崩溃时自动重启。如果 `systemd --user` 不可用，请使用 `neo-mcp --http` 手动启动。请参阅 下方的 [Daemon](#daemon)。 该 server 暴露了 12 个工具： | 工具 | 返回内容 | | --- | --- | | `status` | setup 健康状况 + 跨会话的实时进程注册表（角色、代码版本、`version_skew` 标志） | | `summary` | 所有表中的顶层行数 | | `data_accounting` | 完整的测量/估算计数 | | `tokens_report` | 包含测量与估算基准的紧凑计数总计 | | `query_reminders` | 带有文件 + 行出处的提醒行 | | `query_sessions` | 跨项目的会话列表，包含 agent / 压缩计数 | | `query_agents` | subagent 谱系和消息 | | `query_probe_events` | 原始 hook 事件，可按类型过滤 | | `query_telemetry` | 保留的遥测行 | | `query_memory_files` | 每个项目的持久化 memory 文件 | | `state_model` | 推断的 state-model 标签 | | `correlations` | 跨信号模式（hook 时间线，按类型统计的总数） | 读取 hook 事件的工具默认会过滤掉 neo 自身的 MCP 流量 (`include_self=false`)，因此观察者的开销不会影响整体情况。 ## Daemon `neo --setup` 会在 `~/.config/systemd/user/neo.service` 写入一个 `systemd --user` 单元，并启用 + 启动它。该单元运行 共享 daemon (`neo-mcp --http`)，它负责管理 dashboard、定期 ingest 以及 HTTP `/mcp` endpoint。如果启动了多个 neo 进程，它们会通过 每台主机的锁选举出一个所有者；跟随者针对共享 DB 提供查询服务， 并在所有者死亡时接管。 ``` systemctl --user status neo # check the daemon systemctl --user stop neo # stop it systemctl --user disable neo # stop it auto-starting on login neo-mcp --http # run the daemon manually (no systemd) ``` ## 证据模型 neo 有意对其声明进行标记： - **measured** — 提醒行、会话、agent、任务、memory 文件、遥测行、hook 事件；当记录包含 API 报告的 token 使用情况时，还包括隐藏上下文比例、数据乘数和 API 调用计数 - **estimated** — *仅*在没有记录 token 使用情况时，指代隐藏上下文比例和数据乘数，此时它们会回退到使用磁盘上记录的字节大小 - **inferred** — state-model 标签和基于本地计时 + 生命周期模式的异常解释 要获取准确的计费 token 数量，请在 Claude Code 中使用 `/usage`。neo 不会 伪造 token 总数。 ## 捕获内容 | 来源 | 位置 | 内容 | | --- | --- | --- | | 会话记录 | `~/.claude/projects/*.jsonl` | 完整的对话，包括系统提醒 | | subagent 和 sidechain | `~/.claude/projects/*/subagents/` | 衍生的记录和上下文副本 | | 压缩事件 | `~/.neo/harness_log.jsonl` | 来自探针的 `PostCompact` hook 事件 | | 遥测 | `~/.claude/telemetry/` | 当前保留在磁盘上的遥测行 | | memory 文件 | `~/.claude/projects/*/memory/` | 由实例播种的持久化上下文 | | 任务 | `~/.claude/tasks/` | 跨会话的任务状态 | | hook 事件 | `~/.neo/harness_log.jsonl` | 工具使用、通知、会话生命周期 | ## 无法捕获的内容 - 从未落盘的服务器端推理或模型内部状态 - 未在本地持久化的任何次要通道的内容 - 缺失的遥测行是被上传了、删除了，还是从未在本地写入 - 编译二进制文件内部的系统 prompt 组装过程 - 没有 proxy 的 HTTPS 请求和响应正文 ## 导出边界 Claude Code 中的 `/export` 命令会剥离系统提醒。而 `~/.claude/projects/` 中的原始 JSONL 文件会保留它们。neo 读取的是原始文件。 这个边界正是该项目存在的全部原因。 ## 项目布局 ``` src/neo/ app.py setup, ingest, threaded HTTP server, systemd daemon install mcp_server.py HTTP MCP server (/mcp on the shared daemon); owner election + process registry db.py SQLite ingest + query layer tokens.py visible vs hidden channel accounting states.py inferred state model + anomaly labels harness_probe.py hook script copied into ~/.neo/ by setup dashboard.html single-file local dashboard neo.py repo-clone launcher shim test.py smoke tests ``` 所有数据都存放在 `~/.neo/neo.db` 中。dashboard 仅绑定到 `127.0.0.1`。 ## Hooks neo 为 20 种 Claude Code 事件类型安装了异步 hooks： `PreToolUse` `PostToolUse` `PostToolUseFailure` `Notification` `SessionStart` `SessionEnd` `Stop` `SubagentStart` `SubagentStop` `PreCompact` `PostCompact` `UserPromptSubmit` `InstructionsLoaded` `PermissionRequest` `PermissionDenied` `TaskCreated` `TaskCompleted` `FileChanged` `CwdChanged` `ConfigChange` ## 安全性 - dashboard 和 `/mcp` endpoint 仅绑定到 `127.0.0.1`，并验证本地 `Host` 标头 - `/mcp` endpoint 需要存储在 `~/.neo/` 中的每主机 bearer token - `POST /api/ingest` 需要同源浏览器请求 - `~/.neo/` 会在操作系统允许的情况下以私有权限创建 - neo 不会将您的数据传输到任何地方 - hooks 异步运行，不会阻塞 Claude Code 的操作 - setup 会安装一个 `systemd --user` 服务 (`neo.service`)，该服务在登录时自动启动 本地 daemon 并在崩溃时自动重启；可以使用 `systemctl --user disable --now neo` 移除它（参见 [Daemon](#daemon)） - 除了 Python 标准库之外没有其他依赖项 ## 环境要求 - Python 3.10+ - 已安装 Claude Code（必须存在 `~/.claude/settings.json`） ## 升级说明 如果您之前使用过该项目旧的 `harnesster` 名称，首次运行 `neo` 或 `python3 neo.py` 会将 `~/.harnesster/` 迁移到 `~/.neo/`，并将 `harnesster.db` 重命名为 `neo.db`。`settings.json` 中的 hook 命令会被自动 重写。 `harnesster` 命令将作为转发垫片保留。 ## License MIT

标签：Claude, CVE检测, MCP, Python, 多模态安全, 无后门, 逆向工具