codeburn 详细介绍：开源项目架构、功能与实践指南

项目快照：getagentseal/codeburn，约 11,094 个 Star，842 个 Fork；最新推送时间 2026-09-19T01:11:08Z。本文基于仓库公开资料撰写。

项目地址：https://github.com/getagentseal/codeburn · https://codeburn.app/

codeburn 从代码、运行环境到实践流程的项目封面 — codeburn 的项目能力与实践流程示意。

项目速览（TL;DR）

codeburn 是一个使用 TypeScript 编写的本地人工智能编程用量与成本跟踪工具。项目描述指出，它面向 Claude Code、Cursor、Codex、Gemini 等 37 个工具和智能体，能够按模型、项目和任务整理 AI 编程令牌（token）使用量与成本。

仓库默认分支为 main，许可证为 MIT。截至所给仓库资料，项目拥有 11094 个 Star 和 842 个 Fork；npm 包版本为 0.9.24，运行要求为 Node.js >=22.13.0。项目同时提供终端界面、Web 界面、桌面应用和菜单栏应用入口。

“See where your AI spend goes.”

来源：README

核心用途：聚合多个 AI 编程工具产生的本地会话、令牌和成本数据。
分析维度：模型、项目、任务；文档索引还列出了提供商、Git 分支、日期区间和会话明细等分析方向。
使用方式：可直接运行 npx codeburn，也可运行 npx codeburn web。
实现形态：CLI 使用 Ink 和 React 构建终端界面，Web 与桌面相关构建位于仓库的 dash 和相关源码中。

定位与目标用户

CodeBurn 的定位不是模型调用网关，也不是替代 Claude Code、Cursor 或 Codex 的编程代理，而是对已有 AI 编程工具产生的使用记录进行发现、解析、归集和展示。它关注的是“这些工具消耗了多少令牌和费用，以及费用发生在什么项目或任务上”。

目标用户首先是同时使用多个 AI 编程工具的个人开发者或团队成员。对于采用按量计费模型、需要追踪模型选择和项目成本的使用场景，按工具、模型和项目拆分数据比只查看单一账单更适合定位费用来源。

根据 README 和文档索引，项目还面向需要进一步分析会话组成、重试成本、路由浪费或 Claude Code 配置消耗的用户。不过，具体收费模型、账单校准方式、企业权限模型和团队协作方案，资料没有给出，应以最新仓库文档为准。

核心功能

核心功能可以分为会话发现、成本聚合、交互式查看和优化分析四类。它们共同依赖本地会话数据与不同提供商的解析器，而不是要求用户手工录入每次调用。

多工具会话发现与解析

仓库的 docs/providers/ 目录为多个提供商维护独立说明文件，包括 Claude Code、Cursor、Codex、GitHub Copilot、Gemini CLI、Kimi Code、Kiro、Goose、Droid、Devin、Cline、Mistral Vibe 等。解析器的输入是这些工具在本地保存的会话或使用记录，输出则是 CodeBurn 能够统一聚合的会话、模型、令牌和成本信息。

