DEV Community: Peder Aaby

I built Blume: it turns your coding-agent corrections into rules

Peder Aaby — Mon, 07 Sep 2026 09:59:46 +0000

Two Claude Code terminals and a Codex session, with Blume on the right tracking all three.

Every coding agent session ends the same way for me. Somewhere in the middle I typed "no, we use the repository pattern here", or "stop adding console.logs", or just "why did you do that again". The agent fixed it, the session ended, and the next session started from zero. I typed the same correction the next day.

Blume is a desktop app that watches those sessions locally and turns the corrections you keep repeating into rules, hooks, and skills for your agent. It works with Claude Code, Codex, and Cursor. It is free, runs on macOS, Linux, and Windows, and nothing leaves your machine.

We launched it on Product Hunt this week. This post is the longer version of the launch comment, plus the questions people asked there.

The problem: agent drift

At my previous startup we shipped fast with agents and paid for it later. Duplicated functions that did the same thing with different names. Three ways of handling errors in one service. Architecture decisions that held for a week until an agent in a fresh session did not know about them. Bugs in production that traced back to the agent not knowing a rule a human had explained five times in chat.

The usual fix is to maintain your CLAUDE.md, AGENTS.md, or Cursor rules by hand. Boris Cherny, who created Claude Code, gives the advice directly: every time Claude makes a mistake, do not tell it to do it differently, tell it to write the fix into CLAUDE.md. That is good advice and almost nobody follows it consistently, because it is a chore that competes with the actual work.

We tried two things before Blume.

Manual maintenance. Someone owns the rules file and updates it after reviews. It works for about two weeks. Then the file goes stale, people stop trusting it, and the corrections move back into chat.

Automating it naively. Have the agent append a rule every time it gets corrected. This produces a context file that grows without bound, full of one-off instructions that contradict each other, and the agent gets worse because its context is now mostly noise. Context bloat is a real cost: a long CLAUDE.md is slower, more expensive, and less likely to be followed.

Neither approach answers the real question: which corrections are signal?

The idea: extract intent from the sessions themselves

Your sessions already contain the answer. If you have corrected the same thing five times across three weeks, that is a rule. If you corrected it once and moved on, it is not. The information about what matters is in the pattern, not in any single message.

So Blume reads the session history that your agent already stores on disk, and looks for three kinds of signal:

Corrections. "No, not like that." "Use X instead of Y." A direct reversal of something the agent did.
Frustration. Short, repeated, escalating messages. High token spend on something that should have been simple. The "why did you do that again" moments.
Nudges. Softer steering that is not a correction but shows up over and over. "Remember to run the tests." "Check the types."

It clusters these by theme. When a cluster crosses a threshold, Blume proposes a concrete change: a rule for your context file, a hook that runs automatically, or a skill that packages a workflow you keep re-explaining. You read the proposal, and you approve or reject it. Nothing is written to your config without you saying yes.

What the thresholds are

This was the first question on Product Hunt, and it is the right one. Taissa asked how we avoid one-off feedback getting hardened into a permanent rule too early.

The thresholds are deliberately conservative:

Five occurrences in the same thematic cluster, or
Two occurrences that Blume classifies as pain, meaning they came with frustration signals or unusually high token usage.

Everything below that stays as an observation you can look at, not a suggestion. The goal is that a suggestion, when it appears, is one you would nod at rather than one you have to think hard about.

Nivy asked a version of the same thing more bluntly: how does it tell a genuine issue from me being annoyed at 11pm? The honest answer is that it does not try to read your mood in any single message. It waits for recurrence. One bad night is one data point. The same bad night three times is a rule.

What it looks like day to day

Blume sits in the background as a desktop app. The main screen shows every agent session on your machine and whether it is working, finished, or waiting for your approval, so you can run several sessions without watching terminals.

Behind that, it maps the hidden files that shape agent behavior: rules, skills, hooks, and the context files spread across your projects. Most people I have shown this to did not know how many of those files they had, or which ones were still being read.

The Setup tab: every CLAUDE.md, skill, hook, and MCP server that shapes your agents, across harnesses and projects.

