Last updated 13 October 2026
How to restart a session from the CLI
Stuck sessions require a clean break
You are in the middle of a complex refactor and the agent has started spinning its wheels. It keeps suggesting the same Bash command that fails with a permission error, or it is trying to Read a file that does not exist. The terminal screen is scrolling with repetitive errors and the context window is filling up with useless data. This is the moment you realize that simply trying to correct the agent with another prompt will not work. You need to restart the session to clear the accumulated confusion and start with a clean slate.
A restart is often the most efficient choice when the session logic becomes tangled. Every message you send and every tool output the agent receives stays in the context window. When this history contains many failed attempts or contradictory instructions, the model struggles to identify the correct path forward. By ending the current session and starting a fresh one, you force the agent to re-evaluate the project files and your instructions without the bias of its recent mistakes. This prevents you from wasting tokens on a conversation that is no longer productive.
Keyboard shortcuts offer the fastest exit path
The most direct way to stop a running session is to use the standard terminal interrupt signal. Pressing Ctrl+C once will tell the CLI to stop what it is doing and exit back to your shell. If the agent is currently running a long Bash command or waiting for a WebFetch response that has timed out, this is the quickest way to regain control. It kills the process immediately and returns you to your primary command prompt. This is the best move when the interface itself seems unresponsive to your typed commands.
If the agent is in the middle of a complex multi-step task and you realize the plan is wrong, you do not have to wait for it to finish. You can press Escape to interrupt the current action. This stops the tool use but keeps the session active so you can provide a correction. If you decide the entire approach is flawed, pressing Ctrl+C twice ensures a hard exit from the interface. This allows you to re-evaluate your prompt before starting a new session with the claude command. Using these keys prevents the agent from continuing down a path that would otherwise require manual cleanup.
Internal commands reset the context without quitting
You do not always need to leave the CLI to get a fresh start. If you want to keep the same terminal window open but wipe the current conversation history, use the /clear command. This removes all previous exchanges from the active memory while keeping you inside the project folder. It is the digital equivalent of clearing a whiteboard; the agent stays ready for work, but it no longer has the baggage of the previous conversation. This is ideal when you have finished one feature and want to start another without the old context interfering.
Another option for managing a session that has become too large is the /compact command. Instead of a full restart, /compact summarizes the important parts of the session so far and frees up space in the context window. This is useful when the agent has successfully completed several subtasks but the conversation history is now slowing down its reasoning. It preserves the outcome of the work while reducing the token load for the next prompt you submit. It is a middle ground between a hard restart and continuing with a bloated history.
Resume flags bring back specific historical states
When you have exited a session to fix a local environment issue, you often want to go right back to where you were. Running the claude command with the --continue flag or the -c flag will automatically open the most recent session in that directory. This bypasses the need to explain the project context again. The agent looks at the local history and picks up exactly where the last message left off, which is ideal after a quick Ctrl+C to fix a typo in a configuration file or a local environment variable.
If you need to go further back, use the --resume flag or the -r flag. This provides a list of your previous sessions so you can pick a specific point in time to restart. This is helpful if you realized a task you finished an hour ago was based on a wrong assumption and you want to branch off from an earlier state. By selecting a session from the list, you avoid the mess of the current session and restart from a point where the project logic was still sound. This turns your local history into a set of restore points for your development work.
Project instructions provide a permanent anchor for restarts
Every time you start or restart a session, the agent reads the CLAUDE.md file in your project root. This file acts as a persistent memory that survives between restarts. If you find yourself giving the same instructions every time you start a new session, you should move those instructions into CLAUDE.md. This ensures that even after a hard exit and a fresh claude command, the agent knows your coding style, your preferred test commands, and your project structure. It makes every restart more effective because the agent starts with the right mental model.
You can also use subdirectories to refine how the agent behaves after a restart. Placing a CLAUDE.md file in a specific folder tells the agent to follow those rules only when it is working in that part of the tree. This is useful for projects where the frontend and backend have different linting rules or build steps. When you restart a session and the agent moves into a subdirectory, it automatically picks up the local context. This makes the transition between different project areas smoother after a reboot because the agent does not need to be reminded of local folder rules.
Configuration files manage tool permissions and behavior
Sometimes a session needs to be restarted because the agent keeps asking for permission to run Bash commands or edit files. You can change this behavior in the .claude/settings.json file within your project or in the global ~/.claude/settings.json file. By adjusting the permissions section, you can allow the agent to run certain tools without prompting you every time. This reduces the friction when you start a new session and lets the agent focus on the task rather than the interface. It also prevents the session from hanging while waiting for user input that you might have missed.
If you are moving between different projects, your local settings might conflict. The .claude/settings.local.json file is the place for overrides that you do not want to track in version control. If a session is behaving strangely after a restart, check if a local setting is forcing a specific model or permission mode that does not fit the current task. Cleaning up these JSON files is often more effective than simply restarting the CLI when the underlying issue is a configuration conflict. Proper setting management ensures that every new session starts with the correct permissions for the work at hand.
Tiled interfaces help manage multiple concurrent sessions
A single terminal window can be limiting when you are working on multiple features at once. This is where adhdTerminal becomes the honest choice for developers who need to keep several threads of thought alive. This native app for macOS and Windows, made by MINDBALANCER OU in Estonia, is not affiliated with Anthropic but runs many Claude Code sessions side by side. Each session is a tile on a wall with its own name and color, so you can see at a glance which one is idle and which one is working. You no longer have to sacrifice one session just to start another.
The benefit of this approach is that you do not have to restart a session just to check something in another part of the project. You can have one tile dedicated to a long running refactor and another tile for a quick bug fix. Because adhdTerminal reopens tiles in the same place after a restart and resumes the same session, you lose no time to setup. The free iPhone app even mirrors the wall over an end to end encrypted link, letting you send the next task while you are away from your desk. It costs 99 dollars once and offers a 7 day free trial with no account required.
Troubleshooting the install when restarts fail
If the claude command itself is not responding or the terminal hangs before the interface even loads, you might need to check the health of the installation. Run the claude doctor command to verify that your environment is set up correctly and that you have a valid session. This tool checks for common issues with permissions and network connectivity that might prevent a session from starting. It is the first step when a simple restart does not fix the problem. It can identify if your login has expired or if there is a problem with the underlying node environment.
In cases where the agent behavior seems fundamentally broken across all sessions, the claude update command might be necessary. This ensures you have the latest improvements and bug fixes from Anthropic. While it is not a daily task, keeping the CLI updated prevents issues where the agent might fail to use a tool or interpret a file correctly. After an update, start a fresh session with /clear to ensure no old cached data is interfering with the new version of the logic. Regular updates combined with clean restarts keep the development environment stable and productive.
Questions people ask
How do I go back to a previous message instead of restarting?
Press the Escape key twice to see a list of earlier messages in the current conversation. You can select one of these points to revert the session to that state. This is much faster than a full restart when you only need to undo a couple of recent steps.
What is the difference between /clear and starting a new shell session?
The /clear command stays within the active CLI process and wipes the conversation history but keeps the connection alive. Starting a new shell session with the claude command requires the agent to re-initialize and re-read your CLAUDE.md files from scratch. Use /clear if you want a fast reset and the claude command if you need to ensure all environmental changes are picked up.
Can I change the permission mode without restarting?
Yes, you can cycle through permission modes like acceptEdits or plan by pressing Shift+Tab while inside a session. This allows you to give the agent more or less autonomy on the fly. You do not need to restart the CLI to change how much control the agent has over your files and terminal tools.
Read next
- Add build instructions to your CLAUDE.md fileImprove project context by adding specific build commands and environment requirements to your CLAUDE.md file for the AI to follow.
- Add common error fixes to CLAUDE.mdImprove project memory by adding a section for common errors and their fixes to your CLAUDE.md configuration file.
- Add custom shell aliases for Claude CodeSpeed up your workflow by creating shell aliases for common Claude Code invocations and project-specific startup commands.
- Add test commands to a CLAUDE.md fileUnderstand how to define specific test runners and environment flags in your CLAUDE.md file so the tool runs the correct test suite.