mirror of
https://github.com/AgentSeal/codeburn.git
synced 2026-11-22 12:59:06 +00:00
* feat(guard): warn and stop identical-call loops and failing-command retries The PreToolUse hook now watches two more signals next to the dollar caps. The same tool called with the same input (hashed as JSON with sorted keys) 4 times in a row gets a one-time warning and the 8th call is denied. A shell command (Bash or PowerShell) that already failed 3 times in the session gets a one-time warning and is denied once it has failed 5 times; successful runs do not reset the count. Both pairs are guard.json settings (loopWarnAfter, loopStopAfter, retryWarnAfter, retryStopAfter), validated like the dollar caps, null turns one off, and guard status prints them. The incoming call is read from the hook payload and recorded by tool_use_id, since the transcript can lag. The session cache (version 4) keeps a rolling window of the last 16 calls, pending shell calls and failure counts per command, folded from the same incremental tail read as the cost. When a loop or retry warning fired, the Stop note adds one line with the count and what the calls after the first warning cost. On a generated 20 MB transcript the warm hook takes about 13 ms (median of 5); the first cold read of the whole file takes about 480 ms, as before. * fix(guard): let allow lift loop blocks and tell the agent at the warning codeburn guard allow now lifts the loop and retry stops as well as the hard cap, for that session only, so polling a CI job on purpose has the same way out. The deny reasons name it. Loop and retry warnings now also reach the agent through PreToolUse additionalContext, with the same sentence plus "Change approach or ask the user." It is sent without a permissionDecision, since "allow" would also skip the user's permission prompt. The docs now say the loop count tops out at 17 (16 earlier calls plus the incoming one). |
||
|---|---|---|
| .. | ||
| design | ||
| providers | ||
| release-acceptance | ||
| sync | ||
| architecture.md | ||
| by-branch.md | ||
| cli.md | ||
| compare-cohorts.md | ||
| compare-periods.md | ||
| configuration.md | ||
| drill-through.md | ||
| guard.md | ||
| how-it-works.md | ||
| mcp.md | ||
| menubar.md | ||
| optimize.md | ||
| plans-and-quota.md | ||
| README.md | ||
| vscode.md | ||
| web.md | ||
| yield.md | ||
Docs index
One line per file in this directory, recursively.
docs/
- architecture.md — A map of the codebase.
- by-branch.md — The Spend view in CodeBurn Desktop has a By branch panel: pick a project and see where its AI spend went, per git branch, with the recorded worktrees and the individual sessions behind each branch.
- cli.md — Every CodeBurn command and keyboard shortcut, plus the report-focused flags for filtering, JSON output, and diagnosing detection.
- compare-cohorts.md — The classic Compare view answers "how do these two models differ across my whole history?" by aggregating everything each model ever did.
- compare-periods.md — Compare two date ranges side by side and see exactly what drove the change in usage and cost.
- configuration.md — Currency, model aliases, local/custom-priced/proxy models, and environment variables.
- drill-through.md — CodeBurn Desktop can open any aggregate as a session list that explains exactly what composes it, without losing your place.
- guard.md — Opt-in Claude Code hooks that watch session cost while you work: soft cap, hard cap, checkpoint nudge, session openers.
- how-it-works.md — Pricing, task categories, breakdowns, one-shot rate, per-tool data locations and parsing, and how to read the dashboard.
- mcp.md —
codeburn mcpruns a local MCP server over stdio so an AI agent can ask about your usage and savings mid-conversation. - menubar.md — The macOS menu bar app, Windows tray app (with WSL discovery), and Linux GNOME Shell extension.
- optimize.md —
codeburn optimizescans your Claude Code sessions and your~/.claude/setup, reports what is costing tokens without earning them, and grades the setup A to F. - plans-and-quota.md — Subscription plan tracking and live provider quota via
codeburn quota. - vscode.md — The VS Code extension: how it reuses the CLI client and the desktop renderer, which Node it runs on, workspace scope, and how to build and test it.
- web.md — The local browser dashboard and combining usage across your paired devices.
- yield.md —
codeburn yieldcorrelates AI sessions with git commits to show what actually shipped.
docs/design/
- design/capacity-dock.md — Status: implementation specification (Epic: Quota Intelligence #725).
- design/codeburn-desktop-plan.md — Goal: a standalone Electron desktop app that renders the approved v6 "indigo instrument" wireframes, fed entirely by spawning the
codeburnCLI for JSON. - design/codeburn-desktop.md — Build CodeBurn Desktop, a standalone, resizable native desktop application (Electron) that renders the approved v6 "indigo instrument" wireframes.
- design/codeburn-mcp-plan.md — Goal: add a
codeburn mcpstdio MCP server exposing CodeBurn's usage/cost data to AI agents via two tools (get_usage,get_savings). - design/codeburn-mcp.md — CodeBurn already aggregates rich AI-coding usage/cost data (by task, model, project, provider; retry tax; routing waste; optimize findings; 365-day history).
- design/desktop-data-lifecycle.md — Status: implementation contract for the quality/performance epic.
- design/perf-cache-fix.md —
codeburn status --format menubar-jsonwas measured taking 25-90+ seconds per call, with no speedup on a repeat call against an unchanged, freshly-warmed cache.
docs/providers/
- providers/README.md — One file per provider integration.
- providers/NEW_PROVIDER.md — Guide for adding a new session-discovery provider to codeburn.
- providers/antigravity.md — Google Antigravity (CLI and IDE).
- providers/claude.md — Anthropic Claude Code CLI and Claude Desktop's local agent mode.
- providers/cline-cli.md — The Cline command-line agent (npm
cline, 3.x). - providers/cline.md — Cline VS Code extension and Cline home-data task storage.
- providers/codebuff.md — Codebuff (formerly Manicode) CLI coding agent.
- providers/codewhale.md — CodeWhale CLI saved sessions.
- providers/codex.md — OpenAI Codex CLI.
- providers/copilot.md — GitHub Copilot Chat (CLI, VS Code core chat sessions, VS Code extension transcripts, and JetBrains IDE sessions).
- providers/crush.md — Charmbracelet's Crush TUI coding agent.
- providers/cursor-agent.md — Cursor's background agent transcripts (separate from the regular chat).
- providers/cursor.md — Cursor IDE chat history.
- providers/devin.md — Cognition Devin CLI local usage tracking.
- providers/droid.md — Factory's Droid CLI.
- providers/dsh.md — DeepSeek's open-source agent harness (
dsh, npm@deepseek-ai/dsh). - providers/forge.md — Forge agent CLI.
- providers/gemini.md — Google Gemini CLI.
- providers/goose.md — Block's Goose CLI.
- providers/grok.md — Grok Build, xAI's coding CLI.
- providers/hermes.md — Hermes Agent CLI profiles.
- providers/ibm-bob.md — IBM Bob IDE task history.
- providers/kilo-code.md — KiloCode VS Code extension.
- providers/kimi.md — Kimi Code CLI session parser.
- providers/kimicode.md — MoonshotAI Kimi Code local session usage and tool activity.
- providers/kiro.md — Kiro IDE chat history.
- providers/lingtai-tui.md — LingTai TUI per-agent token ledger integration.
- providers/mistral-vibe.md — Mistral Vibe CLI.
- providers/mux.md — coder/mux, Coder's desktop/CLI app for parallel agentic development.
- providers/omp.md — OMP CLI.
- providers/open-design.md — Open Design coding agent.
- providers/openclaude.md — OpenClaude (npm
@gitlawb/openclaude) is a Claude Code fork that runs the same agent loop against any LLM backend. - providers/openclaw.md — OpenClaw, plus the older Clawdbot / Moltbot / Moldbot lineage.
- providers/opencode.md — OpenCode (sst/opencode).
- providers/pi.md — Pi agent CLI.
- providers/quickdesk.md — Amazon Quick Desktop local usage and session history.
- providers/qwen.md — Qwen Code CLI.
- providers/vercel-gateway.md — Cloud usage for Vercel AI Gateway via the reporting API.
- providers/vscode-cline-parser.md — Shared discovery and parsing for Cline and VS Code extensions descended from Cline.
- providers/warp.md — Warp Oz agent sessions from Warp's local SQLite database.
- providers/zcode.md — ZCode CLI coding agent (z.ai), running GLM-5.2 over the z.ai start-plan.
- providers/zed.md — Zed's built-in AI agent.
- providers/zerostack.md — Zerostack (gi-dellav/zerostack), a minimal Rust coding agent.
docs/release-acceptance/
- release-acceptance/README.md — This directory turns the August 2026 dogfood audit into a repeatable release gate.
- release-acceptance/AGENT-RUNBOOK.md — Use this contract when assigning a CodeBurn candidate to an audit agent.
- release-acceptance/cases.csv — CSV, columns: id, phase, persona, surface, test, method, automation, evidence, threshold, blocking, owner.
- release-acceptance/ledger.schema.json — JSON Schema titled "CodeBurn release acceptance run".
- release-acceptance/ledger/history.jsonl — JSON Lines log; each line is one release-acceptance run record (run_id, verdict, surfaces, findings, evidence).
- release-acceptance/templates/accuracy.csv — CSV template, columns: run_id, case_id, persona, surface, filter, provider, session_id, expected/actual token and cost fields, status, evidence, notes.
- release-acceptance/templates/click-through.csv — CSV template, columns: run_id, case_id, persona, surface, destination_or_control, prerequisites, action, resulting_state, status, feedback_ms, settled_ms, screenshot, accessibility_notes, notes.
- release-acceptance/templates/findings.csv — CSV template, columns: run_id, id, severity, status, confidence, frequency, persona, surface, candidate_sha, version, prerequisites, repro, expected, actual, evidence, privacy_impact, owner, size, execution_lane, acceptance_condition.
- release-acceptance/templates/residue.csv — CSV template, columns: run_id, kind, path, active, version, bundle_id, sha256, size_bytes, process_pid, package_manager, disposition, backup_path, notes.
- release-acceptance/templates/timings.csv — CSV template, columns: run_id, case_id, surface, persona, operation, trial, cache_state, start_monotonic_ms, first_feedback_ms, first_useful_ms, complete_ms, cpu_peak_pct, rss_peak_bytes, calls, tokens, cost_usd, identical_totals, notes.
docs/sync/
- sync/README.md — Push your AI usage telemetry to a shared backend so teams can track adoption, budgets, and ROI across developers.
- sync/DEVELOPER.md — Architecture, protocol, server contract, and testing for
codeburn sync.