When to Start a New Claude Code Session
Your test test_empty_amount_returns_validation_error is failing. Claude Code has edited the same handler twice, reopened the same files, and now proposes the first rejected patch again. Halfway through the conversation, you also asked it to update the README. Should you continue, trigger context compaction, or start a fresh session?
Run the focused test first. If no edit has been tested, the immediate problem is diagnosis, and a new session will only repeat the guesses. If the failure is reproducible and the facts are recorded, but Claude Code mixes the bug with documentation or forgets a rejected result, choose the right context management tool.
There is no universal threshold based on tokens, messages, or tool calls. Use observable task behavior.
1. Reduce the task to one symptom
For this example:
Importing a row with an empty amount crashes.
Expected: return a validation error and write no data.
Run the narrowest available test:
npm test -- tests/import/empty-amount.test.ts
Two outcomes are possible:
- The test does not exist yet or checks different behavior. Stay in the current session and clarify the specification or create a reproducible test first.
- The test reliably reproduces the crash. Now evaluate whether the session still retains verified facts and moves the task forward.
Restarting before reproduction removes a history of guesses. It does not produce evidence about the cause.
2. Decision table: Continue, Compact, or New Session
Different symptoms require different actions. Use this decision matrix:
| Observable symptom | Likely cause | Recommended action |
|---|---|---|
| Session remembers symptom and proposes a new testable hypothesis | Clean context, normal progress | Continue: keep working in current session |
| Context grew large due to command outputs/logs, but goal is clear | Noise accumulation in tool outputs |
Compaction: run /compact command |
| Session re-proposes rejected patch `Number(value | 0)` | |
| Second task (e.g., README) mixed into dialogue | Context boundary drift | New Session: split into separate branch |
| Agent repeatedly reads files without new hypotheses or checks | Search loop / lost direction | New Session: collect facts manually |
3. How to use Compaction and verify it
The /compact command is useful when the agent is on the right track but the context is overwhelmed by large terminal outputs or intermediate diffs. However, never let the agent write code immediately after compaction.
Run a mandatory post-compaction check:
We just compacted context. Before editing code, answer 4 questions:
1. What exact symptom are we fixing and what is the expected result?
2. Which approach was already tested and why was it rejected?
3. Which files are allowed to be modified?
4. What single command will verify the next step?
- If the agent correctly recalls the rejected
Number(value || 0)and the constraint on public CSV format, continue in the same session. - If the agent forgot the rejection reason or expanded file boundaries, compaction erased critical constraints. Start a fresh session with a handoff.
4. Build a factual handoff
This is enough for the example bug:
Goal: empty amount returns a validation error and writes no data
Files: parser/amount.ts, tests/import/empty-amount.test.ts
Reproduction: npm test -- tests/import/empty-amount.test.ts -> failed
Rejected: Number(value || 0), because empty became zero
Constraint: do not change the public CSV format
Open question: where to distinguish empty from a valid zero
Next step: trace value from CSV parsing to the validation branch
Do not include API keys, cookies, .env contents, personal data, or raw logs containing secrets. Keep the minimum error excerpt, timestamp, and path to a safely stored local log.
5. Recovery checklist for the new session
Give the handoff to the new session and verify it against this checklist:
Read the handoff. Before editing, state:
1) expected result;
2) two target files;
3) rejected approach and reason;
4) next check command.
- [ ] New session preserves the distinction between empty and zero.
- [ ] Rejected patch is not resurrected.
- [ ] No unrelated tasks (like README) leaked into the scope.
- [ ] Agent names the exact command for the next verification.
Only after confirming all items should the new session read target files, make the smallest edit, and rerun the focused test.
When to keep the current session
Continue when the session remembers the symptom, uses the last test result, and can name the next check. A long conversation can remain useful while each action reduces uncertainty.
Clarify the specification instead of restarting when the unresolved question is product behavior, such as whether empty amount should be invalid or treated as zero. A clean context cannot make that owner decision.
Keep API configuration separate from task state
When Claude Code uses a separate API provider, do not copy keys or changing configuration fields into the handoff. BetterToken supports Claude Code through an Anthropic-compatible API with the user's own account and key. This is separate API access, not a replacement for Claude.ai or Claude Max.
Open the current BetterToken Claude Code guide, verify the current Base URL, key group, and model, then run a small test request. The handoff only needs to say that the setup was checked; it must not contain secret values.
The one-minute decision
Run the focused test and name the next expected result. If the symptom is reproduced, but the session repeats rejected actions, mixes tasks, or loses constraints after /compact, write a short handoff and open a new session. Its first job is to restate the boundaries and complete one safe verification.
Sources
Originally published on the BetterToken blog.
BetterToken provides pay-as-you-go access to AI model APIs through
OpenAI-compatible and Anthropic-compatible endpoints — useful if you are wiring
Claude Code, Codex, or your own tooling to a custom base URL.
See the docs to get started.
Top comments (0)