Show HN: agent-usage-guard – a Claude Code mod to protect your usage window

Posted by zzyyxx332211 5 days ago

Comments

Comment by zzyyxx332211 5 days ago

After consuming my whole usage window in a few minutes multiple times, I realised I needed a hook to do some checks for me and prompt me before submitting when cache had expired and content is too big, so that it can suggest me to "compact then send". It can also prevent sub-agents from spawning when above 80% usage window. Control is handed over to the user.

The first I built, based on hooks (run for 75 days), the biggest burst fell from 365 agent spawned to 27, and requests over 500k tokens of context from 14.5% to 0.6%. Lockouts still went up, because lots of parallel main sessions use up the window too. The strength is that it counts agents across every session on the machine.

I built https://github.com/rbartoli/agent-usage-guard, MIT-licensed, makes no network calls, needs Claude Code 2.1.287 or later.

I have also a post on this: https://rblab.com/what-stops-claude-code-burning-your-usage-...

Comment by donfuzius 5 days ago

interesting, I think that's a needed lever of control that's currently missing. Can you state against what plan you think the defaults make sense (pro / max 5x / max 20x)? A nice addition might be presets which are meaningful for each plan (i.e roughly scaled accordingly where it makes sense).

Comment by zzyyxx332211 5 days ago

Thanks! The percentage rules don't depend on the plan as it reads the 5-hour and weekly percentages Claude Code reports, so asking at 80% and refusing at 95% works the same on Pro or Max 20x. Same for the burn rule (20 points of the 5-hour window in 10 minutes).

The ones that depend on the plan are the absolute numbers: 4 agents running at once, 12 agent starts per 10 minutes, 10M subagent tokens per 10 minutes, and the 500k context before it asks to compact. I tuned them on my own Max 5x, so on Pro they are probably too loose. You can change all of them with env vars (AGENT_GUARD_*), but presets per plan is a good idea, I'll look into it.

Comment by khalidsaidi 3 days ago

[flagged]

Comment by adastra22 4 days ago

I just disabled fan out. Hasn’t been a problem for me since!

Comment by Robin_Message 5 days ago

I was under the impression a compact resurrected the session anyway so it is not a good idea on a cold session. Is that true or is it actually cheaper?

Comment by randomblock1 5 days ago

Yes, it's better to compact before it gets out of cache. I think new versions of Claude Code can do that automatically. It can be cheaper if you switch to Haiku or something

Comment by SOLAR_FIELDS 5 days ago

Newer versions of CC do in fact compact when the cache is close to expiry. I haven’t seen it work 100% of the time but it does it most of the time

Comment by 5 days ago

Comment by neuronexmachina 5 days ago

[dead]

Comment by bhu8 5 days ago

You could use a dumber model (luna or haiku) for compact to get around this

Comment by kinduff 5 days ago

I do this + caveman and my allowed usage lasts longer.

Comment by adastra22 4 days ago

That’s forced refilling the cache under a different model.

Comment by zzyyxx332211 5 days ago

You are correct, the first turn costs about the same either way, the difference comes after. Without compacting, every later turn re-reads the non-compacted context, and after compacting it reads a short summary.

So it only pays off if the session goes on. In my own dogfooding tests, I compacted 47 times out of 50 it had suggested.