Agent Insights
narutojzm1-dot/agent-insights
Indexação local multi-agent com Island flutuante e busca semântica
Ver no GitHubIndexador e recuperador de históricos locais de múltiplos AI coding agents (Claude Code, Codex CLI, Cursor) com interface de desktop (Multi-Agent Island) e Web UI. Resolve o problema de encontrar conversas perdidas em diferentes agents através de busca full-text, semântica e geração automática de títulos legíveis.
Instalação
npx convez-ai narutojzm1-dot/agent-insights1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Recuperar conversas antigas de coding agents quando não lembra exatamente do conteúdo
- Análise de padrões de trabalho (relatórios Insights sobre tipos de tarefa, agentes usados, tendências)
- Gerenciar permissões e sessões recentes via Island flutuante no desktop
- Busca híbrida (full-text + semântica) em históricos de múltiplos AI coding agents
Veredito

Ferramenta bem construída para um problema real de desenvolvedores que usam múltiplos coding agents. A abordagem local-first, busca full-text + semântica e visualizações (Island, Web UI) compõem uma solução completa. Recomendado para quem trabalha regularmente com Claude Code, Cursor ou Codex.
README
A tradução para o português deste README ainda está na fila.
Agent Insights
统一索引并检索多个 AI coding agent 的本地会话历史,并提供顶部"多 Agent 灵动岛"。当前支持 Claude Code、Codex CLI 与 Cursor。
解决的核心痛点:经常找不到会话。本工具把分散在各 agent 里、没有名字的会话,统一索引、自动生成可读标题、做全文搜索,让你随时找回。

顶部悬浮的「多 Agent 灵动岛」:聚合多个 agent 的权限请求(拒绝 / 允许一次 / 始终允许 直接在岛上回答),并列出最近会话点击切回。


