Last updated 13 October 2026
How to run Claude Code in WSL2
Preparing the WSL2 environment for the agent
Running the agent on Windows works best when you keep your code inside the Linux Subsystem. You should install Node.js using a tool like nvm within your Ubuntu or Debian shell. This ensures that the agent has the correct environment to run scripts and handle project files. Avoid installing Node.js on Windows and trying to call it from WSL2 because this causes path resolution errors that will break the tool logic.
The command to start the agent is claude. When you run this for the first time in a new directory, it will look for configuration files and local environment settings. If you have any trouble with the installation, run the claude doctor command. This tool checks your path and dependencies to ensure everything functions correctly. Keep your Linux distribution updated to avoid issues with the underlying system libraries that the agent relies on for network calls.
Handling authentication across the Windows boundary
When you start a session, the agent needs to verify your identity. Use the /login command to begin the process. Because WSL2 runs in a virtualized environment, it will attempt to open the authentication page in your default Windows browser. If the browser does not open automatically, the terminal will display a long URL. You can copy this link and paste it into any browser on your host machine to complete the login process manually.
Once you are logged in, your credentials stay active for your future sessions. If you need to switch accounts or clear your local tokens for security reasons, use the /logout command. The agent stores your global settings in the ~/.claude/settings.json file in your Linux home directory. This allows you to maintain a consistent identity even if you work across many different repositories within your WSL2 instance. You can check your current status and connection health at any time by typing /status.
Optimizing performance with the Linux file system
Performance is a common concern when using WSL2 for heavy development tasks. You should always store your project repositories in the native Linux file system, usually under a path like /home/username/projects. Do not run the agent on files located in /mnt/c or other Windows mount points. The agent uses the Read and Write tools frequently to analyze and modify your code. Accessing the Windows file system from Linux is significantly slower and can cause the agent to time out during large operations.
The agent respects your .gitignore file to keep the context clean and focused. It will not spend time reading build artifacts or node-modules unless you specifically tell it to do so. If you are starting a new project in a folder, run /init to set up the basic structure and project files. This helps the agent understand the boundaries of your work and where it should apply its changes. You can also use the /add-dir command to bring in specific directories that might be outside your current working path.
Directing the agent with CLAUDE.md files
The agent relies on a file called CLAUDE.md to understand your project rules and build steps. You should place this file in the root of your repository to provide high-level context. It should contain information about how to build the project, how to run tests, and any coding style preferences you have. In WSL2, this file is essential because it tells the agent which Bash commands are safe and necessary for your specific Linux environment.
You can also place a CLAUDE.md file in your home directory at ~/.claude/CLAUDE.md. This file applies to every project you work on across your entire machine. It is a good place to put general instructions about your preferred Linux tools or shell aliases. If you have specific subdirectories that need different rules, you can put a CLAUDE.md file in those folders too. The agent reads these files in order to decide how to use tools like Edit and Task.
Managing session context and costs
Every conversation with the agent fills up a context window with history and file content. In a complex WSL2 project, the agent might read many files using the Glob and Read tools. This can make the session slow or lead to higher token usage. Use the /cost command to see how much you have spent on the current session. If you want to see your total spend over time across all your work, use the /usage command to see the data.
When a session gets too long, the agent might struggle to remember earlier details from the conversation. Use the /compact command to summarize the current conversation and save space. This frees up space in the context window while keeping the important facts from the earlier parts of the chat. If you want to start a fresh conversation in the same folder without losing your configuration, use the /clear command. This is useful when you finish one feature and want to start another.
Working with multiple sessions in adhdTerminal
Managing multiple terminal tabs for different Claude Code sessions in WSL2 can become confusing very quickly. This is where adhdTerminal becomes the honest answer for a busy developer. It is a native app for Windows and macOS that runs many sessions side by side on a single wall. Each session appears as a tile with its own name, number, and color. You can see at a glance which WSL2 task is still working and which one is waiting for your input.
The app keeps your sessions organized even if you have to restart your computer. The tiles reopen in the same place and resume the same session automatically. This is much more efficient than manually searching through your shell history with Ctrl+R to find where you left off in your Linux terminal. You can give each tile a name that matches the feature you are building in WSL2. This visual overview helps you stay focused on the high-level progress of your project.
Using shell tools and subagents
The agent is powerful because it can use standard Linux tools directly from your shell. It uses Bash to execute commands and Grep to find strings in your code. It can also use the Glob tool to find files that match a specific pattern across your tree. If you need the agent to perform a repetitive task, you can create a custom command. These are markdown files that you save in the .claude/commands directory to extend the agent with your own logic.
For very complex tasks, you might use subagents to handle different parts of the work. You define these in markdown files inside the .claude/agents directory. Use the /agents command to see which ones are available for your current project. Subagents allow the main agent to delegate work to a specialized assistant. This is helpful in WSL2 when you are managing a large microservices architecture. One subagent could handle the frontend while another focuses on the backend logic.
Controlling permissions and safety modes
Safety is important when an agent can run Bash commands in your Linux environment. You can cycle through permission modes by pressing Shift+Tab inside the session. The default mode asks for your permission before the agent uses any tool. The acceptEdits mode allows the agent to write files but still asks before running commands. If you trust the agent completely in a safe environment, you can use the bypassPermissions mode for a faster experience.
You can fine-tune these permissions in your settings.json file found in the .claude directory. This file allows you to allow or deny specific tools based on your needs. For example, you might want the agent to use Read and Grep freely but always ask before using Write or Bash. You can also configure hook events like SessionStart or PostToolUse to run scripts at certain times. These settings give you full control over how the agent behaves within your WSL2 shell.
Mobile access and remote monitoring
Sometimes you need to step away from your desk while the agent performs a long task like a full refactor or a large test suite in WSL2. A free iPhone app mirrors the adhdTerminal wall over an end-to-end encrypted link. You can check the status of your Linux sessions from another room without staying glued to your monitor. If the agent hits a point where it needs your permission or a new prompt, you can send it from your phone.
This setup bridges the gap between your powerful WSL2 development environment and your mobile device. You do not need to stay tethered to your Windows machine to keep the project moving forward. The encrypted link ensures that your code and conversations stay private at all times. When the agent finishes its work, you will see the tile status change on your phone immediately. This allows you to manage your developer workflow with more flexibility and less stress.
Questions people ask
How do I handle file path differences between Windows and WSL2?
You should avoid using Windows paths like C:\Users inside your sessions. The agent works best when it stays within the Linux file system. Always run the agent from your home directory in WSL2 to ensure tools like Grep and Bash work as expected without path errors.
Can the agent access internet resources from inside WSL2?
Yes, the agent can use tools like WebSearch and WebFetch to get information. It uses the network connection of your WSL2 instance. If you have a proxy or a VPN on Windows, ensure it is configured to allow traffic from the Linux subsystem so the agent can reach the web.
What should I do if the agent becomes unresponsive in the terminal?
You can press the Escape key once to interrupt the current action. If you need to go back to a previous point in the conversation, press Escape twice. If the entire process hangs, use Ctrl+C to quit the session and restart it with the claude --continue command to pick up where you left off.
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.