Then there are the suggestions. Each one shows the cluster of session moments that produced it, so you can see the evidence, and the proposed rule or hook. Approve, edit, or dismiss.

The Improve tab: analytics on how often you correct or steer your agents, and the suggestions those patterns produced.

It also tracks Claude Code and Codex plan usage so you see the weekly limit coming, but that is the least interesting part to me. The point is that your agent setup gets better without you maintaining it.

What it does not do

I would rather say this here than have you find out after installing.

It is a desktop app, not a CLI. If you want something scriptable for CI, this is not it. Tools like ccusage are better for usage numbers in a terminal.
It needs sessions to learn from. On a brand new project with no history it has nothing to say. It gets useful after a week or two of real work.
If you already keep a tight, hand-tuned CLAUDE.md and you are the only person on the project, you may not need it. The pain it solves scales with the number of sessions, people, and agents touching a codebase.
Analytics on whether your setup is improving over time is still in progress. The suggestions work today. The trend view is next.

Privacy

All processing happens on your machine. Blume reads the session files your agent already writes locally, and does not send your code or your chats anywhere. That was a constraint from day one because the sessions contain everything: proprietary code, half-formed ideas, and the occasional swearing.

What I want from you

Blume is free. If you run Claude Code, Codex, or Cursor daily, I would like to know two things after a week of use:

Did the first suggestion match something you actually wanted, or did it feel off? That tells us whether the thresholds are tuned right for your style.
What did you correct this week that Blume did not catch?

Download is at blume.codes. The Product Hunt thread is still open if you would rather ask there, and I answer everything.

Peder

Claude Code's Weekly Limit, Explained (and How to See It Coming)

Peder Aaby — Fri, 07 Aug 2026 11:23:49 +0000

The 5-hour limit is annoying. The weekly limit is the one that actually ruins your week: you wait out the usual break, come back, and you are still locked out, sometimes for days. This post explains how the weekly limit actually works, how to tell which limit you hit, why your usage drains faster than your activity suggests, and every way to see it coming before it lands.

Disclosure: I work on Blume, a desktop app mentioned in the tools section. Everything else here comes from Anthropic's documentation and the built-in commands.

The two limits, in one minute

Claude Code subscriptions (Pro, Max, Team, Enterprise) enforce two overlapping windows:

A rolling 5-hour window. Limits the pace of your usage. Wait, and it comes back.
A weekly window. Caps your total volume. When this one is gone, waiting an hour does nothing.

Two details cause most of the confusion:

The pool is shared across products. Claude Code, claude.ai chat, and Cowork all draw from the same allowance. A long brainstorming session in the web chat eats the same budget your coding sessions use.
It is shared across models too. Switching from Opus to Sonnet with /model keeps you working after an Opus-specific limit message, but it does not restore access once you have hit the overall session or weekly limit.

Which limit did I hit?

The error message tells you: "You've hit your session limit" is the 5-hour window, "You've hit your weekly limit" is the weekly cap. Both show when the window resets. The practical test, if you missed the message: if a short break restores access, it was the 5-hour window. If you stay blocked no matter how long you wait, it was the weekly cap.

Run /usage at any time to see both bars, your reset times, and activity stats. On claude.ai, Settings > Usage shows the same thing in a browser.

Why the weekly limit drains faster than you expect

This is the part most guides skip, and it is where the budget actually goes. Claude Code sends your full conversation with every request, so context size, not message count, drives consumption. Anthropic's own docs list the main culprits:

Long-lived sessions. A one-line question in a session that has been open all day still carries the whole conversation. Prompt caching makes re-reads cheaper, but they are not free.
Cache misses after breaks. On a subscription, the prompt cache lives for about an hour. Come back from lunch and your first message reprocesses the full context at normal rates. (Once you are drawing on usage credits, the cache lifetime drops to five minutes.)
Compaction. /compact reads everything it summarizes, so compacting a huge context is itself a huge request. /clear costs nothing, so prefer it when you do not need continuity.
Scheduled tasks and agent teammates. Anything that fires on an interval, or any parallel teammate you forgot to shut down, keeps drawing from the pool while you are not looking. Agent teams can use roughly 7x the tokens of a normal session.

