Best Way To Scope Claude Code (2026)
When working with Claude Code in multi-project environments or team settings, you often need to restrict its access to a specific directory. Whether you’re concerned about accidentally modifying the wrong files, working in a shared development environment, or simply want to maintain cleaner context boundaries, directory scoping is an essential skill. This guide covers the most effective methods for constraining Claude Code to a single directory.
Why Scope Claude Code to a Single Directory?
There are several compelling reasons to limit Claude Code’s file access:
- Accident prevention: Avoid modifying files outside your current project
- Security: Restrict AI access to sensitive directories in shared environments
- Context clarity: Keep Claude focused on relevant files only
- Team collaboration: Ensure Claude respects project boundaries in team workflows
- Performance: Reduce context overhead by limiting file scanning
The performance point deserves more attention than it usually gets. When Claude Code searches for files or reads context, a narrower working directory means faster, more relevant results. In a monorepo with dozens of services, asking Claude to “find the authentication middleware” without scoping produces noise from every service that has an auth folder. With proper scoping, you get exactly the files you mean.
The security angle matters in shared or CI environments. In a CI pipeline running as a service account, Claude’s file access should be constrained to the build workspace. not because Claude behaves maliciously, but because least-privilege access is sound engineering regardless of the tool involved.
Understanding How Claude Code Determines Its Working Context
Before looking at the specific methods, it helps to understand what Claude Code actually does with directory scope. Claude Code’s file tools (Read, Write, Edit, Glob, Grep) resolve paths relative to the working directory established at session start. If you start in /home/user/projects/myapp, a relative path like src/index.ts resolves to /home/user/projects/myapp/src/index.ts.
The allowedDirectories setting adds an additional layer: it specifies a whitelist of paths that Claude’s tools are permitted to touch. Even if the working directory is set to one path, Claude will refuse tool calls that target files outside the allowed directories list.
These two mechanisms compose: working directory controls resolution of relative paths, while allowedDirectories controls the access whitelist. For maximum isolation you typically want both pointing at the same location.
Method 1: Using the –dir Flag (Command Line)
The simplest and most direct approach is using the --dir flag when invoking Claude Code. This tells Claude to change into the specified directory before beginning its session.
claude --dir /path/to/your/project
This command launches Claude Code with its working directory set to the specified path. All file operations, glob searches, and context loading will be constrained to that directory and its subdirectories.
For interactive sessions, the most common approach is to change into the directory yourself first:
cd /path/to/your/project && claude
Both achieve the same result. The --dir form is slightly preferable in scripts and shell aliases because it keeps the intent explicit and does not modify your shell’s working directory.
Shell Alias Pattern
If you regularly work on multiple projects and want quick scoped sessions, shell aliases are useful:
In ~/.zshrc or ~/.bashrc
alias cl-frontend='claude --dir ~/projects/myapp/frontend'
alias cl-backend='claude --dir ~/projects/myapp/backend'
alias cl-infra='claude --dir ~/projects/infra'
With these aliases, cl-frontend drops you into a Claude session already scoped to the frontend, with no flags to remember.
The --dir method is ideal for quick sessions where you want immediate isolation without configuration changes.
Method 2: Using Allowed Directories in Settings
Claude Code supports an allowedDirectories setting in its configuration file. This provides persistent directory scoping that applies to all sessions.
Global Configuration
Edit your Claude Code settings file (typically located at ~/.claude/settings.json):
{
"allowedDirectories": [
"/Users/yourname/projects/myapp",
"/Users/yourname/projects/shared-library"
]
}
Project-Specific Configuration
For project-level scoping, create a .claude/settings.json file in your project root:
{
"allowedDirectories": [
"./"
]
}
Using "./" restricts Claude to the project root and below, preventing access to parent directories.
You can also specify multiple directories for projects that span multiple locations:
{
"allowedDirectories": [
"./frontend",
"./backend",
"./shared"
]
}
Monorepo Configuration
In a monorepo, You should scope Claude to a specific service while still allowing access to a shared package directory:
{
"allowedDirectories": [
"./packages/auth-service",
"./packages/shared-types",
"./packages/shared-utils"
]
}
This lets Claude read and write within the auth service and the shared packages it depends on, but prevents it from touching other services.
Configuration Hierarchy
Claude Code reads settings from multiple locations and merges them, with more specific settings taking precedence:
~/.claude/settings.json. global defaults~/.claude/projects/<project-id>/settings.json. project-level overrides.claude/settings.jsonin the current directory. directory-level overrides
For team projects, committing .claude/settings.json to your repository ensures every team member and every CI run has the same scoping configuration. This is the recommended approach for projects where consistent boundaries matter.
Method 3: Using .claudeignore for File Filtering
While not strictly directory scoping, the .claudeignore file helps maintain focus by excluding specific files and directories from Claude’s context. Create this file in your project root:
Dependencies
node_modules/
venv/
.env/
Build outputs
dist/
build/
*.log
IDE
.idea/
.vscode/
Git
.git/
Generated files
coverage/
*.generated.ts
*.min.js
Large data files
*.csv
*.parquet
data/
This tells Claude to ignore certain directories when scanning for relevant files, effectively narrowing its focus to the files that matter for your task.
The .claudeignore format follows the same syntax as .gitignore. Patterns support wildcards, directory separators, and negation with !:
Ignore all SQL files except migrations
*.sql
!migrations/*.sql
Ignore test fixtures but not test files themselves
/__fixtures__/
A well-tuned .claudeignore file can dramatically improve the relevance of Claude’s file searches. If your project has a vendor/ directory with 200,000 lines of third-party code, ignoring it means Claude searches your code instead of that.
.claudeignore vs allowedDirectories
.claudeignore |
allowedDirectories |
|
|---|---|---|
| Controls | Files excluded from context scanning | Paths Claude’s tools can access |
| Syntax | Gitignore-style patterns | Explicit path list |
| Granularity | Fine (file patterns, wildcards) | Coarse (directory level) |
| Location | Project root | Settings file |
| Effect on writes | Reduces context noise | Blocks tool calls to unlisted paths |
Use both together for the best result: allowedDirectories for hard access boundaries, .claudeignore for refining the file search context within those boundaries.
Method 4: Using Project Initialization with Scope
When initializing a new Claude Code project, you can establish directory scope from the start:
claude --add-dir /path/to/project
This creates the project configuration with the specified directory as the default scope. It is particularly useful when setting up Claude for the first time on an existing project. running this command establishes the directory as the project root before you start any sessions.
You can also combine --add-dir with the initial session:
claude --add-dir /path/to/project --dir /path/to/project
The first flag configures the project, the second sets the working directory for the current session.
Method 5: Environment-Based Scoping
For CI/CD pipelines or automated workflows, you can combine directory scoping with other techniques:
CLAUDE_DIR=/workspace/myapp claude --print < prompt.txt
This approach works well for scripted workflows where you want directory isolation without interactive prompts.
CI/CD Integration
In a GitHub Actions workflow, you might scope Claude to a specific subdirectory for a code review or generation step:
- name: Generate API client
run: |
claude --dir ./packages/api-client \
--print \
"Generate TypeScript types from the OpenAPI spec in openapi.yaml"
For Docker-based CI environments, mount only the relevant directory into the container rather than the entire monorepo:
Dockerfile.claude-ci
FROM anthropic/claude-code:latest
WORKDIR /workspace
Container only has access to what you mount
docker run --rm \
-v /path/to/service:/workspace \
anthropic/claude-code:latest \
claude --print "Run a code review on the recent changes"
Combining container isolation with allowedDirectories gives you two independent layers of access control.
Comparing the Methods
| Method | Persistence | Team-shareable | Best for |
|---|---|---|---|
--dir flag |
Session only | No | Quick one-off sessions |
cd && claude |
Session only | No | Interactive daily use |
allowedDirectories in global settings |
Permanent | No | Personal machine defaults |
allowedDirectories in project settings |
Permanent | Yes (commit it) | Team projects |
.claudeignore |
Permanent | Yes (commit it) | Filtering noise within scope |
| Environment variable | Session / script | Via script | CI/CD pipelines |
For most projects, the right combination is .claude/settings.json with allowedDirectories committed to the repo, plus a .claudeignore file for filtering. This gives every team member and every CI run the same boundaries with no manual setup.
Best Practices for Effective Directory Scoping
Start Broad, Then Narrow
When beginning a new project, start with a slightly broader scope, then narrow it as you understand what files are relevant. This prevents accidentally excluding needed resources.
It is common to start with the entire project root ("./") and add .claudeignore entries as you discover directories that add noise without adding value. Reverse-engineering a too-narrow scope is more frustrating than refining a broad one.
Combine Methods for Maximum Isolation
For sensitive projects, layer multiple scoping methods:
- Use
--dirflag for session start - Configure
allowedDirectoriesin project settings - Add
.claudeignorefor file filtering
This defense-in-depth approach ensures consistent boundaries. If one layer has a misconfiguration, the others still apply.
Scope to What Claude Actually Needs to Write
A common mistake is scoping too broadly for write access. It is often appropriate to give Claude broad read access (so it can understand the codebase) while restricting writes to the specific directory being modified.
You can achieve this by configuring allowedDirectories to include paths needed for reading while using more targeted prompts that direct Claude to only write in specific locations:
claude --dir /projects/myapp \
"Review the auth service implementation in packages/auth-service and
suggest improvements. Write any changes only to packages/auth-service/src."
Document Your Scope Choices
Include a brief note in your project’s CLAUDE.md or CONTRIBUTING file about the directory scope you’ve configured. This helps team members understand Claude’s boundaries:
Claude Code Configuration
This project uses `.claude/settings.json` to scope Claude Code to the project root.
The `./data` directory is excluded via `.claudeignore` because it contains large
datasets not relevant to code changes.
To start a scoped session: `claude --dir .`
Test Your Scoping
After configuring directory restrictions, verify they work correctly by asking Claude to access a file outside the configured scope. Claude should either refuse the request or indicate it cannot access files outside its allowed directories.
This is especially important before onboarding a new team member or setting up a CI pipeline. a quick test up front avoids surprises in production.
Troubleshooting Common Issues
Claude Still Accessing Files Outside Scope
If Claude appears to be accessing files it should not, verify your settings file is valid JSON. Malformed JSON silently fails to load. Run the file through a JSON validator (python3 -m json.tool .claude/settings.json) to confirm it parses correctly.
Also confirm that the settings file is in the location Claude is actually reading. Global settings live in ~/.claude/settings.json; project settings live in .claude/settings.json relative to the directory you started Claude from.
Scope Too Restrictive
If Claude cannot find necessary files, your scope is too narrow. Expand your allowedDirectories to include parent directories or additional project folders.
A common cause is a project that imports from a shared library in a sibling directory. If allowedDirectories only includes ./packages/my-service but the service imports from ./packages/shared, Claude will not be able to read the shared package and will produce suggestions without that context.
Settings Not Applying
Ensure your .claude/settings.json is in the correct location (project root or home directory) and restart your Claude Code session for changes to take effect. Changes to settings files do not apply to already-running sessions.
Performance Issues Despite Scoping
If Claude’s file searches are still slow after scoping, check your .claudeignore file. Large directories like node_modules, venv, .git, and build outputs should always be listed. A missing node_modules/ entry in .claudeignore is the single most common cause of slow context loading in JavaScript and TypeScript projects.
Conclusion
Scoping Claude Code to a single directory is straightforward with the right techniques. Whether you prefer command-line flags for quick sessions or persistent configuration for project isolation, there is an approach that fits your workflow. Start with the --dir flag for immediate results, then graduate to configuration-based scoping for permanent solutions. Combined with .claudeignore, you can create precise boundaries that keep Claude focused and your files protected.
The key is choosing the method that matches your use case: temporary sessions benefit from flags, while team projects benefit from configuration files that can be committed to version control. For CI/CD pipelines, environment-based scoping integrates cleanly with existing workflow tools without requiring interactive configuration.
With these tools at your disposal, you have complete control over where Claude Code can operate. The effort to set up proper scoping is small and the payoff. faster, more accurate file operations and a reduced risk of accidental modifications. is immediate.
Try it: Paste your error into our Error Diagnostic for an instant fix.
Related Reading
- Configuration Reference. Complete Claude Code settings and configuration guide
- Claude Code disallowedTools Security Configuration
- MCP Transport Layer Security TLS Configuration Guide
- Best Encrypted Backup Solution for Developers: A 2026 Technical Guide
Built by theluckystrike. More at zovo.one
Set it up → Build your permission config with our Permission Configurator.