DEV Community: Peder Aaby

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.