The newer builds of Claude Code surface this directly: the /usage breakdown now attributes recent usage to skills, subagents, plugins, and individual MCP servers, and flags behaviors like long context or cache misses when one accounts for 10 percent or more of your recent usage. Press d or w to toggle between the last 24 hours and the last 7 days. If you have not looked at this screen since it shipped, it answers "where did my week go" better than any external tool used to.

Seeing it coming: the tooling options

Built-in: /usage for the bars and the attribution breakdown, /context for how full the current session is, and a status line if you want context usage always visible.

CLI reports: ccusage reads your local session logs and produces daily, weekly, and 5-hour-block reports, useful for understanding patterns across weeks. Claude Code Usage Monitor gives you a live terminal view with burn-rate predictions for the current window.

Desktop: Blume shows plan usage for Claude Code and Codex side by side, next to a live view of what every agent is doing (working, finished, or waiting on approval). The angle is different from the CLI tools: usage spikes are often a symptom of setup problems, like an agent stuck re-reading files because its instructions are unclear, and Blume also tracks the rules, skills, and hooks steering each agent, with automatic mismatch detection on its roadmap. If you only run Claude Code in one terminal, the built-ins plus ccusage cover you; Blume earns its place when several agents share your weekly budget.

What to do when you hit the wall

Usage credits. Paid plans can now continue past the limit with usage credits: run /usage-credits to set it up. Older "you just have to wait" advice predates this.
Make the budget go further. Clear between unrelated tasks, resume big sessions from a summary instead of the full history, use Sonnet for routine work and save Opus for the hard problems, lower the thinking effort for simple tasks, and move rarely-used instructions out of CLAUDE.md into skills that load on demand.
Check the breakdown before changing habits. If /usage says one MCP server or a cache-miss pattern accounts for a third of your consumption, fix that first. One config change can be worth more than a week of careful prompting.

FAQ

Does claude.ai chat count against my Claude Code weekly limit?
Yes. Pro and Max usage is one pool shared across Claude Code, claude.ai, and Cowork.

When exactly does my weekly limit reset?
The limit message and /usage both show your reset time. Do not rely on blog posts for this one: third-party write-ups disagree about the reset mechanics, and your own /usage screen is authoritative for your account.

Does switching models restore access?
No. Session and weekly limits are shared across all models. Switching only helps with model-specific messages like the Opus limit.

Can I pay to keep working?
Yes, with usage credits on paid plans, or by using an API key with pay-as-you-go billing, which has no weekly cap but bills per token.

Do background processes really use my quota?
A little. Conversation summarization and some status commands consume small amounts (typically under $0.04 per session), but scheduled tasks and idle agent teammates can consume a lot more.

If your weekly limit keeps surprising you, the /usage attribution screen is the first thing to check. And if you have found a consumption pattern that surprised you, share it in the comments: the failure modes are more varied than the docs suggest.

How to Know When a Claude Code Agent Needs Your Approval (Without Watching the Terminal)

Peder Aaby — Wed, 05 Aug 2026 13:48:57 +0000

The promise of background coding agents is that you kick off a task and go do something else. The reality, for a lot of people, is kicking off a task, doing something else, and coming back forty minutes later to find the agent stopped three minutes in, waiting for permission to run a command.

An agent that waits silently is worse than an agent that interrupts you, because the silence costs you the whole gap. Here is every practical way to get notified the moment a Claude Code agent needs your input.

Disclosure: I work on Blume, covered as one option below.

Option 1: Claude Code's agent view

Claude Code has a built-in answer for multiple sessions: agent view. It shows what every session is doing and which ones need input, lets you dispatch new sessions, and while it is open, the terminal tab title shows a count of sessions awaiting input.

Crucially, agent view also sends notifications through your configured terminal notification channel when a background session starts needing input, finishes, or fails. This uses the same preferredNotifChannel setting as the rest of Claude Code, so make sure that is set to something you will actually notice (terminal_bell or your OS notifier).

