Last updated 13 October 2026
Where to find Claude Code session data on disk
The primary location of the claude directory
You need to find your Claude Code session data because a session crashed or you want to back up your work. This tool does not store your data in a hidden cloud database that you cannot access. It saves everything locally on your computer. On macOS and Linux systems, you will find the primary data folder in your home directory under a hidden directory named .claude. If you are on a Windows machine, this folder usually sits in your user profile folder at the same path.
This global folder serves as the central hub for the command line coding agent. It contains your authentication state, global settings, and the history of the sessions you have initiated. When you run the claude command, the agent checks this directory to understand who you are and what you have done previously. It is the first place to look if you need to inspect the underlying data that powers your interactions.
Inside this global directory, you will find a settings.json file. This file stores your global preferences that apply across every project on your machine. You can modify this file directly or use the /config command within a session to change how the agent behaves. Understanding the structure of this folder helps you manage your local environment and ensures you know exactly where your information lives.
Mapping session history to your local files
Every time you start a conversation, the agent creates a unique record of that exchange. You do not have to guess which session is which by looking at raw file names alone. You can use the claude --resume command, or simply -r, to see a list of your previous sessions. This command pulls from the metadata stored in your home directory and presents a readable list of your past work. You can then pick a session to continue exactly where you left off.
The actual content of these sessions includes the prompts you wrote and the responses the agent provided. It also tracks the tools the agent used, such as Read, Write, or Edit. This history is vital for the context of your project. If a session becomes too large and consumes too much memory or becomes expensive, you can use the /compact command. This summarizes the session so far and frees up space in the context window while preserving the essential points of the conversation in the stored data.
If you want to start fresh in a specific directory without losing your global history, the /clear command is the right choice. It wipes the current session context but does not delete the history files from your disk. This allows you to maintain a clean slate for a new task while keeping the old data available if you ever need to use the claude -r command to look back at a previous solution.
Project level instructions in the root directory
Claude Code looks for a specific file named CLAUDE.md to understand the rules of your project. This file should sit in the root of your repository. It is a plain text file where you define how the agent should behave, what code style to use, and how to run tests. Because this file lives in your project folder, it is easy to find and edit with any text editor. It is often the most important piece of data for ensuring the agent produces high quality code.
The agent also supports hierarchical instructions. If you have a large project with different rules for different modules, you can place a CLAUDE.md file in a subdirectory. The agent will respect the instructions specific to that part of the file tree. There is also a global version of this file located at ~/.claude/CLAUDE.md. This global file applies to every project you work on, which is perfect for setting your personal coding preferences that never change.
Managing these instructions is a manual process. You write them, and the agent reads them. When the agent uses the Read tool on your project, it often starts by looking for these files to orient itself. If you find the agent is making the same mistakes repeatedly, update the CLAUDE.md file in your project root. This acts as a persistent memory that survives between different sessions and even after you run the /clear command.
Configuration files for local and global settings
Settings for the command line coding agent exist in three distinct layers. First, the ~/.claude/settings.json file holds your global configuration. Second, you can create a .claude/settings.json file within your specific project folder for project-wide defaults. Third, you can use .claude/settings.local.json for your own overrides that you do not want to commit to version control. This system gives you granular control over how the agent operates in different environments.
These files control things like permission modes. You can set the agent to default, acceptEdits, plan, or bypassPermissions mode. You can also define specific permissions for individual tools in the settings.json file. For example, you might want to allow the Read tool to run without asking but require a prompt before the agent uses the Write or Bash tools. These choices are saved in the JSON files mentioned above.
If you are unsure if your settings are correct, run the claude doctor command. This tool checks your installation and your configuration files for errors. It will tell you if a file is missing or if the agent cannot access a specific directory. This is the fastest way to debug issues related to session data storage or permission errors on your local machine.
Visualizing your work with adhdTerminal
When you work on many projects at once, managing multiple sessions through the terminal can become difficult. Searching through history with Ctrl+R or listing sessions with claude -r takes time. This is where adhdTerminal provides a visual solution. It is a native app for macOS and Windows that runs many Claude Code sessions side by side. Each session appears as a tile on a wall, showing you exactly which tasks are active and which are idle.
The app tracks the state of your sessions and displays the last few exchanges from the conversation directly on the tile. This means you do not have to dig through your ~/.claude folder to find out what happened in a previous session. The tiles are persistent, so they reopen in the same place after a restart. This visual organization helps you keep track of multiple work streams without getting lost in the command line.
Using a tool like adhdTerminal also gives you the benefit of a mobile mirror. A free iPhone app connects to your wall over an end to end encrypted link. You can see the status of your long running tasks or send a new prompt to a specific session while you are away from your desk. It costs 99 dollars once and offers a 7 day free trial without an account, making it a simple way to manage the data and sessions the agent generates.
Custom commands and subagent data storage
You can extend the functionality of the agent by adding custom slash commands. These are stored as markdown files in the .claude/commands directory within your project. Each markdown file defines a new command that you can trigger inside a session. This allows you to automate repetitive tasks or create complex workflows that are specific to your codebase. These files are part of your project data and can be shared with your team.
Similarly, you can define subagents in the .claude/agents directory. These are also markdown files that describe specific roles or personas the agent should adopt for certain tasks. When you use the /agents command, the agent looks in this folder to see what specialized assistants are available. This local storage approach ensures that your custom logic stays with the project code.
If your project uses Model Context Protocol servers, the configuration for those servers is kept in a file named .mcp.json. You can manage these servers using the claude mcp command or the /mcp slash command within a session. This file tells the agent how to connect to external data sources or tools, further expanding what it can do with your local files and external APIs.
Monitoring your local costs and usage
Every session you run incurs costs based on the number of tokens used. The agent keeps track of this data locally so you can monitor your spend. Use the /cost command to see the estimated cost of the current session. If you want to see your total spend over time across all sessions, use the /usage command. This information is pulled from the local logs and metadata stored in your home directory.
The agent also tracks the number of tokens currently in your context window. As you read more files with the Read or Glob tools, the context fills up. You can check the current status with the /status command. This helps you decide when to use /compact or /clear to manage the performance and cost of your session. All of this tracking happens on your machine, giving you a clear view of your resource consumption.
Recovering and exporting your session data
If you need to move your work or share a transcript, you can use the /export command. This takes the current session data and saves it to a file. This is useful for documentation or for moving a complex conversation into a different tool. It extracts the raw history from the local storage and puts it into a format you can easily share or archive.
For those who prefer to navigate history manually, the agent supports keyboard shortcuts within the interactive interface. Pressing Escape twice allows you to go back to earlier messages in the current session. If you need to stop a long running process, a single press of the Escape key will interrupt the agent. These interactions are reflected in the session logs, ensuring your local data accurately represents the state of the work.
Because all this data is local, you have full control over it. You can back up the ~/.claude directory to secure your history or delete specific project folders to remove local settings. The agent respects your .gitignore file, so it will not attempt to read or track files you have excluded from your repository. This ensures that your private data stays private while the agent helps you build your application.
Questions people ask
Where is the global configuration file located on my computer?
The global settings for the command line coding agent are stored in your home directory at ~/.claude/settings.json. On Windows, this is typically found in your user profile folder. You can edit this file to change global permissions or default behaviors for the agent.
How can I see how much I have spent on my sessions?
You can view your spending by using the /cost or /usage commands inside any active session. The /cost command shows the price of the current session, while /usage provides a broader view of your total token consumption and estimated costs. This data is calculated based on the logs stored in your local .claude directory.
What happens to my stored sessions when I run the update command?
Running the 'claude update' command replaces the agent's executable with the latest version but does not delete your session data. Your history in ~/.claude and your project specific CLAUDE.md or settings files remain intact. You can still use 'claude --resume' to access your old conversations after the update is complete.
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.