Token & Session-Burnout Habits for AI Code Agents

What Problem This Solves

Three concrete symptoms, not an abstract fear of "spending tokens":

• Session-memory files grow without limit. If you keep project state in a file like CLAUDE.md/CONTEXT.md/NOTES.md, reading it in full at the start of every session burns context budget before you've even touched the real problem.
• The tool's auto-compact fires late (around 95% of the window). By then the tool decides what to drop, and it systematically keeps mundane output while discarding the reasoning that actually mattered.
• Long sessions re-derive decisions already made in the same conversation, lose track of what was decided ten minutes ago, or drift from the original request. That's context-budget degradation, not "the model got lazy."

This guide attacks the two levers that are actually controllable: tokens per task (well-scoped context) and unnecessary tasks (the Restart Rule, one chat = one task) — not the price per token or the number of users.

L0 / L1 / L2 Habits (Abstract-First)

Load information in layers, from less to more detail, and only go deeper once something actually matched the current task.

Writing rule: every new entry in a state/memory file starts with a bold L0 — one sentence a future session can rank without reading the body. Never open an L2 file because "the name sounds relevant": check its L0/L1 first.

Checkpoint at ~60%, Not ~95%

Most agent tools' auto-compact fires around 95% of capacity — by then the tool decides what to drop, keeping mundane output and discarding the reasoning. Intervene earlier, while the agent still has control:

• At ~60% of the session's practical budget (a "this is getting heavy" signal, not an exact token counter).
• Stop at a clean point, not mid-edit.
• Write the state to a file: what was done, what's left, what decision is pending. That's the real checkpoint, not the chat's own memory.
• If a logical unit of work is finished and the code passes its quality gate, commit.
• Say it explicitly: "I recommend a fresh chat from here — the state is saved in [file]/git log."

Explicit handoff: for large or multi-stage work, write the checkpoint as a clearly marked block ("HANDOFF" or similar) with the reference plan, what's done, what's left, and what human confirmation is pending.

Stop Arguing, Respec Instead

If the agent is stuck, produces output that doesn't work, or you find yourself arguing the same point twice — stop arguing. Rewrite the spec (what's being asked, what constraints, what acceptance criteria) and regenerate cleanly. Arguing spends tokens re-deriving; a clean respec spends tokens moving forward.

Corollary: if you correct the same thing twice, that's the signal to write it once as a permanent rule, not to keep correcting it by hand every time.

Summary Only, Never the Transcript

Don't paste chat transcripts into durable state/memory files. Writes are summary-level: rationale + outcome, never the full conversation. Every new entry carries its bold L0 and, below it, the minimum needed for another session to understand what happened and why, without reading the original chat.

Escalate on Anomaly, Not on Schedule

Default: autonomous — the agent keeps working and commits without asking permission at every step. Interrupt the human only on a concrete signal:

• the same file rewritten more than ~5 times in a row,
• the build/typecheck fails 3+ times consecutively,
• the tool-call count is roughly 2x the expected baseline for that kind of task.

Don't add a "should I continue?" checkpoint at a fixed number of turns regardless of session health — the goal is for the flow to run mostly unattended, and for an interruption to signal something real.

Mechanical Work Is a Script, Not a Session

Creating a new copy/variant of a project (duplicating a folder, renaming identifiers, registering paths across several files) is mechanical work. It's better handled with a shell script than as open-ended, turn-by-turn agentic editing. Only the real design/logic changes inside the new copy need a reasoning model's attention.

Intent note: the moment work starts on a new fork or scoped derivative, write a short note (~5 lines): what changes this round, what stays untouched, and one line answering "fork on disk, or a git branch?" — a full fork only if it needs to run live alongside another version or be published separately; otherwise a branch, deleted once the learning is extracted.

Checkpoint Gated on Build/Typecheck

Commit at the end of the scaffold step, before starting feature edits, and at every natural subtask boundary — but only if the current state passes the project's build/typecheck/tests. If it doesn't pass, commit to a working branch, never to main with broken state.

Only for Large Work

Write a short plan and get a one-line approval before scaffolding a new variant, preparing a reduced-scope clone, or any refactor touching multiple files. Skip this ceremony for single-file tweaks — it isn't worth it below roughly ~15 expected tool calls.

Soft-Exclude Large, Superseded Trees

Distinguish two levels of exclusion: hard (the agent can't read it even with an explicit mention — binaries, installed dependencies, build artifacts) and soft (out of search by default, but reachable with an explicit mention — superseded versions still useful as historical reference). When something becomes formally superseded, move it to soft exclusion in the same session, instead of leaving it competing for search space indefinitely.

A Manual Export Bridge, Never a Database

If a project needs a knowledge layer outside the repo (an Obsidian-style note, a wiki), treat it as a manual, on-request bridge only — never automatic sync, never a source of truth. Export only when explicitly asked, carry minimal metadata, and keep it hand-curated: no relationship queries unless a real index structure exists. The repo's own state files and git history remain the source of truth.

What Not to Do

• Don't open every file "just in case" — use a "where to look" routing map if one exists.
• Don't paste chat transcripts into durable memory files.
• Don't silently archive a large state file — flag the recommendation and wait for confirmation.
• Don't use broad git commands (checkout/reset) on shared work to fix a wrong turn — restore only the agent's own last edit with a targeted patch.
• Don't treat an Obsidian/wiki-style export as a database or source of truth.
• Don't add a "should I continue?" checkpoint at a fixed number of turns.

How to Install This in Another Project

• Copy the Markdown file into the new repo (e.g., docs/token-burnout-optimization.md).
• If the agent supports "always-apply" per-file rules, create a summarized 20–30 line version that points to this doc for detail — don't duplicate the full content there.
• If the agent supports "skills" or longer on-demand documents, move the full detail there and leave only the summary in the always-apply rule.
• Adapt the session-memory filenames to the project's actual scheme — none of this requires a particular filename.
• If multiple agents/tools work on the same repo, point all of them at the same doc instead of each keeping its own abbreviated version.