Anthropic’s Claude Code, a terminal-based agentic coding tool, is now available across the three major developer operating systems—macOS, Linux, and Windows (via WSL)—offering AI-assisted development directly inside the command line. The agent, which debuted as a research preview in October 2024, lets developers chat with Claude to edit code, run shell commands, manage files, and handle entire Git workflows with full context of their projects. This cross-platform reach means Windows users can tap into the same agentic capabilities long enjoyed by macOS and Linux developers, while keeping local code secure and under version control.

Setting up Claude Code is straightforward but requires careful attention to API key management and environment hygiene. The agent runs entirely on your machine except for API calls to Anthropic’s servers, so protecting your key and understanding what files Claude can access are essential steps for any security-conscious developer. Below we break down installation for each platform and cover best practices for using Claude Code safely in a team or solo workflow.

What You Need Before Installing

Across all operating systems, the prerequisites are minimal: Node.js version 18 or later (the agent runs on the Node.js runtime) and an active Anthropic API key with billing enabled on your account. You also need a terminal emulator and a basic understanding of command-line navigation. Claude Code can function inside any directory that contains a Git repository or a regular folder with code files; it will automatically detect the project structure, list files, and respect .gitignore rules by default.

Windows users specifically must have Windows Subsystem for Linux (WSL2) installed, or alternatively a full Git Bash environment. Native Windows Command Prompt and PowerShell are not directly supported by the official Claude Code CLI, though the agent can still be invoked via the Anthropic API from any client that can make HTTP requests. For the fullest experience and the interactive terminal UI that “thinks” through changes, WSL2 is the recommended pathway.

API Key Considerations

Generate your API key from the Anthropic Console. Once created, the key allows Claude Code to issue requests billed to your account; each invocation can issue multiple API calls as the agent reasons, edits files, and runs commands. Because the key is stored locally in a plain-text file (default location ~/.claude.json or set via the CLAUDEAPIKEY environment variable), you must treat it like any high-privilege credential. Never commit it to shared version control, and consider using a hardware security module or a secrets manager if your organization requires it.

Installation on macOS and Linux

macOS and Linux share an almost identical setup process. Open your terminal and run the npm global install command:

npm install -g @anthropic-ai/claude-code

If you don’t have Node.js, install it first via a version manager like nvm or your system’s package manager. Once installed, verify the binary is available:

claude --version

You’ll see a version string starting with Claude Code followed by the current release number (e.g., Claude Code 0.2.x). With the CLI in place, set your API key as an environment variable. The most portable method is to export it in your shell profile:

echo 'export CLAUDEAPIKEY="sk-ant-..."' >> ~/.zshrc
source ~/.zshrc

Alternatively, you can let Claude Code prompt you for the key on first run, which stores it inside ~/.claude.json. However, using an environment variable is often cleaner for scripting and avoids accidentally exposing the key in config file backups.

Now navigate to a project directory and type claude. The interactive TUI will launch, introducing itself and offering to help. At this point Claude has read access to the current directory and can suggest file edits, run shell commands after your approval, and manage Git operations. All permissions are governed by the “approval mode” you select: full-auto, per-request approval, or manual-only. For secure coding, per-request approval is recommended, so you can inspect every command before it executes.

Secure Defaults on macOS and Linux

By default, Claude Code respects the .gitignore file to avoid reading or modifying ignored files. You can also pass a .claudeignore file to further exclude sensitive files like environment configs or large binary blobs. For enterprise environments, consider running Claude Code inside a container or a dedicated virtual environment to limit its filesystem reach.

Windows Setup via WSL2

Windows 10 and 11 with WSL2 provide a native Linux environment where Claude Code runs exactly as it does on Linux. Start by ensuring WSL2 is installed and a distribution like Ubuntu 24.04 LTS is set up. Inside your WSL terminal, install Node.js using a version manager:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 20

Then proceed with the npm global install just like on Linux:

npm install -g @anthropic-ai/claude-code

Set your API key the same way by exporting it in your WSL ~/.bashrc or the equivalent for your shell.

One key difference for WSL users is that you will often work with files stored on the Windows filesystem (e.g., /mnt/c/Users/YourName/projects). Claude Code can access these directories, but performance may be slower due to the 9P network protocol between WSL and Windows. For best response times and security isolation, clone your repositories directly inside the WSL filesystem, typically under /home/<username>/.

WSL Interop and Network Safety

Since Claude Code can execute shell commands, it may interact with Windows binaries via wsl.exe if your path is configured that way. To prevent accidental cross-system operations, limit the visibility of Windows executables inside WSL by checking your $PATH. Additionally, if you use a corporate VPN or proxy, ensure that Node.js and the Anthropic API endpoints (api.anthropic.com) are reachable from WSL.

Working with Git Bash on Windows (Without WSL)

For developers who prefer a lightweight setup or cannot install WSL2, Git Bash (part of Git for Windows) can run the Claude Code npm package. The process is the same as a Unix environment because Git Bash provides a minimal GNU shell. Install Node.js for Windows from nodejs.org, making sure to add the Node.js installation to your system PATH. Then open Git Bash and run:

npm install -g @anthropic-ai/claude-code

Set the API key and call claude from the Bash prompt. Be aware that Git Bash’s terminal emulation may have subtle quirks with Unicode characters or the interactive TUI, but all core functionalities—code editing, command running, and Git workflows—work correctly. For a smoother experience, use the most recent version of Windows Terminal as your host, selecting the Git Bash profile.

Limitations and Workarounds

