{"slug": "when-to-start-a-new-claude-code-session", "title": "When to Start a New Claude Code Session", "summary": "A developer outlines a decision framework for when to start a new Claude Code session versus continuing or compacting context, based on observable task behavior rather than token counts. The guide includes a decision matrix for common symptoms like re-proposing rejected patches or mixing unrelated tasks, and recommends a post-compaction verification checklist before editing code.", "body_md": "Your test `test_empty_amount_returns_validation_error`\n\nis 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?\n\nRun 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.\n\nThere is no universal threshold based on tokens, messages, or tool calls. Use observable task behavior.\n\nFor this example:\n\n```\nImporting a row with an empty amount crashes.\nExpected: return a validation error and write no data.\n```\n\nRun the narrowest available test:\n\n```\nnpm test -- tests/import/empty-amount.test.ts\n```\n\nTwo outcomes are possible:\n\nRestarting before reproduction removes a history of guesses. It does not produce evidence about the cause.\n\nDifferent symptoms require different actions. Use this decision matrix:\n\n| Observable symptom | Likely cause | Recommended action |\n|---|---|---|\n| Session remembers symptom and proposes a new testable hypothesis | Clean context, normal progress |\nContinue: keep working in current session |\n| Context grew large due to command outputs/logs, but goal is clear | Noise accumulation in tool outputs |\nCompaction: run `/compact` command |\n| Session re-proposes rejected patch `Number(value | 0)` | |\n| Second task (e.g., README) mixed into dialogue | Context boundary drift |\nNew Session: split into separate branch |\n| Agent repeatedly reads files without new hypotheses or checks | Search loop / lost direction |\nNew Session: collect facts manually |\n\nThe `/compact`\n\ncommand 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.\n\nRun a mandatory post-compaction check:\n\n```\nWe just compacted context. Before editing code, answer 4 questions:\n1. What exact symptom are we fixing and what is the expected result?\n2. Which approach was already tested and why was it rejected?\n3. Which files are allowed to be modified?\n4. What single command will verify the next step?\n```\n\n`Number(value || 0)`\n\nand the constraint on public CSV format, continue in the same session.This is enough for the example bug:\n\n```\nGoal: empty amount returns a validation error and writes no data\nFiles: parser/amount.ts, tests/import/empty-amount.test.ts\nReproduction: npm test -- tests/import/empty-amount.test.ts -> failed\nRejected: Number(value || 0), because empty became zero\nConstraint: do not change the public CSV format\nOpen question: where to distinguish empty from a valid zero\nNext step: trace value from CSV parsing to the validation branch\n```\n\nDo not include API keys, cookies, `.env`\n\ncontents, personal data, or raw logs containing secrets. Keep the minimum error excerpt, timestamp, and path to a safely stored local log.\n\nGive the handoff to the new session and verify it against this checklist:\n\n```\nRead the handoff. Before editing, state:\n1) expected result;\n2) two target files;\n3) rejected approach and reason;\n4) next check command.\n```\n\nOnly after confirming all items should the new session read target files, make the smallest edit, and rerun the focused test.\n\nContinue 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.\n\nClarify the specification instead of restarting when the unresolved question is product behavior, such as whether empty `amount`\n\nshould be invalid or treated as zero. A clean context cannot make that owner decision.\n\nWhen 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.\n\n[Open the current BetterToken Claude Code guide](https://docs.bettertoken.ai/ai-tools/claude-code?utm_source=devto&utm_medium=syndication&utm_campaign=SEO-096&utm_content=kogda-nachinat-novuyu-sessiyu-claude-code), 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.\n\nRun 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`\n\n, write a short handoff and open a new session. Its first job is to restate the boundaries and complete one safe verification.\n\n*Originally published on the BetterToken blog.*\n\nBetterToken provides pay-as-you-go access to AI model APIs through\n\nOpenAI-compatible and Anthropic-compatible endpoints — useful if you are wiring\n\nClaude Code, Codex, or your own tooling to a custom base URL.\n\nSee the [docs](https://docs.bettertoken.ai/?utm_source=devto&utm_medium=syndication&utm_campaign=SEO-096&utm_content=when-to-start-new-claude-code-session) to get started.", "url": "https://wpnews.pro/news/when-to-start-a-new-claude-code-session", "canonical_source": "https://dev.to/bettertoken_ai/when-to-start-a-new-claude-code-session-1fl9", "published_at": "2026-08-20 14:59:23+00:00", "updated_at": "2026-08-20 15:15:32.240442+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-tools"], "entities": ["Claude Code"], "alternates": {"html": "https://wpnews.pro/news/when-to-start-a-new-claude-code-session", "markdown": "https://wpnews.pro/news/when-to-start-a-new-claude-code-session.md", "text": "https://wpnews.pro/news/when-to-start-a-new-claude-code-session.txt", "jsonld": "https://wpnews.pro/news/when-to-start-a-new-claude-code-session.jsonld"}}