触发条件是用户运行 CodeBurn 的 CLI、Web 或其他界面入口。具体会话文件位置、每个提供商的字段映射和兼容版本在对应的 docs/providers/*.md 文档中定义；本文资料没有给出完整字段协议，因此不能据此推断所有工具都会提供相同粒度的数据。

按模型、项目与任务聚合

项目描述明确列出模型、项目和任务三个主要分析维度。聚合过程需要先把不同工具的本地记录转换到统一的数据结构，再按时间、项目或任务进行汇总，最后交由终端、Web 或桌面界面展示。

这种设计适合回答“哪个模型产生了更多成本”“某个项目的 AI 开销来自哪些任务”等问题。资料没有提供统一数据结构的公开接口签名，也没有说明成本价格表的具体来源，因此展示金额的计算规则应以仓库当前实现和文档为准。

终端、Web、桌面与菜单栏入口

终端入口是 npx codeburn，README 将其标为 Terminal；Web 入口是 npx codeburn web。桌面版本提供 macOS Apple Silicon、macOS Intel、Windows Microsoft Store、Linux .deb、Linux .rpm 和 AppImage 下载项，菜单栏入口则使用 codeburn menubar。

这些入口共享同一项目的数据处理能力，但资料没有给出各界面之间的完整功能差异。实际选择时，可先使用终端入口确认本地数据能被发现，再选择 Web、桌面或菜单栏界面进行持续查看。

深入会话、分支与时间区间分析

文档索引列出了 By branch、Compare cohorts、Compare periods 和 Drill-through 等功能说明。By branch 面板用于在选定项目后，按 Git 分支查看 AI 开销，并关联工作树与分支背后的单独会话；Compare periods 用于并排比较两个日期区间并定位使用量和成本变化来源。

Drill-through 的工作方式是把聚合结果展开为会话列表，从而解释一个总量由哪些会话组成，同时保留原有查看位置。Compare cohorts 面向模型历史聚合之间的比较。以上功能名称和用途来自文档索引，具体界面操作、过滤条件和导出格式未在给定资料中提供。

优化检查与 MCP 方向

文档索引中的 optimize.md 描述了 codeburn optimize：它扫描 Claude Code 会话以及 ~/.claude/ 配置，报告哪些内容消耗令牌却没有产生相应收益，并以 A 到 F 的等级评估配置。该命令涉及本地会话和用户配置，使用前应确认当前用户对这些目录具有合法访问权限。

仓库设计文档还记录了 CodeBurn MCP Server 计划，目标是通过标准输入输出（stdio）向 AI 智能体提供 get_usage 和 get_savings 两个工具。这里是设计文档中的计划信息，不应视为已经稳定发布的接口；当前资料没有给出可直接执行的 MCP 命令或接口版本。

系统架构与关键模块

从仓库结构和构建脚本看，系统由命令行入口、提供商解析层、数据聚合逻辑和展示层组成。以下说明区分“资料直接确认的内容”和“根据文件结构作出的工程判断”，避免把设计文档或目录名称误写成稳定 API。

命令行入口

package.json 将包入口设置为 ./dist/cli.js，并通过 bin 字段把 codeburn 命令映射到该文件。构建脚本会先运行 tsup，再把 src/cli.ts 复制为 dist/cli.js 并设置可执行权限。

因此，CLI 是用户进入终端、Web、菜单栏和其他子命令的统一入口。资料没有提供完整命令树；除 README 明确出现的 npx codeburn、npx codeburn web、codeburn menubar 和文档索引中的 codeburn optimize 外，不应自行补充命令。

提供商适配层

docs/providers/ 为不同工具提供独立的发现和解析说明，另有 NEW_PROVIDER.md 介绍新增提供商集成。由此可以确认，项目采用按提供商拆分的适配方式；根据本文作者的经验判断，这种模块边界有助于隔离不同工具的本地记录格式变化，但不能据此推断所有解析器都使用完全相同的实现。

解析器的输入来源是本地工具数据，输出进入统一的用量与成本分析流程。资料没有列出解析失败时的完整错误码、重试策略或兼容矩阵，运维人员应以具体提供商文档和运行时输出为准。

构建与展示层

项目依赖 Ink、React、Chalk 和 Commander，说明终端交互层采用 React 风格组件和命令行参数解析。构建脚本中的 build:dash 会进入 dash 目录执行依赖安装和构建，表明仓库包含独立的 Dashboard 构建部分。

仓库还包含 parse-worker.js.map 的发布排除规则、Playwright 开发依赖以及与性能缓存、锁相关的测试脚本。资料没有公开完整目录树和模块接口，因此这里仅描述已出现的文件和脚本，不虚构内部类名、数据库类型或缓存存储格式。

依赖与运行环境

运行时最重要的前置条件是 Node.js 版本。根据 package.json，引擎要求为 >=22.13.0；README 徽章显示 Node.js >=22，安装判断应优先采用更精确的 package.json 约束。

生产依赖包括 @modelcontextprotocol/sdk、bonjour-service、chalk、commander、ink、react、selfsigned、strip-ansi、undici 和 zod。开发依赖包括 TypeScript、tsup、tsx、Vitest、Playwright 及 Node.js、React 的类型包。

语言：TypeScript。
模块类型：ECMAScript Module，来自 "type": "module"。
运行时：Node.js >=22.13.0。
构建工具：tsup；开发运行命令使用 tsx。
测试工具：Vitest；部分端到端或浏览器相关能力使用 Playwright。

仓库资料没有提供 Dockerfile、Docker Compose 配置、数据库服务、固定端口或云端部署要求。部署这些未记录的组件前，应以最新 README 和代码中的实际配置为准。

快速开始（含最小可运行示例）

最小闭环可以不创建项目配置文件，直接使用 npm 的包执行方式启动 CodeBurn。该方式适用于本地验证 Node.js 环境和工具入口，不代表已经验证了所有提供商数据都能被成功解析。

安装并运行终端界面

# 使用 npx 获取并运行 codeburn
npx codeburn

上面的命令来自 README 中的 Terminal 用法。首次运行时，终端会进入 CodeBurn 的交互界面；具体展示内容取决于本机是否存在项目支持的工具会话数据。

运行 Web 界面并完成验证

# 启动 CodeBurn Web 界面
npx codeburn web

当终端出现 Web 界面启动提示并能打开对应页面时，可视为入口级验证完成。资料没有提供 Web 默认端口或绑定地址，因此不能在文章中写死浏览器 URL、端口号或网络暴露方式。

若已经把 npm 包安装到本地并且命令目录已加入 PATH，README 还给出了菜单栏入口：

# 启动菜单栏应用
codeburn menubar

这里没有使用 API 密钥或远程目标。项目描述将 CodeBurn 定义为本地工具，资料也没有要求设置任何密钥环境变量；如果某个提供商自身需要登录或令牌，应按照该提供商的官方配置执行，而不是把凭据写入示例命令。

配置说明

给定资料没有提供 .env.example、配置文件样例或环境变量清单，因此不能虚构用户可调参数。下面的表格列出仓库中真实存在的 npm 包元数据和运行相关字段；这些字段用于安装、构建或入口识别，不等同于业务配置项。

字段名	类型	默认值	作用
`name`	字符串	`"codeburn"`	npm 包名称，也是 npx 使用的包标识。
`version`	字符串	`"0.9.24"`	当前给定 `package.json` 中的包版本。
`type`	字符串	`"module"`	将项目声明为 ECMAScript Module。
`main`	字符串	`"./dist/cli.js"`	包的主入口文件。
`bin.codeburn`	字符串	`"dist/cli.js"`	安装后提供 `codeburn` 命令。
`engines.node`	字符串	`>=22.13.0`	声明支持的最低 Node.js 版本。
`license`	字符串	`"MIT"`	声明项目采用 MIT 许可证。

端口、缓存目录、数据目录、日志级别、价格表路径和远程同步开关在给定资料中均未提供。若需要调整这些内容，官方仓库未提供该信息，建议以最新 README、对应源码和发行版本说明为准。

进阶用法

进阶使用的重点是选择合适的观察界面，并把聚合结果下钻到具体会话。不同入口并不是独立产品，而是围绕同一批本地用量数据提供不同的操作方式。

终端优先排查：使用 npx codeburn 快速确认命令行入口和本地数据发现情况。
Web 查看：使用 npx codeburn web 访问 Web Dashboard，适合需要图形化浏览聚合结果的场景。
桌面安装：根据操作系统选择 README 列出的 macOS、Windows 或 Linux 安装包。给定资料中的桌面发行版本为 0.9.24。
分支分析：在 Desktop 的 Spend 视图中使用 By branch 面板，按项目查看分支、工作树和相关会话。
时间区间比较：使用 Compare periods 思路对比两个日期范围，定位使用量和成本差异。
配置优化：在 Claude Code 使用场景中运行文档列出的 codeburn optimize，检查会话和 ~/.claude/ 配置中的令牌消耗。

不要把这些功能理解为对所有工具都具有相同的可见性。每个提供商保存的字段不同，项目、分支、任务或模型信息是否可用，取决于本地记录是否包含相应数据以及当前解析器的实现。

可观测性与运维

CodeBurn 本身就是面向 AI 编程用量可观测性的工具，重点是从“总账单”下钻到模型、项目、任务和会话。文档索引还明确出现了重试成本、路由浪费、365 天历史等设计数据范围描述，但这些内容不应被解释为服务级别承诺或固定保留策略。

仓库脚本包含普通测试、缓存刷新锁相关测试和性能度量脚本，例如 test、test:locks、perf:fixture、perf:metric 与 perf:all。这些是开发与验证命令，不是面向终端用户的运行时监控接口；执行前应在仓库工作区安装开发依赖。

文档中的性能缓存设计说明记录过 codeburn status --format menubar-json 的缓存性能问题，但给定资料没有提供当前修复后的基准、硬件条件或 SLA。任何性能结论都应以当前版本、数据规模和本地环境的实测结果为准。

安全与合规边界

CodeBurn 处理的是 AI 编程工具的本地会话、项目名称、任务内容、模型使用量和成本信息，这些数据可能包含源代码片段、路径、内部项目名或提示词。虽然项目描述为本地工具，但“本地运行”不等于数据天然不敏感，使用前仍应按照组织的数据分类制度评估。

仅在你拥有访问授权的开发设备、项目和会话目录中运行解析。
不要把包含 API 密钥、访问令牌、私有源代码或客户数据的会话导出到未批准的位置。
在团队环境中展示成本和任务信息前，确认项目名称、分支名称与会话内容符合内部访问控制要求。
如果使用桌面、Web 或菜单栏界面，确认监听地址和网络暴露范围；资料没有提供默认端口或绑定策略，不能据此假设服务只对本机可见。
对于受监管数据、客户代码和跨境存储场景，应由组织的安全、隐私和合规负责人确认使用边界。

项目资料没有声明认证、授权、加密传输、审计日志、数据留存周期或企业合规认证。官方仓库未提供该信息，不能把 MIT 许可证或本地运行方式解读为上述安全能力的保证。

许可证与商用条款

MIT 许可证不自动授予项目商标、第三方依赖、外部服务账号或第三方数据的额外权利。项目的第三方依赖、官方发布物和集成工具还应分别遵循各自许可和服务条款，仓库发布包中也包含 THIRD_PARTY_NOTICES.md 文件。

局限性与已知限制

当前资料足以确认项目的用途和入口，但不足以构成完整的兼容性与计费准确性承诺。采用前应把以下限制纳入评估，而不是只依据 Star、Fork 或支持工具数量作决定。

“37 个工具和智能体”来自项目描述，但资料没有列出完整的 37 项清单，也没有提供每个工具的版本兼容矩阵。
不同工具的本地会话字段不一致，某些记录是否包含项目、任务、分支、模型或精确令牌数，需要查看对应提供商文档和实际样本。
成本计算的价格来源、更新时间、折扣处理、订阅额度处理和货币转换规则未在给定资料中说明。
默认端口、数据目录、缓存目录、日志文件位置和网络绑定方式未提供。
资料没有给出并发能力、最大会话数量、性能基准、数据保留 SLA 或企业级支持承诺。
MCP 功能在设计文档中被描述为计划方向，不能据此假定对应命令或工具已经稳定发布。
桌面下载链接对应 README 中的桌面版本 0.9.24，后续发行版的安装方式可能变化，应核对最新 Releases。

适合谁

适合与否主要取决于本地会话数据是否丰富、是否需要跨工具聚合，以及团队是否接受在开发机上运行解析工具。以下信号同时满足两项或以上时，CodeBurn 的定位通常更匹配。

个人或小型开发团队同时使用 Claude Code、Cursor、Codex、Gemini 等多个 AI 编程工具，需要统一查看成本。
项目负责人希望按项目、任务、模型或 Git 分支拆分 AI 编程开销，而不是只查看供应商账单总额。
开发环境可以访问相关工具的本地会话记录，并且组织允许对这些记录进行本地解析。
使用者接受先通过终端命令验证数据发现，再使用 Web、桌面或菜单栏界面查看结果。
Claude Code 用户需要检查 ~/.claude/ 配置和会话中的令牌消耗，并希望使用 codeburn optimize 进行整理。

不适合谁

如果需求重点不是本地会话统计，或者环境要求资料中尚未声明的企业能力，CodeBurn 可能不是合适的首选。以下情况应先完成安全、准确性和集成验证。

组织只允许使用具备明确认证、审计、权限隔离、数据驻留和 SLA 文档的集中式成本平台。
目标数据只存在于远程账单系统，而本机没有 CodeBurn 支持的会话记录。
团队需要官方确认的高并发、多租户、服务端 API 或固定数据导出协议，而仓库资料未提供这些能力。
成本核算必须与财务账单逐分一致，但项目当前资料没有说明价格表、订阅额度和折扣的完整计算规则。
使用环境仍停留在低于 Node.js 22.13.0 的运行时，且无法升级。

常见问题与排查（FAQ / Troubleshooting）

排查应从运行时、入口、数据发现和数据解释四个层面依次进行。不要因为界面能启动，就直接认为所有提供商记录都已成功解析。

为什么命令无法运行

先检查 Node.js 是否满足 package.json 声明的 >=22.13.0。若运行时版本不满足，官方仓库未提供兼容旧版本的方案，建议升级 Node.js 后重新执行 npx codeburn。

为什么启动后看不到某个工具的数据

确认该工具是否出现在仓库的提供商文档中，并确认本机确实产生了对应的本地会话记录。提供商文档分别描述了发现方式；资料没有给出一个覆盖所有工具的统一诊断命令，因此应从对应的 docs/providers/ 文档和实际记录入手。

为什么项目或任务维度为空

项目和任务字段依赖原始会话是否记录了这些上下文。CodeBurn 的项目描述列出这些分析维度，但没有承诺每个提供商、每种会话格式都能提供全部字段；可以先查看会话级明细，再判断是原始数据缺失还是解析器限制。

为什么金额与供应商账单不同

给定资料没有说明价格表、订阅计划、折扣、缓存令牌和货币换算的完整计算规则。应把 CodeBurn 的结果作为本地使用分析视图，并按照仓库当前文档核对计价逻辑，不能在缺少规则说明时把它当作财务结算凭证。

如何确认 Web 入口是否可用

执行 npx codeburn web，观察终端是否成功启动并根据提示访问页面。默认端口和 URL 未在资料中提供，官方仓库未提供该信息，建议以当前版本运行输出和最新 README 为准。

桌面版本如何选择

README 提供 macOS Apple Silicon、macOS Intel、Windows Microsoft Store 以及 Linux 的 .deb、.rpm 和 AppImage 入口。选择时依据处理器架构和操作系统格式，不要把 macOS Intel 安装包用于 Apple Silicon 发行项；具体安装限制仍以对应发行包说明为准。

项目地址与资源

以下链接均来自给定仓库资料，优先用于获取源代码、文档、发行包和项目公告。版本、命令和支持范围可能随仓库更新，使用前应核对最新内容。