Try free

Last updated 13 October 2026

Running Claude Code on Windows machines

Setting up the Windows terminal environment

Windows developers often struggle with terminal tools that assume a Unix environment or a specific shell configuration. You need a modern terminal like Windows Terminal or a configured PowerShell environment to see the terminal colors and text formatting correctly. Claude Code runs as a command line agent inside your existing terminal and interacts with your local files to perform coding tasks. You must have Node.js installed on your system and available in your environment path before you can begin the installation process.

Verify your setup by running a simple command to check your node version. If your terminal does not recognize the command, you may need to restart your computer or manually add the installation folder to your system environment variables. Using a high-contrast theme in your terminal can help you distinguish between the agent output and your own typed commands. Once your environment is ready, you can move on to the actual installation of the coding agent.

Installing and authenticating the agent

You install the agent using your preferred package manager to make the "claude" command available globally on your Windows machine. Once the installation finishes, the first action you must take is to authenticate your session by typing /login into the prompt. This command generates a temporary link that opens in your default web browser where you can sign in to your account. After you complete the process in the browser, the terminal will update to show that you are successfully logged in and ready to work.

The /login command is essential because it links your local terminal session to the cloud services that power the agent logic. If you ever need to switch accounts or secure your machine, use the /logout command to remove your credentials from the local session. You can also use "claude doctor" at any time to verify that your authentication token is still valid and that your network connection is stable. This initial setup only needs to happen once per machine unless you manually clear your settings.

Defining project rules with markdown files

Project context is the most important factor for getting good results from an automated coding agent. You should create a file named CLAUDE.md in the root directory of your repository to store specific instructions for the agent. This file usually contains details about your preferred coding style, how to run your build scripts, and which test commands to use for verification. The agent uses the Read tool to scan this file whenever it starts a new task in that folder, ensuring it follows your project standards without being told every time.

If you have a large project with different rules for different modules, you can place a CLAUDE.md file in any subdirectory. The agent will prioritize the instructions in the local directory over the ones in the root. For rules that you want to apply to every single project on your Windows machine, you can create a global configuration file at ~/.claude/CLAUDE.md. This is a great place to put your general preferences, such as a preference for specific libraries or a requirement to always write comments in a certain format.

Controlling permissions and tool access

Security is a primary concern when giving a tool the ability to run commands and edit files on your Windows machine. You can cycle through different permission modes by pressing Shift+Tab while the agent is active. These modes include default, acceptEdits, plan, and bypassPermissions. In the default mode, the agent will ask for your explicit approval before it uses any tool that changes your files, such as the Write or Edit tools. This gives you a chance to review every proposed change before it hits your disk.

You can further customize these restrictions by editing the .claude/settings.json file in your project or your home directory. This file allows you to set specific permissions for individual tools like Bash, Grep, or WebFetch. For example, you might want to allow the Read tool to work without asking while requiring a confirmation for every Bash command. If you share a project with a team, you can check the .claude/settings.json file into your version control system to ensure everyone on the team has the same safety boundaries. Use .claude/settings.local.json for any personal overrides that you do not want to share with others.

Working across PowerShell and WSL boundaries

The agent uses the Bash tool to execute commands on your system, which behaves differently depending on your Windows setup. If you run the agent in a standard PowerShell window, the Bash tool will actually execute commands through your Windows shell environment. This means you should use Windows-compatible commands or ensure that you have a compatibility layer like Git Bash installed and configured. If you prefer a full Linux experience, you can run the agent inside the Windows Subsystem for Linux, where it will have access to a standard Linux terminal.

When switching between PowerShell and WSL, be careful about file paths and line endings. Windows uses different conventions for paths than Linux does, and the agent might get confused if you move a session between environments. It is usually best to pick one environment for a specific project and stay with it. If you need to debug terminal issues specific to Windows, use the /terminal-setup command to adjust how the interactive elements and special characters are rendered in your shell.

Running multiple sessions for different tasks