Good for: running several Claude Code sessions from one terminal.
The gap: you need agent view open, and it covers Claude Code only.

Option 2: The Notification hook

For full control, Claude Code fires a Notification hook event with types like agent_needs_input and agent_completed. A hook is a shell command, so you can route it anywhere: macOS notification, Slack webhook, ntfy push to your phone.

A minimal macOS example in .claude/settings.json:

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude needs input\" with title \"Claude Code\" sound name \"Glass\"'"
          }
        ]
      }
    ]
  }
}

Swap the osascript for a curl to a Slack webhook or ntfy.sh topic and the alert follows you off the machine.

Good for: people who want alerts in a specific channel, deterministically.
The gap: per-machine setup, and it alerts without showing state. You still open the terminal to see what the agent wants.

Option 3: Stay current on permission-prompt fixes

One reason this problem feels worse than it should: for a while, background subagents could be silently blocked by permission prompts that never surfaced, which looked like a hung agent. Since v2.1.186, background subagents surface their permission prompts into the main session, labeled with the subagent's name, and you approve with a keypress.

If agents seem to hang with no prompt anywhere, update Claude Code before debugging anything else. Several apparent hangs in older versions were exactly this bug.

Option 4: A desktop dashboard across all your agents

The options above are per-tool and per-terminal. Blume approaches it from the desktop: it monitors your coding agents across Claude Code, Codex, and Cursor and shows at a glance which are running, which are working, and which are stuck waiting for approval, without you cycling through terminal tabs. Because it also tracks plan usage, "why did my agent stop" has one more answer visible in the same place: sometimes the agent is not waiting for permission, it is waiting for your 5-hour window to reset.

Blume's broader premise is that interruptions like these are often symptoms of setup problems. An agent that constantly asks for permission usually has a permissions config that does not match how you actually work, and Blume's suggestion engine flags exactly that kind of mismatch (along with rules your agents ignore and hooks that never fire) and proposes fixes you approve or reject.

Good for: multi-agent, multi-project setups.
The gap: if you run one agent in one terminal, the built-ins above are probably enough.

Reduce the prompts instead of just routing them

The best notification is the one that never fires. Three habits shrink the number of approval stops dramatically:

Pre-approve what you always approve. If you say yes to npm test every time, put it in your allowlist in .claude/settings.json. Every rubber-stamp prompt is pure interruption
Scope permissions per project. A prototype repo can run permissive; a production repo should not. Checked-in project settings mean the whole team gets the same behavior
Audit what the agent actually asks for. The prompts you keep approving are a to-do list for your permissions config. This is the kind of setup-versus-behavior mismatch that tooling can watch for you

FAQ

Do I get notifications when Claude Code runs in the background?
Yes, if agent view is open or you configure the Notification hook. Otherwise a stopped background session waits silently, which is the trap this post exists to fix.

Can I get alerts on my phone?
Yes. Point the Notification hook at a push service like ntfy.sh or a Slack webhook.

Why does my agent stop even though I approved everything?
Check three things in order: an unsurfaced permission prompt (update Claude Code), a hit usage limit (/usage), or the agent finished and the completion notification went nowhere.

If you have a notification setup that survives real use, especially for a fleet of parallel agents, share it in the comments.

How to Sync Cursor Rules, CLAUDE.md, and AGENTS.md Across Projects Without Config Drift

Peder Aaby — Wed, 05 Aug 2026 13:48:21 +0000

If you use Claude Code and Cursor, or you work across more than a handful of repos, you have met config drift: the CLAUDE.md in one project says one thing, the .cursor/rules in another says something else, and the AGENTS.md you wrote for Codex is three months behind both. Every agent gets a slightly different briefing, so every agent behaves slightly differently, and nobody can say which copy is the truth.

This post covers the five practical approaches to keeping agent configuration in sync, from zero-dependency symlinks to purpose-built tools.

Disclosure: I work on Blume, which appears as one of the five options. The other four are covered on their merits, and for many setups one of them is all you need.

