agentburn — Claude Code MCP server: what it does, how to install
Local token profiler for agent logs. Identifies heavy five-hour usage windows, tallies context costs, and measures how soon you hit subscription caps.
claude mcp add agentburn -- uvx agentburnWhat agentburn 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.
What it helps with
- 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 for the agent
- Run
agentburn limitsto check peak usage slots and time left until the cap - Check
agentburn contextto see token burn caused by prolonged session history - Execute
agentburnto inspect local cost drivers and active subagent expenses
How to install agentburn
Platform CLI
claude mcp add agentburn -- uvx agentburnuvx runs the command named after the package; if the README names another one, use uvx --from agentburn <command>
Platform CLI
codex mcp add agentburn -- uvx agentburnuvx runs the command named after the package; if the README names another one, use uvx --from agentburn <command>
Config file
{
"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>
Config file
{
"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>
Platform CLI
gemini mcp add agentburn uvx agentburnuvx runs the command named after the package; if the README names another one, use uvx --from agentburn <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about agentburn
How to install agentburn in Claude Code?
Run the command claude mcp add agentburn -- uvx agentburn.
What does agentburn do?
It audits agent transcript files locally to explain token and budget exhaustion. The tool highlights peak five-hour consumption slots, measures context overhead, and projects when rate limits will trigger.
Are transcript logs uploaded to external servers?
No external network calls are made. All log processing happens locally in read-only fashion without creating any accounts.
