# codeburn

> 来源：[GitHub](https://github.com/AgentSeal/codeburn) · ⭐ 1202 stars

## 项目简介

在AI编程助手（如GitHub Copilot、Claude Code、Cursor等）日益普及的今天，开发者的编码效率得到了显著提升。然而，随之而来的是一个隐形成本问题：**AI代码生成的Token消耗**。无论是使用OpenAI的API，还是Anthropic的Claude服务，每一次代码补全、解释或重构，都在消耗着宝贵的Token额度。对于团队或频繁使用AI编程的开发者而言，这些消耗往往像“黑盒”一样，难以追踪、分析和优化，导致成本不可控。

`codeburn`项目应运而生，旨在解决这一痛点。它是一个**交互式的终端用户界面（TUI）仪表盘**，专门为Claude Code和OpenAI Codex等AI编程服务提供成本可观测性。其核心价值在于，将原本不可见的Token消耗数据，转化为直观、实时、可交互的可视化图表，让开发者能够清晰地洞察“AI编码的Token都去哪儿了”，从而为成本控制和用量优化提供数据支撑。

## 核心特性

*   **实时交互式仪表盘**：在终端中提供完整的图形化界面，支持实时刷新，展示Token消耗、成本估算、请求历史等关键指标，无需离开命令行环境。
*   **多数��源与格式支持**：项目设计灵活，能够解析来自不同AI服务的日志或API响应。目前重点支持Claude Code，其架构也易于扩展以适配其他类似服务（如GitHub Copilot的日志）。
*   **详尽的成本与用量分析**：
    *   **总览视图**：展示总Token数、预估成本、请求次数。
    *   **时间序列图**：以折线图形式展示Token消耗随时间的变化趋势。
    *   **项目/文件级分析**：深入分析不同项目或文件中AI生成的代码量及占比，帮助定位“高消耗”区域。
    *   **模型对比**：如果使用了不同模型，可以对比其成本和效率。
*   **注重隐私与本地化**：`codeburn`在本地运行，所有日志数据的处理和分析都在用户本地完成，避免了敏感代码或使用数据上传到第三方服务器的风险。
*   **开发者友好的体验**：作为TUI应用，它启动快速，资源占用低，与开发者的终端工作流无缝集成，符合“在工具中思考”的理念。

## 技术实现

`codeburn`是一个基于Node.js的TypeScript项目，其技术栈和架构设计体现了现代CLI/TUI工具的良好实践。

1.  **技术栈**：
    *   **语言**：TypeScript，确保了代码的类型安全和可维护性。
    *   **TUI框架**：使用**`blessed`**和**`blessed-contrib`**库。`blessed`是一���强大的终端界面库，提供了构建复杂TUI的底层抽象（如盒子模型、事件处理）。`blessed-contrib`在其基础上提供了丰富的“小部件”，如折线图、条形图、表格等，是构建仪表盘的核心。
    *   **应用框架**：采用**`ink`**和**`react-blessed`**。这是一个非常有趣且高效的选择。`ink`允许开发者使用React组件的方式来构建CLI界面，而`react-blessed`是`ink`的`blessed`渲染器。这意味着开发者可以用熟悉的React声明式语法来构建复杂的TUI，极大地提升了开发效率和代码组织性。
    *   **数据处理**：核心逻辑围绕解析AI服务的日志文件（如Claude Code的日志）展开，使用Node.js的`fs`模块进行文件读取和监控，并通过自定义的解析器提取Token数、模型、时间戳、文件路径等关键信息。

2.  **架构思路**：
    项目的架构可以概括为 **“数据管道 + React视图”** 模式。
    *   **数据层**：负责监听日志文件的变化，解析原始数据，并聚合成结构化的指标（如按时间、按项目汇总）。这部分是纯Node.js逻辑。
    *   **状态层**：聚合后的数据被注入到应用的状态中。由于使用了React范���，状态管理可以非常清晰。
    *   **视图层**：由一系列`ink` + `react-blessed`组件构成。每个图表（如`LineChart`）或面板（如`Dashboard`）都是一个React组件，它们接收状态层的数据并渲染为`blessed-contrib`对应的终端图形元素。这种分离使得数据流和渲染逻辑非常清晰。

    这种用React写TUI的模式，是项目在技术实现上的一大亮点，它降低了开发复杂交互式终端应用的门槛。

## 快速上手

以下是在macOS/Linux上快速体验`codeburn`的步骤，假设已安装Node.js环境。

1.  **全局安装**：
    ```bash
    npm install -g codeburn
    ```

2.  **定位Claude Code日志文件**：
    Claude Code的日志通常位于 `~/Library/Logs/Claude/`（macOS）或 `~/.local/share/Claude/logs/`（Linux）。`codeburn`通常会尝试自动发现，你也可以手动指定。

3.  **运行仪表盘**：
    最简单的启动方式是直接运行命令，让它自动发现日志：
    ```bash
    codeburn
    ```
    如果自动发现失败，你可以使用`--log-file`参数指定确切的日志文件路径：
    ```bash
    codeburn --log-file /path/to/your/claude-code.log
    ```

4.  **查看仪表盘**：
    运行成功后，终端会清屏并显示一个类似下图的交互式仪表盘：
    ```
    +----------------------------------------------------------+
    | codeburn                            [q] Quit [r] Refresh |
    +------------------+----------------------------------------+
    | Token Overview   |          Token Usage Over Time        |
    | Total: 15,234    |  ^                                    |
    | Cost: ~$0.30     |  |                                    |
    | Requests: 42     |  +--------------------------------->  |
    +------------------+                                        |
    | Top Files by AI Tokens        | Requests by Hour (Last7d)|
    | src/utils/helper.ts: 4,512 (30%)| ████████                |
    | src/components/Modal.tsx: 2,890| ██████▊                 |
    | ...                           | ...                      |
    +-------------------------------+--------------------------+
    ```
    你可以使用键盘（如方向键）在不同的图表面板间导航，按 `q` 退出。

## 应用场景

1.  **个人开发者成本监控与习惯优化**：独立开发者或自由职业者在使用Claude Code时，可以通过`codeburn`实时了解自己的Token消耗速度和日均成本。例如，发现自己在编写某个复杂模块时AI生成了大量高Token的代码，可以反思是否提示词（prompt）不够精确，从而调整与AI的交互方式，在保证效率的同时降低成本。

2.  **团队研发管理与预算分配**：在小型团队或创业公司中，AI编程工具可能共享一个组织级API密钥。团队负责人可以定期（如每周）在共享开发机上运行`codeburn`，分析各项目或各目录下的AI代码生成量。这有助于识别哪些项目或任务对AI辅助依赖度高，为未来的技术选型、项目预算分配甚至性能评估（AI生成代码的质量与数量比）提供量化依据。

3.  **AI编程工具效能评估**：当开发者同时试用多种AI编程助手（如Claude Code vs. GitHub Copilot）时，可以结合`codeburn`（针对Claude）和其他日志分析手段进行横向对比。通过对比完成相似任务所消耗的Token数和生成的代码质量，可以更数据化地评估哪个工具在“性价比”上更符合自己的需求，而不仅仅是凭感觉。

## 总结

`codeburn`是一个精准切入AI编程时代新需求的优秀工具。它巧妙地将可观测性（Observability）理念引入AI辅助开发领域，用简洁高效的TUI形式解决了Token成本不透明的实际问题。其采用React范式开发TUI的技术选择颇具前瞻性，为同类工具开发提供了良好范本。该项目非常适合**频繁使用Claude Code等AI编程工具的开发���、���术负责人以及对研发成本敏感的小型团队**，是提升技术决策数据驱动能力的得力助手。