Native Windows paths use backslashes, which can cause path-related issues inside Claude Code. Always use forward-slashed Unix-style paths (e.g., /c/Users/…) inside Git Bash. If you encounter permission errors when Claude tries to write files, check that the file is not locked by another Windows process; tools like Process Explorer can help identify the lock. Furthermore, since Git Bash is not a full Linux environment, some shell commands that Claude Code might try to run (like grep -c with certain options) may behave differently. Keep a Linux-compatible toolchain (via MSYS2 or Cygwin) if you need advanced text processing.

Secure Coding with Claude Code

Beyond platform setup, secure usage of an agentic AI coding tool involves clear boundaries and informed consent. Claude Code operates with the same privileges as your user account. If it can write to production servers or databases from your terminal, it will try to do so when asked. Therefore, always work in development or staging environments, and never run the agent as root or Administrator.

Permission Model

Claude Code offers three levels of automation:

  • Full Auto – the agent may execute any command without asking. Use only in sandboxed, disposible environments.
  • Per-request Approval – you confirm each shell command, file write, or network access before it runs. This is the default and the safest for most development.
  • Manual Only – the agent never runs a command; it presents the command for you to copy-paste and run manually. This is the most secure but can slow down workflows.

For team settings, append --approval human (or set the environment variable CLAUDEAPPROVALLEVEL=human) to enforce that every action requires a human go-ahead.

Sensitive Files and .claudeignore

Create a .claudeignore file in your project root to explicitly exclude files containing credentials, API keys, or personal data. The syntax mirrors .gitignore. For example:

.env
credentials.json
keys/
*.pem

Claude Code will not read, edit, or even list these files in its context. Additionally, if your repository already has a .gitignore, Claude Code will honor it unless you explicitly opt out with the --include-ignored flag. Double-check this behavior when dealing with monorepos that contain infrastructure configuration.

API Key Lifecycle

Rotate your Anthropic API key periodically, especially if you suspect it was accidentally committed or shared. You can revoke the old key from the Anthropic Console and issue a new one. Use environment variables to inject the key dynamically in CI/CD pipelines; never bake it into Docker images or code. For local development, consider a tool like direnv to automatically set CLAUDEAPIKEY when you enter a project directory, and unset it when you leave.

Network and Data Privacy

Code snippets, error messages, and file contents are sent to Anthropic as part of each API request. By default, Anthropic’s API does not use your data to train models, but always review the latest privacy policy for your account tier. If your organization deals with highly sensitive source code, you may want to self-host a model or use an on-premise gateway; however, that falls outside the scope of the standard Claude Code setup. As a lighter measure, use .claudeignore and ensure that only relevant files are included in the project context.

Using Claude Code in a Multi-Platform Team

Because the code produced by Claude Code is plain text, it is immediately portable across macOS, Linux, and Windows. When a developer on a Mac uses Claude to refactor a Python module, the generated diff can be applied on a Windows teammate’s WSL environment without modification. However, watch for OS-specific file paths, line endings, and environment variables. Configure your Git repository to use .gitattributes to normalize line endings, and avoid embedding absolute paths like /home/user/project in shared scripts.

For a unified toolchain, all developers can use the same Claude Code version by pinning it in a project-level package.json:

{
  "devDependencies": {
    "@anthropic-ai/claude-code": "^0.2.0"
  },
  "scripts": {
    "claude": "claude"
  }
}

Then run npm run claude from any platform, ensuring consistency across the team.

Troubleshooting Common Cross-Platform Issues

“Command not found” after npm install

On all platforms, ensure that the npm global bin directory is on your PATH. On macOS/Linux/WSL, this is usually ~/.npm-global/bin if you use npm’s prefix configuration, or $(npm config get prefix)/bin. On Git Bash, it’s typically $APPDATA pm. You can add it to your .bashrc:

export PATH="$HOME/.npm-global/bin:$PATH"

Hostname Resolution in WSL

If WSL cannot resolve api.anthropic.com, check your resolv.conf. WSL2 may lose DNS settings after sleep; regenerate it with wsl --shutdown and a fresh start, or manually add a nameserver like 8.8.8.8.

Performance on Large Repositories

Claude Code sends a snapshot of the project structure and up to a few thousand tokens of file contents with each interaction. In large monorepos, the initial indexing can be slow. Mitigate this by using --max-repo-size (default 30MB) or by running Claude Code inside a focused subdirectory instead of the root. Additionally, keep an up-to-date .gitignore to prevent scanning the node_modules folder or compiled binaries.

Windows Line Endings (CRLF)

When using Git Bash, ensure your Git configuration has core.autocrlf true so that files checked out on Windows have CRLF endings but are committed with LF. Claude Code will write files with LF endings by default in a Unix-like environment; consistent settings avoid spurious diffs.

Future Cross-Platform Outlook

Anthropic has indicated that Claude Code will eventually support a native Windows CLI, eliminating the WSL or Git Bash requirement. Meanwhile, the rapid adoption of WSL2 among Windows developers and the convergence of development tooling across platforms make the current setup a pragmatic bridge. The addition of multimodal abilities (vision for screenshots and diagrams) in the latest Claude model family also hints at future integrations directly inside Windows Terminal without translation layers.

For now, the combination of macOS/Linux support and robust WSL/Git Bash pathways gives every developer access to the same agentic coding experience. By following the secure setup guidelines and understanding the cross-platform nuances, teams can safely let Claude Code handle boilerplate, refactors, and even complex bug hunts—all from the comfort of the terminal, no matter the underlying OS.

Resources and Next Steps

Start with a small, non-critical project to get a feel for the agent’s workflow. Experiment with the different approval modes and .claudeignore patterns until your setup matches your security posture. The agent learns from each interaction, so the more you use it within a well-defined environment, the more helpful it becomes while staying within the bounds you’ve set.