The complete guide to claude code filesystem access

What Is Claude Code Filesystem Access?

Claude Code filesystem access is the set of read, write, and execute permissions granted to the Claude Code agent when it operates on your local machine — including which directories it can read, which files it can modify, and whether it can traverse into sensitive paths like ~/.ssh, .env, or system configuration directories.

Unlike a web-based AI assistant that only sees what you paste into a chat window, Claude Code runs as an agentic process on your workstation or CI runner. It resolves file paths, reads source trees, edits code, and shells out to terminal commands. That's genuinely useful. It's also a meaningful attack surface if you haven't thought through the boundaries.

This guide covers how filesystem access works under the hood, what can go wrong, and how to configure it correctly in production environments. If you want the full permission model picture alongside filesystem controls, the Claude Code Security documentation goes deeper on scoping rules, MCP integration, and audit logging.

Why Claude Code Filesystem Access Matters in 2026

Agentic coding tools are no longer novelties. GitHub Copilot reported over 1.8 million paid seats by late 2024; Claude Code itself saw enterprise adoption accelerate through early 2026 as teams moved from autocomplete to fully autonomous coding sessions. With that scale comes a new class of incident.

The core risk isn't that Claude Code is malicious. It's that an agent operating with broad filesystem permissions becomes a high-value pivot point. A prompt injection embedded in a third-party dependency's README can instruct the agent to exfiltrate .env credentials. An MCP tool that returns attacker-controlled content can redirect write operations to sensitive paths. These aren't theoretical: CVE-2024-5184 documented a prompt injection pattern against AI coding assistants that leveraged file context to escalate privileges within the IDE environment.

Three things compound the risk in real deployments:

• Claude Code's default working directory is often the repository root, which in monorepos can include infrastructure-as-code, secrets references, and deployment configs alongside application code.

  • Developers routinely grant broad shell execution permissions in .claude/settings.json to avoid friction, then forget those settings persist across projects.
  • CI/CD pipelines that run Claude Code in automated modes frequently inherit ambient cloud credentials through environment variables, expanding the blast radius of any filesystem escape.

How Claude Code Filesystem Access Works

How Claude Code Filesystem Read Access Works

When Claude Code starts a session, it resolves a working directory — by default, the directory from which the CLI was launched. Read access extends across that tree unless you've set explicit restrictions. The agent uses this to build context: it reads source files, config files, lock files, and any other documents it judges relevant to your query.

What it reads isn't random. Claude Code uses an internal relevance heuristic to decide which files to load into context. But "relevance" is determined by the model, not by a whitelist you control. A query like "update the database connection string" can trigger reads across multiple config files, including ones that contain secrets you may not have intended to expose to any external process.

How Claude Code Filesystem Write Access Works

Write operations go through a permission gate. By default, Claude Code prompts for confirmation before modifying files, but this behavior is configurable. In --dangerously-skip-permissions mode (designed for headless CI), that gate is removed entirely. Teams using this mode in automated pipelines often don't realize they've given the agent carte blanche to overwrite any file in the working directory without any human review step.

Write permissions are scoped to the working directory by default, but shell tool access can bypass this. If Claude Code can run bash commands, it can write to arbitrary paths via shell redirection, regardless of the filesystem permission configuration.

Restricting Claude Code Filesystem Access with .claude/settings.json

The primary control surface is .claude/settings.json at the project root. This file governs which tools Claude Code can invoke, what shell commands are allowed, and which directories fall within scope. A minimal hardened configuration looks like:

{
  "permissions": {
    "allow": ["Read(**)", "Edit(src/**)"],
    "deny": ["Read(**/.env*)", "Read(**/secrets/**)", "Bash(*)"]
  }
}

The deny array takes precedence over allow. You can explicitly block reads on .env files, SSH keys, and cloud credential paths (~/.aws/credentials, ~/.config/gcloud) regardless of what the model requests. This is the single most impactful configuration change most teams can make immediately.

Best Claude Code Filesystem Access Tools and Solutions

The built-in settings file handles basic scoping, but production environments need more. Three layers are worth combining:

Static policy enforcement. Tools like OPA (Open Policy Agent) can intercept MCP tool calls before they reach the filesystem, evaluating requests against a policy document. This works well for organizations that already run OPA in their infrastructure; it adds latency but gives you centralized, auditable policy that isn't stored in individual project repos.

Filesystem-level sandboxing. On Linux, running Claude Code inside a container with a read-only rootfs and explicit volume mounts limits the blast radius regardless of what the agent requests. macOS users can use sandbox-exec profiles to restrict file access by path prefix. Neither approach is zero-friction, but both provide defense-in-depth that doesn't depend on the agent respecting its own configuration.

Audit logging with reasoning traces. Standard filesystem audit logs (auditd on Linux, OpenBSM on macOS) record what happened, but not why. For incident response, you need the agent's reasoning trace alongside the file operation log. Claude Code's verbose mode outputs this trace to stderr; piping it to a structured log aggregator gives you the context needed to reconstruct what the agent was attempting when an unexpected write occurred.

For teams deploying Claude Code at scale, the Claude Code Security product overview covers centralized policy management, reasoning trace logging, and MCP server sandboxing in a single deployment-ready package. At Claude Code Security, we built our tooling specifically for engineering teams that need granular filesystem controls without requiring every developer to manually maintain per-project settings files.

Claude Code Filesystem Access Best Practices

A few concrete rules that hold across most deployment contexts:

1. $1

   1. $1
   2. $1
   3. $1
   4. $1

More deployment patterns and configuration templates are available on the Claude Code Security blog, including worked examples for monorepo setups and air-gapped CI environments.

Frequently Asked Questions

What is Claude Code filesystem access?

Claude Code filesystem access refers to the read, write, and execute permissions the Claude Code agent holds when running on your machine. By default, it can read and modify files within its working directory and run shell commands unless you restrict those capabilities in .claude/settings.json or via OS-level sandboxing.

How does Claude Code filesystem access work?

Claude Code resolves a working directory at session start (typically the directory you launched the CLI from) and uses that as its root scope for file reads and writes. It reads files into context based on query relevance, writes through a permission-gated edit system, and can execute shell commands if the Bash tool is enabled. All of these behaviors are configurable through the settings file and via runtime flags.

Does Claude Code access .env files?

By default, yes — Claude Code can read any file in its working directory, including .env files, unless you add an explicit deny rule. Add "Read(**/.env*)" to your deny list in .claude/settings.json to block this. Treat .env access the same way you'd treat it in a shared codebase: assume it will be read unless you actively prevent it.

How do I restrict Claude Code filesystem permissions?

The primary mechanism is the permissions.deny array in .claude/settings.json. Deny rules take precedence over allow rules. You can also restrict the working directory with --cwd at launch, run Claude Code inside a container with limited volume mounts, or use OS-level sandbox profiles (sandbox-exec on macOS, seccomp on Linux) for defense-in-depth.

What are the best tools for managing Claude Code filesystem access?

For most teams: the built-in settings file for basic path restrictions, container-level sandboxing for CI environments, and structured logging of agent reasoning traces for incident response. Teams running Claude Code at scale typically add centralized policy management (OPA or equivalent) to avoid per-project configuration drift. See the Claude Code Security pricing page for enterprise options that include centralized policy enforcement.

What are common Claude Code filesystem access mistakes to avoid?

The most common mistakes: launching Claude Code from a monorepo root that includes secrets and infrastructure configs, using --dangerously-skip-permissions in CI pipelines that have ambient cloud credentials, granting wildcard shell permissions instead of enumerating specific allowed commands, and forgetting that MCP servers returning external content can inject instructions that redirect file operations to sensitive paths.