Developers often work on multiple features or bugs at the same time, which requires switching context frequently. You can use the "claude --resume" command to see a list of your previous sessions and select one to continue exactly where you left off. If you only care about the most recent thing you were doing, "claude --continue" or the -c flag will reopen that session immediately. This saves you from having to explain the problem again or wait for the agent to re-read all your project files.

Managing many open terminal windows for different tasks can quickly become overwhelming on a single monitor. The adhdTerminal app provides a way to handle this by displaying your Claude Code sessions as colored tiles on a wall. Each tile shows the name of the project, the current status of the agent, and the last few lines of the conversation. This visual overview makes it much easier to keep track of several long-running tasks without constantly clicking through your taskbar to find the right window.

The wall of tiles can also be mirrored to a free iPhone app over an encrypted link. This allows you to check on a long-running task or send a new prompt to one of your Windows sessions while you are away from your desk. You can see which tiles are busy and which are idle directly from your phone, providing a convenient way to manage your development pipeline without being tethered to your workstation. You get a twenty four hour free trial to see if this workflow fits your needs.

Managing context window and session costs

Every interaction with the agent adds to the context window, which is the total amount of information the agent can remember at one time. If your conversation becomes very long, the agent might start to run out of space or become slower to respond. You can use the /compact command to create a summary of the session so far and clear out the detailed history. This keeps the agent focused on the current task while preserving the important decisions made earlier in the session.

Running a powerful coding agent involves costs based on the number of tokens you use. You can monitor your spending by using the /cost command inside any active session to see the price of the current conversation. For a broader view of your usage over time, the /usage command shows your daily limits and total consumption. Monitoring these figures helps you decide when to use /clear to start a fresh session or when to use /compact to keep a single session running efficiently without wasting money on redundant data.

Maintaining the installation and fixing errors

To ensure you have access to the latest features and security updates, you should periodically run "claude update" in your terminal. This command checks for new versions of the agent and installs them automatically, ensuring your local environment stays current. If you notice the agent making mistakes or if the tools stop working as expected, the "claude doctor" command is your first line of defense. It runs a series of diagnostic tests to identify problems with your Node.js installation, your network, or your local configuration files.

If the agent gets stuck or starts producing incorrect output, you can use the Escape key to interrupt its current task. Pressing Escape twice will open a menu that allows you to go back to earlier messages in the conversation and try a different approach. For more severe issues, you can use /bug to report a problem to the developers. Remember to use /help whenever you are unsure about a specific command or need to see the full list of available slash commands and their functions.

Advanced automation with hooks and subagents

If you want to customize your workflow, you can use hook events to trigger actions during a session. Events such as SessionStart, UserPromptSubmit, and PreToolUse allow you to run scripts or log data at specific points. You can also define specialized subagents by creating markdown files in the .claude/agents directory. Use the /agents command to see your available subagents and delegate specific tasks to them based on their defined expertise.

For connecting to external data or services, use the "claude mcp" command to manage your Model Context Protocol servers. These are configured in the .mcp.json file and allow the agent to interact with tools outside of its standard set. You can also create your own custom slash commands by adding markdown files to the .claude/commands folder. This level of customization allows you to tailor the agent to the specific needs of your Windows development environment and your team's unique workflow.

Questions people ask

How can I stop the agent if it starts making a mistake?

You can press the Escape key once to immediately interrupt the agent and stop it from continuing its current task. If you need to go back further, press Escape twice to see a list of previous messages and revert the conversation to an earlier point.

Is there a way to search through my command history in the terminal?

Yes, you can use Ctrl+R to search through your shell history directly in your terminal while the interactive session is active. This allows you to quickly find and reuse previous prompts or commands without retyping them.

How do I manage permissions for many tools at once?

Use the Shift+Tab key combination to cycle through global permission modes like bypassPermissions or acceptEdits. For more granular control, you can modify the permissions section in your .claude/settings.json file to allow or deny specific tools by default.

Read next

More on claude code basics·All posts