# agentburn

Local token profiler for agent logs. Identifies heavy five-hour usage windows, tallies context costs, and measures how soon you hit subscription caps.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 113
- Author: Socialpranker
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/Socialpranker/agentburn
- Updated: 2026-10-19
- HTML: https://affpapa.org/en/nevibecode/mcp/agentburn

## What it does

The tool inspects your assistant's local transcript files without sending metrics anywhere off your machine. Instead of showing an overall total, it breaks activity down into rolling five-hour slots to pinpoint the single window that drained your allowance. Reports highlight whether spend came from cache reads, cache writes, output generation, or subagent tasks.

Under fixed subscriptions, agentburn identifies ceiling thresholds directly from transcript cut-off notices or provider metrics. It also evaluates session history growth, calculating exactly how many tokens a `/clear` call at specific thresholds would preserve during repeated context passes.

Running the tool via `uvx` requires Python 3.9 or newer on the system. The profiler relies entirely on local transcript files, so it will produce nothing if previous session histories are absent.

## Requirements
- Needs: Python and uv (commands run via uvx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add agentburn -- uvx agentburn
```
uvx runs the command named after the package; if the README names another one, use uvx --from agentburn <command>

### Codex

**Platform CLI**
```bash
codex mcp add agentburn -- uvx agentburn
```
uvx runs the command named after the package; if the README names another one, use uvx --from agentburn <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "agentburn": {
            "command": "uvx",
            "args": [
                "agentburn"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from agentburn <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "agentburn": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "agentburn"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from agentburn <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add agentburn uvx agentburn
```
uvx runs the command named after the package; if the README names another one, use uvx --from agentburn <command>

## When to use it
- pinpoint the rolling five-hour window that exhausted your allowance
- calculate token savings from pruning chat history with `/clear`
- estimate remaining working time before reaching a session limit
- break down consumption across directories, models, and skill calls

## Example prompts
- Run `agentburn limits` to check peak usage slots and time left until the cap
- Check `agentburn context` to see token burn caused by prolonged session history
- Execute `agentburn` to inspect local cost drivers and active subagent expenses

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md