Claude Code on WSL2: Fixing Permissions for Local File Access

Running Claude Code on WSL2 provides a powerful environment for Windows developers who want the speed of Linux with the convenience of a desktop OS. However, developers often encounter significant friction when the agent attempts to write to the file system or access local directories. This guide explains how to configure your environment to ensure Claude Code has the necessary permissions to function correctly without compromising security.

Understanding the WSL2 Permission Model

Windows Subsystem for Linux 2 uses a virtualization technology that creates a bridge between the Windows NTFS file system and the Linux EXT4 system. When you run a CLI agent like Claude Code, it expects a standard POSIX environment. Problems arise because Windows permissions do not map one to one with Linux permissions.

If you store your project files on the Windows mount, located at /mnt/c/, you will likely face performance lag and metadata issues. The agent might report that it cannot modify files even if you are logged in as a user with administrative privileges. To avoid this, it is highly recommended to move your active development projects into the native Linux file system, such as your home directory at /home/username/.

Common Permission Errors and Solutions

When Claude Code attempts to initialize a project or edit a file, it might throw an EACCES error. This usually happens when the underlying directory is owned by the root user or has restricted write access. You can check the current ownership of your directory by running ls -la in your terminal.

If the files are owned by root, you should change ownership to your current user. Use the command sudo chown -R $(whoami):$(whoami) . to recursively update the permissions of your current working directory. This ensures that the agent can read, write, and create new files during its reasoning process.

Another common issue involves the umask setting. This determines the default permissions for new files. If your umask is too restrictive, Claude Code might create files that it cannot subsequently edit. Setting a umask of 022 in your .bashrc or .zshrc file is generally sufficient for local development.

Optimizing the Agent Workflow with Deska

For developers who find terminal management in WSL2 cumbersome, using a specialized workspace can simplify the process. Deska offers a local-first approach to managing these agents. It is a free desktop app for Mac, Windows, and Linux that provides an infinite canvas workspace.

Instead of managing multiple independent terminal windows to handle your permissions and your agent sessions, you can use Deska to place panels anywhere on a large canvas. This allows you to run Claude Code in one terminal panel while keeping a code editor or a documentation browser open right next to it. You can learn more about how this works by visiting the workspaces documentation.

One of the key advantages of using this environment is the ability to zoom out to see your entire project architecture. While Claude Code handles the logic, Deska provides the visual context. Since it is local-first, your code and sessions stay on your machine, which aligns with the security model required for WSL2 development.

Comparison of Development Environments

Choosing how to run AI agents involves balancing ease of use with control. Below is a comparison of different approaches for Windows developers.

While VS Code is excellent for traditional editing, it often treats terminal agents as secondary processes. In contrast, the canvas in Deska treats the terminal as a first-class citizen. You can run Claude Code, Codex CLI, and OpenCode side by side as panels, allowing for a comparative analysis of how different agents solve the same permission or logic problem.

Setting Up Claude Code in a Deska Panel

To get started within the workspace, you first need to ensure your WSL2 instance is the default shell for your terminal panels. You can configure this in the settings section of the app. Once configured, you can open a new terminal panel and initialize your agent.

If you are using the lifetime tier, you can use your own API keys. This is a BYOK (Bring Your Own Key) model that gives you direct control over your costs. For those who prefer a managed experience, there is an option for managed inference. You can explore these options on the pricing page.

The workspace also includes a feature called Ask Deska. This is a voice and chat assistant that can drive the workspace for you. If you are struggling to find a specific panel or want to run a common permission-check command, you can use voice commands or chat to automate the layout.

Managing Files and Git

Claude Code relies heavily on being able to read your git history and file structure. If your .git folder has incorrect permissions, the agent will lose its ability to understand the context of your changes. Ensure that the git configuration within WSL2 matches your user identity.

In Deska, the code editor panel uses Monaco, the same engine that powers VS Code. This means you get familiar syntax highlighting and linting while your AI agent works in the adjacent panel. Because the tool is local-first, the synchronization between the agent's edits and the editor's view happens instantly without cloud latency.

FAQ

How to fix WSL2 permission denied error for Claude Code?

The most effective fix is to ensure your project files are located within the Linux file system rather than the Windows mount. Use sudo chown -R $USER:$USER /path/to/project to grant your user full ownership of the directory.

Why is Claude Code slow on Windows WSL2?

Slowness is often caused by cross-file system access. If the agent is accessing files on the /mnt/c/ path, Windows Defender and the translation layer slow down every read/write operation. Move your files to the native WSL2 home directory for a significant speed boost.

Can I run Claude Code and other agents side by side?

Yes, using a workspace like Deska allows you to run Claude Code, Codex CLI, and OpenCode in parallel panels. This helps you compare results and use the best tool for specific tasks within the same canvas.

Streamline Your AI Workflow

Fixing permissions is only the first step in creating an efficient development environment on Windows. Once your file access is stable, the next challenge is managing the sheer volume of information these agents generate.

Deska provides the infrastructure to keep your agents organized. Whether you are monitoring a long-running task via the mobile app or organizing your thoughts in the notes panel, the goal is to keep you in the flow. By moving away from cramped terminal windows and into an infinite workspace, you can fully leverage the power of Claude Code.

Download the workspace for free at /download and start building more effectively on WSL2.