Practitioner viewpoint / T SALON

EDITORIAL

How to Run Long-Horizon Agent Refactoring Without Hitting the 5-Hour Limit

A practical playbook for Claude Code and Codex engineers on $20 Pro or $100/$200 Max plans: how to eliminate the 3 context black holes that drain 5-hour windows and ship 20+ file refactors using checkpointed micro-sessions.

Revised 2026-11-17

Playbook for running long-horizon AI agent refactoring within 5-hour rolling limits
Playbook for running long-horizon AI agent refactoring within 5-hour rolling limits

TL;DR

  • Multi-file refactors burn through a 5-hour rolling window in 90 minutes not because of code output volume, but because a 120K+ token session replays its entire history on every tool call.
  • Splitting a large refactor into three disk-backed micro-sessions (Read-Only Inventory -> Batched Edits of <=5 files -> Targeted Verification) cuts total token consumption by 55% to 70%.
  • Anchor your daily schedule to your first message timestamp using the 5-Hour Window Calculator and keep weekly burn near ~14% per day.

Almost every engineer running large-scale refactors in Claude Code or Codex has hit the same wall: half your files are migrated, the build is broken, and the terminal suddenly locks you out with a 5-hour limit banner. Looking at telemetry in the T Salon AI Coding Benchmark Report, over 65% of quota waste comes from compounding context replay inside oversized single sessions.

Here is the field-tested workflow for finishing 20+ file refactors cleanly inside fixed subscription quotas.

1. The Three Quota Black Holes in Multi-File Refactors

  1. Monolithic discovery + edit sessions: Asking one session to search the repo, edit 20 files, and run the test suite. Once context crosses 100K tokens, even renaming a single variable replays 100K+ tokens of prior turns.
  2. Unfiltered build and test logs: Dumping thousands of lines of bundler or test stack traces straight into chat history, where they get re-sent on every subsequent turn.
  3. Pausing across cache TTL boundaries: Leaving an 80K-token session idle for 30–60 minutes and resuming it forces the expired prefix to re-bill as fresh input.

2. The 3-Stage Disk-Checkpointed Workflow (Saves ~60% Quota)

Instead of storing refactor state in chat memory, persist it to a local REFACTOR_PLAN.md file and run short, disposable sessions:

Stage Session Scope Target Context Cap Action on Completion
Stage 1: Read-Only Inventory Scan affected modules and write the file checklist + type contracts to REFACTOR_PLAN.md <= 35K Tokens Close session immediately
Stage 2: Batched Execution Open a fresh session, read REFACTOR_PLAN.md, migrate 3–5 files, and check off items <= 45K Tokens Run /clear or start a new session per batch
Stage 3: Targeted Verification Run failing tests with tail -n 40 output filtering and fix edge cases <= 40K Tokens Delete temporary plan file once green

Because each batch starts around 15K–25K tokens instead of 120K+, your quota burn stays linear rather than exponential.

3. Pacing Around 5-Hour Rolling Windows and Weekly Caps

Before kicking off a major refactor, spend 30 seconds aligning your window schedule:

  • Anchor your 5-hour start time: Log your first prompt of the morning in the Claude 5-Hour Rolling Window Calculator. If your window opens at 09:00, it resets at 14:00—schedule heavy discovery and batch edits before 13:30 so your quota refreshes right when verification starts.
  • Guard your weekly daily budget: Enter your current usage percentage in the WhenReset Weekly Quota Planner. A 7-day cycle gives roughly 14.2% per day; if you cross 55% by Wednesday, switch to smaller batches or check API fallback costs in the AI Cost Calculator.
  • Instant error recovery: If you hit You've reached your limit or Context window is full, jump to the AI Coding Error Wiki for immediate recovery steps.

Frequently Asked Questions

Why does splitting a 15-file refactor into 3 sessions use less than half the quota of a single session?
In one continuous session, file #15 carries the full diffs and test logs of files #1 through #14 in its input context. Writing progress to a local Markdown checklist and starting fresh sessions keeps every turn lightweight.
How do I stop test runner loops from draining my quota?
Pipe only the last 30 to 40 lines of failure output to the agent instead of dumping thousands of lines of build logs. If the agent fails twice on the same error, compact or intervene manually.
What should I do if I hit the 5-hour cap with 10% of the refactor left?
Check your exact recovery timestamp with the 5-Hour Calculator (first message + 5h). Because state is saved in your local checklist file, you can also hand the final step seamlessly to Codex CLI or an API key.
⚡ T SALON AI CODING TOOLKIT