Context Window Strategy for Long-Running Agents

Context exhaustion is the #1 failure mode for long-running agents. Here's how to design around it.

The Context Problem

Claude Code has a finite context window. In a long-running session — hours of coding, many files read, many outputs generated — the context window fills up. When it does, either the agent stops working or (with amux) it auto-compacts. Auto-compact helps, but poorly structured sessions lose important context during compaction and produce lower-quality output afterward.

The solution is to design tasks and sessions so that context usage is efficient from the start — not treating compaction as a fix for poor session hygiene.

Task Scoping Rules

• One task per session: Don't ask one agent to implement a feature, write tests, and update docs. Give those to three agents. Each agent's context stays focused on one problem.
• Specify files explicitly: "Read src/api/users.ts and src/models/user.ts" is better than "look at the user-related code." Agents that search broadly consume more context finding relevant files.
• Set scope boundaries: Tell the agent what to ignore. "Don't read test files unless needed for understanding the interface" prevents unnecessary context loading.
• Short task horizons: Tasks that take 30 minutes are better than tasks that take 3 hours. Short tasks complete within one healthy context window. Long tasks risk degradation.

amux's Auto-Compact

When amux detects context exhaustion, it:

1. Sends /compact to summarize the conversation
2. Monitors for the summary confirmation
3. Resumes the agent

This keeps agents running, but compacted context loses detail. After a compaction, agents are working from a summary, not the full conversation. Quality can drop. The goal is to design tasks that complete before compaction is needed.

Context Checkpointing Patterns

For genuinely long tasks that can't be broken up:

• Commit frequently: Instruct agents to git commit after each meaningful unit of work. Commits externalize progress so context can be cleared more aggressively.
• Write progress notes: Have the agent write a PROGRESS.md file summarizing what it's done and what's left. This note survives compaction and re-orients the agent.
• Staged handoffs: Break a large task into sequential sub-tasks on the board. When one agent completes its sub-task, a fresh agent starts the next with a clean context window.

git clone https://github.com/mixpeek/amux && cd amux && ./install.sh
amux register myproject --dir ~/Dev/myproject --yolo
amux start myproject
amux serve  # → https://localhost:8822