The problem in one sentence

Every agent invented its own config location: Claude Code reads CLAUDE.md and .claude/ (rules, skills, hooks, settings), Cursor reads .cursor/rules/*.mdc, Codex reads AGENTS.md, and Copilot, Gemini CLI, and the rest have their own variants. The knowledge is 90 percent identical, but it lives in N places times M repos.

Option 1: Symlinks (the zero-dependency fix)

Make one file the source of truth and link the rest to it:

# AGENTS.md is the master; CLAUDE.md points at it
ln -sf AGENTS.md CLAUDE.md

A popular variant centralizes everything in one .agents/ (or .ai/) folder in the repo and symlinks each tool's expected path into it. Update the master file and every tool sees the change instantly.

Good for: single repo, cross-tool consistency.
Limits: does nothing across repos, and symlink behavior on Windows can be a headache for mixed teams.

Option 2: Hard links

Same idea, but the same physical file exists at multiple paths. Some prefer this because every path looks like a real file to tools that resolve symlinks oddly.

Good for: the same cases as symlinks, with slightly different edge cases.
Limits: hard links silently break when a tool replaces a file instead of editing it in place, which is exactly what some formatters and generators do. Drift returns without warning, which is worse than obvious drift.

Option 3: ai-rules-sync (cross-tool, git-backed)

ai-rules-sync manages rules, skills, commands, and subagents in a git repository and syncs them into projects via symlinks. It explicitly supports Cursor, Claude Code, Copilot, OpenCode, Trae, Codex, Gemini CLI, and Warp, which makes it the broadest cross-tool option.

Good for: individuals and teams who want one git repo as the canonical rule set across many projects and many tools.
Limits: you are adopting a tool and its conventions; the sync is still file-copy-shaped, so what to sync and when stays a human decision.

Option 4: RuleSync (CI-friendly distribution)

RuleSync distributes CLAUDE.md, .cursorrules, and settings files across repos with npx rulesync-cli pull, and it runs in CI. Adding it to postinstall means every checkout gets current rules automatically.

Good for: teams that want rule distribution to be part of the build, not a manual step.
Limits: pull-based distribution keeps files identical, but it cannot tell you whether the rules themselves are still correct.

Option 5: Blume (drift detection, not just distribution)

The four options above all solve copying: making sure the same bytes exist in the right places. Blume works on the layer above that. It is a desktop app that manages rules, skills, hooks, and the rest of your agent dotfiles centrally across Claude Code, Codex, and Cursor, and then does the part copying cannot: it watches how your agents actually behave, detects when setup and instructions have drifted apart (a rule one agent ignores, configs that contradict each other, a hook that never fires), and proposes fixes you approve or reject.

Sync tools keep copies identical. Identical copies of a rotten rule set are still rotten, and that second failure mode is the one that quietly degrades agents over months.

Good for: multi-agent setups where the config has grown beyond easy manual review.
Limits: it is a desktop app, so if you need headless CI distribution, pair it with option 3 or 4 rather than replacing them.

Which approach fits you

Situation	Start with
One repo, two tools	Symlinks
Many repos, one person	ai-rules-sync
Team, rules must ship with checkout	RuleSync in postinstall
Multi-agent, config grown past manual review	Blume, plus symlinks in-repo

These compose. A common stack is AGENTS.md as the in-repo master with symlinks, a git-backed rule repo for cross-project sharing, and something watching for drift on top.

FAQ

Which file should be the master?
AGENTS.md, because most agents now read it natively (Codex, Cursor, Copilot CLI, Gemini CLI, and Claude Code). Keep genuinely Claude-specific instructions in a small CLAUDE.md that defers to it.

Should agent config be committed?
Project-level rules, yes: they are institutional knowledge and belong in review. Personal preferences and secrets, no.

How do I know if my configs have already drifted?
Quick check: diff CLAUDE.md AGENTS.md in any repo where both exist as real files, and compare rule counts across your most-touched repos. If you find contradictions in five minutes of looking, there are more you did not find.

If you have a sync setup I did not cover, especially for larger teams, drop it in the comments.

AGENTS.md vs CLAUDE.md: Which Context File Should Your Coding Agents Use in 2026?

Peder Aaby — Wed, 05 Aug 2026 13:47:55 +0000

If you use more than one coding agent, you have probably ended up with a small pile of context files: CLAUDE.md for Claude Code, AGENTS.md for Codex, maybe leftover .cursorrules from an older Cursor setup. They all do the same conceptual job, which is giving the agent a persistent briefing that survives across sessions. The question is which one to maintain in 2026, and the answer is more nuanced than picking a winner.

Disclosure: I work on Blume, a desktop app that manages agent configuration across tools. This post stays practical and tool-agnostic; Blume appears once near the end where it is relevant.

The short version

AGENTS.md is the closest thing to a universal standard. It is recognized by Codex CLI, Copilot CLI, Gemini CLI, Cursor, and Claude Code itself.
CLAUDE.md is Claude Code's native file, and it still has capabilities AGENTS.md does not standardize, most notably hierarchical loading and imports.
If you maintain only one file, make it AGENTS.md. If Claude Code is your primary agent, a two-line setup gives you both.

What the two files actually are

CLAUDE.md is project context that Claude Code injects into every conversation. It supports a hierarchy: a global file at ~/.claude/CLAUDE.md, a project root file, and per-directory files deeper in the tree that load when the agent works in those directories. It also supports importing other files by reference, so a short root file can point to detailed docs without pasting them.

AGENTS.md is the same idea, standardized across vendors. One markdown file at the repo root that any compliant agent reads on startup. Codex popularized it, and through 2025 and 2026 most major CLIs adopted it, including Claude Code.

Functionally, both are persistent project context. The difference is tooling compatibility and features around the edges.

Where AGENTS.md wins

Cross-tool coverage. One file, every agent. When a teammate uses Codex and you use Claude Code, AGENTS.md means you are maintaining shared institutional knowledge instead of per-tool copies that drift apart.

Team standardization. It is much easier to get a team to agree on one AGENTS.md than to keep four vendor files in sync. Drift between context files is one of the most common causes of agents behaving differently for different teammates on the same repo.

Longevity. Standards outlive tools. If you switch agents next year, AGENTS.md comes with you.

Where CLAUDE.md wins

Hierarchy. Claude Code loads directory-level CLAUDE.md files as it moves through the tree. A monorepo can have a lean root file plus focused files in apps/web and packages/api. AGENTS.md as commonly implemented is a single root file.

Imports. CLAUDE.md can reference other files and pull them in, which keeps the root file short while making detailed conventions reachable.

Claude-specific instructions. Guidance about Claude Code's own features (how to use its hooks, skills, subagents, or compaction behavior) belongs in a Claude-specific file, not in a cross-tool one where other agents will read it as noise.

One warning from teams who migrated: renaming your CLAUDE.md to AGENTS.md and calling it done leaves performance on the table. The files get read by different models with different instruction-following behavior, and content tuned for one agent does not automatically land the same way with another.

The setup that gives you both

The pattern that has become standard practice:

Put all shared, tool-agnostic project context in AGENTS.md: build commands, architecture overview, conventions, testing rules.
Make CLAUDE.md defer to it. Either symlink it (ln -sf AGENTS.md CLAUDE.md) or keep a tiny CLAUDE.md that imports AGENTS.md and adds only Claude-specific instructions below.
Keep vendor-specific behavior (hooks, skills, model preferences) in each tool's own config, not in the shared file.

This way there is exactly one source of truth for project knowledge, and each agent still gets its native extras.

The maintenance problem nobody talks about

Whichever file you choose, the failure mode is the same: the file rots. Rules accumulate, some contradict each other, and some are silently ignored because the file grew past what the model reliably follows. Frontier models follow roughly 150 to 200 instructions before compliance starts dropping, and most long-lived context files blow past that without anyone noticing.

The symptom is subtle: the agent starts making mistakes it did not make three months ago, and nobody connects it to the context file.

A few ways to catch it:

Review the file quarterly like you would review CI config
Delete any rule the agent could infer from reading the code
Convert rules that must always happen into hooks, which are deterministic, instead of instructions, which are suggestions
Watch agent behavior for rules that are being ignored, which is a sign the file is too long or contradictory

That last one is tedious to do by hand, and it is the specific problem Blume automates: it watches how your agents actually behave across Claude Code, Codex, and Cursor, flags instructions your setup contradicts or ignores, and proposes edits you approve or reject. If your CLAUDE.md and AGENTS.md have been growing for a year, an automated second opinion tends to find things.

FAQ

Does Claude Code read AGENTS.md natively?
Yes. Claude Code recognizes AGENTS.md, so a symlinked or single-file setup works without duplication.

Should I keep .cursorrules?
Cursor has moved to .cursor/rules and also reads AGENTS.md. Treat legacy .cursorrules files as migration candidates.

Where do skills fit?
Skills (SKILL.md) are task-specific instructions loaded on demand, not persistent context. Keep always-true project facts in AGENTS.md and workflow recipes in skills.

What goes in neither file?
Anything a linter or formatter already enforces, anything derivable from the code in a few minutes of reading, and secrets of any kind.

If you have strong opinions on the single-file versus hierarchy trade-off, I would like to hear how you handle monorepos in particular.

How to Track Claude Code Usage in 2026: Built-in Commands, ccusage, and Desktop Dashboards Compared

Peder Aaby — Wed, 05 Aug 2026 13:42:37 +0000

If you use Claude Code on a Pro or Max plan, you have probably hit the wall mid-session: the 5-hour window runs out, or the weekly cap kicks in, usually right when the agent was in the middle of something important. The fix is not to code less. It is to see your usage before it becomes a problem.

This post covers every practical way to track Claude Code usage in 2026, from built-in commands to community CLIs to desktop dashboards, and when each one makes sense.

Disclosure: I work on Blume, one of the tools covered below. I have tried to keep the comparison factual so you can pick what fits.

The quick answer

Fastest check: run /usage inside Claude Code for your current session and weekly limits
API billing: run /cost to see running spend in the current session
Historical reports in the terminal: npx ccusage@latest
Real-time burn rate and predictions: Claude Code Usage Monitor (claude-monitor)
A desktop app that watches all your agents, not just usage: Blume

Now the details.

Understanding what you are actually limited by

Claude Code subscriptions enforce two overlapping limits:

A 5-hour rolling window. Your usage inside the current window counts against a session budget. When it resets, you get a fresh budget.
A weekly cap. Heavy use across many sessions draws down a weekly allowance, shared across Claude Code, claude.ai chat, and Cowork.

This matters because the two limits fail differently. The 5-hour window surprises you in the afternoon. The weekly cap surprises you on a Thursday. A good tracking setup makes both visible.

Option 1: The built-in commands

Claude Code ships with everything you need for a point-in-time check:

/usage shows your current 5-hour window and weekly usage with reset times (subscription plans)
/cost shows running API spend for the session (API key users)
/status shows account and model details
/context shows how full your context window is

There is also the Usage dashboard on claude.ai under Settings, which shows the session bar and weekly usage in a browser.

Good for: quick checks before starting a long session.

The gap: no history, no trends, no warning before you hit a limit, and nothing at all about what your agents are doing while you are away from the terminal.

Option 2: ccusage, the standard CLI report

ccusage is the most widely used community tool. It reads the local JSONL logs that coding agents already write to disk and turns them into cost reports. No account, no telemetry, runs with a single command:

npx ccusage@latest

What you get:

Daily, weekly, monthly, and per-session reports with USD cost estimates
A 5-hour blocks report that maps directly onto Claude's billing windows
Per-model breakdowns, cache token tracking, and date range filters
Support for 15+ agent CLIs beyond Claude Code, including Codex, Gemini CLI, and Copilot CLI
JSON export for piping into your own scripts

Good for: understanding where your tokens went, especially across weeks or months.

The gap: it is a report, not a monitor. You run it, read it, and close it. It will not tell you that your current session is on pace to hit the limit in 40 minutes.

Option 3: Claude Code Usage Monitor, the real-time view

Claude Code Usage Monitor fills exactly that gap. Install it with uv tool install claude-monitor (or pip/pipx), run claude-monitor, and you get a live terminal dashboard with progress bars, burn-rate analysis, and predictions about when you will hit your limit.

Notable features:

Plan-aware budgets for Pro, Max5, and Max20, plus a P90 auto-detection mode
Predictive warnings before you run out, based on your current burn rate
Optional local history warehouse that keeps data beyond Claude's 30-day retention
JSON/CSV export and a compact single-line mode for status bars

Good for: heavy users who live inside the 5-hour window and want to pace themselves.

The gap: it monitors Claude Code subscriptions only, and it monitors usage only. If you also run Codex or Cursor, or you care about what the agents are doing rather than just what they are spending, you need something broader.

Option 4: Blume, the desktop app for the whole agent setup

Blume approaches the problem from a different angle. Usage tracking is one part of it, but the premise is that usage is a symptom. The underlying question is whether your coding agents are set up correctly at all.

Blume is a desktop app that sits alongside Claude Code, Codex, and Cursor and gives you:

Automatic improvement suggestions. Blume watches how your agents actually behave, detects inconsistencies between your setup and your instructions (a CLAUDE.md rule your agent keeps ignoring, a hook that never fires, skills that overlap), and proposes concrete fixes you approve or reject. This is the part the CLI tools do not attempt: it does not just show you the damage, it suggests the repair.
Agent monitoring. See at a glance which agents are running, which are working, and which are stuck waiting for your approval, without cycling through terminal tabs.
Usage tracking for Claude Code and Codex plans, so the 5-hour window and weekly cap are visible in one place across tools.
Config management. Rules, skills, hooks, and the growing pile of dotfiles that agents depend on, managed centrally instead of drifting per-project.
Local storage. Conversation history stays on your device.

Good for: anyone running more than one agent, or anyone whose CLAUDE.md and hooks have grown past the point where they can eyeball whether the setup still makes sense.

The gap: it is a desktop app, so if you want something scriptable in CI, ccusage's JSON export is the better fit.

Comparison table

	Built-in commands	ccusage	Usage Monitor	Blume
Interface	In-session	CLI report	Live terminal UI	Desktop app
Real-time warnings	No	No	Yes	Yes
Historical reports	No	Yes	Yes (opt-in)	Yes
Tools covered	Claude Code	15+ agent CLIs	Claude Code	Claude Code, Codex, Cursor
Shows what agents are doing	No	No	No	Yes
Suggests setup fixes	No	No	No	Yes
Scriptable output	No	JSON	JSON/CSV	No
Price	Included	Free, OSS	Free, OSS	Free to start

Which one should you use?

You hit limits occasionally: the built-in /usage command is enough.
You want to understand a month of spending: ccusage.
You are rationing a Max plan hour by hour: Claude Code Usage Monitor.
You run multiple agents, or you suspect your agent config is quietly working against you: Blume.

These are not mutually exclusive. A common stack is /usage for quick checks, ccusage in a monthly review, and a desktop app running in the background for everything else.

FAQ

Does Claude Code share limits with claude.ai chat?
Yes. Subscription usage draws from one pool across Claude Code, claude.ai, and Cowork. A heavy chat session eats into your coding budget.

How do I see when my limit resets?
Run /usage in Claude Code, or check Settings > Usage on claude.ai. Both show reset times for the 5-hour window and the weekly cap.

Do these tools send my data anywhere?
ccusage and Claude Code Usage Monitor read local log files and run entirely on your machine. Blume stores conversation history locally on your device.

What about tracking Codex or Cursor usage too?
ccusage covers many agent CLIs for cost reports. Blume tracks Claude Code and Codex plan usage and monitors agent activity across Claude Code, Codex, and Cursor.

If you have a tracking setup that works well for you, I would genuinely like to hear about it in the comments, especially if you are juggling more than one agent.