下载(绿色版,解压即用)
到 Releases 下载,免装 Python/Node:
agent-insights-green-*.zip— 含桌面灵动岛 + Web UI(推荐)。解压后双击Start-Island.bat。agent-insights-portable-*.zip— 仅 Web UI(轻量)。双击Insights.bat。agent-insights-*.zip— 源码安装版(需 Python,可选 Node)。
数据全程留在本地(~/.agent-insights),不配大模型也能全文搜索 + 报告。
特性
- 解析 Claude Code (
~/.claude/projects/**/*.jsonl)、Codex (~/.codex/sessions/**/rollout-*.jsonl) 与 Cursor (state.vscdbSQLite) 会话 - SQLite + FTS5 全文索引(支持中文,无 jieba 时 bigram 兜底)
- 语义搜索:按意思找回会话,记不住原话也能搜(需 API key)
- 混合搜索:全文 + 语义合并
- 自动生成可读标题 + 一句话摘要 + 工作类型分类(摘要/标题需 API key,分类无 key 时用启发式)
- Insights 报告:工作类型分布、项目时间、agent 偏好、活跃趋势(纯本地聚合)
- 本地 Web UI:搜索 + 报告 + 会话详情页(点开看完整对话),无额外依赖
- CLI:
scan/index/search/open/insights/ui - CLI:
scan/index/search/open/insights/ui/ingest-event/live-status/run-actions/island - 增量索引:未变化的会话不重复处理(全文、摘要、embedding 都增量)
- 纯本地可用:不提供 API key 也能全文搜索 + 启发式分类 + 报告
安装
cd agent-insights
pip install -e .
# 可选:中文分词更好
pip install jieba
# 可选:自动标题 + 语义搜索(Anthropic 路线还需 voyageai)
pip install anthropic
pip install voyageai # anthropic provider 的 embedding
# 或走 OpenAI 兼容
pip install openai
# 可选:加速语义检索
pip install numpy
使用
# 1. 看看能发现哪些会话
agent-insights scan
# 2. 建索引(不调模型,纯本地)
agent-insights index --no-llm
# 或:带自动标题(需 API key)
export AGENT_INSIGHTS_KEY=sk-ant-...
agent-insights index
# 或:同时生成语义向量(供按意思搜索用)
agent-insights index --embed
# 3. 搜索
agent-insights search "jwt 鉴权" # 全文(记得里面的词)
agent-insights search "用户无法登录" --semantic # 语义(只记得意思,记不住原话)
agent-insights search "登录 401" --hybrid # 混合:全文+语义合并
agent-insights search "重构支付" --agent codex --since 7d
# 4. 定位某个会话的原始文件
agent-insights open <session_id>
# 5. 生成 Insights 报告(工作类型分布、项目、agent 偏好、时间趋势)
agent-insights insights
agent-insights insights --agent codex --since 30d
# 6. 启动本地 Web 界面(搜索 + 报告,最顺手的入口)
agent-insights ui # 打开 http://127.0.0.1:7788
# 7. Cursor 联调排障(检查每个 state.vscdb 的解析结果)
agent-insights cursor-check
agent-insights cursor-check --show-files
Insights 报告
insights 纯本地从 SQLite 聚合,不调模型,包含:会话/消息/工具调用总览、工作类型分布(调试/实现/重构/写脚本/配置/测试/...)、各 agent 使用占比、项目分布、按天活跃趋势、最近会话列表。工作类型在 index 阶段分类:有 API key 用便宜模型,无 key 用启发式(基于关键词 + 工具调用,实测分类相当准)。
Web 界面
ui 用 Python 标准库起服务,无额外依赖。一个页面里有:搜索框(可切全文/语义/混合,可按 agent 和时间过滤)、命中高亮、一句话摘要。点击任意结果的标题进入会话详情页,按用户/助手/工具分色展示完整对话,超长工具输出自动折叠。报告页里"最近会话"的标题同样可点进详情。
实时监控与灵动岛(本地优先)
新增“事件总线 + 动作队列 + 顶部灵动岛(Windows)”能力,目标是同时观察多个 agent 的状态,并以低打扰方式快速操作。
ingest-event:写入本地事件(默认 fail-open,不阻塞 hook 主流程)live-status:查看当前聚合状态(谁在问什么、谁在等什么)run-actions:消费动作队列(选项回复/跳终端)island:启动顶部灵动岛 companion app(Tk 本地版)
示例:
python -m agent_insights.cli ingest-event \
--agent-id cursor --task-id t-a --state awaiting \
--question "是否继续执行" --option "继续" --option "暂停"
python -m agent_insights.cli live-status --awaiting-only
python -m agent_insights.cli run-actions
python -m agent_insights.cli island
一句话摘要
有 API key 时,index 会为每个会话生成一句客观摘要(用户想解决什么、最终做了什么),用于:详情页与搜索结果展示,以及作为语义搜索 embedding 的输入文本(比直接用消息节选更干净,召回更准)。无 key 时摘要留空,不影响其他功能,embedding 自动回退到消息节选。
三种搜索的区别
- 全文(默认):用 SQLite FTS5,适合"我记得里面提到过某个词/函数名/报错"。无 jieba 时中文用 bigram 兜底,开箱即用。
- 语义
--semantic:把会话摘要算成向量,按意思找。查询词和原文用词完全不同也能命中("登录"找到讲"鉴权"的会话)。需先index --embed,需 API key。 - 混合
--hybrid:两者结果合并去重,召回最全。
语义搜索的 embedding 配置
~/.agent-insights/config.toml 里:
provider = "openai_compatible"→ 用 OpenAI 兼容的/embeddings,embed_model = "text-embedding-3-small",key 走AGENT_INSIGHTS_KEY。provider = "anthropic"→ Anthropic 自身无 embedding 端点,走 Voyage:pip install voyageai,设VOYAGE_API_KEY,embed_model = "voyage-3"。
向量以 float32 存进 SQLite,检索时内存算余弦(装了 numpy 会更快,没有也能跑)。增量:内容没变不重算 embedding。
配置
首次运行自动在 ~/.agent-insights/config.toml 生成默认配置,可覆盖路径和模型设置。
Cursor 说明
Cursor 把会话存在 SQLite (state.vscdb),分两层:每个工作区一个库(含真实项目路径)、一个全局库(cursorDiskKV 表,按 bubble 存储)。adapter 只读打开这些库,兼容 Cursor 历史上的多种序列化格式。注意:全局库里的会话不带工作区信息,项目会显示"未知";工作区库的会话能正确还原项目名。adapter 绝不修改 Cursor 的任何数据。
平台默认路径:macOS ~/Library/Application Support/Cursor/User、Linux ~/.config/Cursor/User、Windows %APPDATA%\Cursor\User。可在 config 的 [adapters] cursor 覆盖。
桌面灵动岛(Electron)
island-electron/ 是顶部悬浮的"多 Agent 灵动岛":真透明无边框、置顶、可拖动、悬停展开。它聚合多个 agent 的实时状态,default 权限模式下把 Claude Code 的权限请求直接搬到岛上(允许一次/始终允许/拒绝),并提供"最近会话 · 点击切回"。开发态:
cd island-electron
npm install # 国内可设 ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
npm start # 自动拉起 Python 后端 + 悬浮岛
Claude Code 接入(PreToolUse / Notification / 跟踪 hook)见 agent-insights/hooks/。
打包与发布
仓库不提交构建产物与发布 zip(见 .gitignore),它们走 GitHub Releases:
| 脚本 | 产物 | 说明 |
|---|---|---|
package-green.ps1 | agent-insights-green-*.zip | 全绿版:agent-insights.exe + 便携 Electron 灵动岛,解压即用,免 Python/Node |
package-portable.ps1 | agent-insights-portable-*.zip | 仅 Web UI 的绿色版(轻量) |
package.ps1 | agent-insights-*.zip | 源码安装版(需 Python/Node) |
发版:在 GitHub 上 Releases → Draft a new release → 选 tag(如 v1.0.0)→ 上传上述 zip。
后续
- 报告里加交互式图表
- 会话详情页内关键词高亮跳转
- 稀疏数据下的趋势图视觉优化