Additional Directories Enhanced

Grant Claude Code access to directories outside the current project for monorepo and multi-repo workflows.

When to Use This Setting

Apply this setting when you need to:

• Access shared libraries, documentation, or utility repositories that live outside the current project directory
• Work in a monorepo setup where related code spans multiple top-level directories
• Reference company tools or common configurations stored in system-level directories Consider alternatives when:
• All relevant code lives within your project's directory tree and no external access is needed
• Security policies prohibit Claude Code from accessing paths outside the project root

Quick Start

Configuration

Copy
name: additional-directories-enhanced
type: setting
category: permissions

Example Application

Copy
claude setting:apply additional-directories-enhanced

Example Output

Setting applied. Changes:
- additionalDirectories: ["../docs/", "../shared-components/", "~/projects/common-utils/", "/opt/company-tools/"]

Core Concepts

Directory Access Overview

Aspect	Details
Relative Paths	Paths like ../docs/ are resolved relative to the current project root
Home Directory	Tilde paths like ~/projects/ expand to the current user's home directory
Absolute Paths	Full paths like /opt/company-tools/ provide explicit access to system directories
Read and Write	Additional directories grant full read and write access unless restricted by other rules

Directory Access Architecture

+---------------------------+
|  Claude Code Session      |
+---------------------------+
|  Project Root (default)   |
|  /home/user/my-project    |
+---------------------------+
|  Additional Directories:  |
|  +---------------------+ |
|  | ../docs/            | |  <-- Sibling repo
|  | ../shared-components| |  <-- Shared library
|  | ~/projects/utils    | |  <-- User projects
|  | /opt/company-tools  | |  <-- System tools
|  +---------------------+ |
+---------------------------+

Configuration

Parameter	Type	Default	Description
permissions.additionalDirectories	array	[]	List of directory paths to grant Claude Code access to
additionalDirectories[0]	string	"../docs/"	Relative path to documentation repository
additionalDirectories[1]	string	"../shared-components/"	Relative path to shared component library
additionalDirectories[2]	string	"~/projects/common-utils/"	Home-relative path to common utilities
additionalDirectories[3]	string	"/opt/company-tools/"	Absolute path to company-wide tools directory

Best Practices

1. Use the most specific paths possible - Avoid granting access to broad directories like ~ or /. Specify the exact subdirectories needed to minimize the scope of access.
2. Prefer relative paths for portable configurations - Relative paths like ../docs/ work across team members' machines regardless of where they clone repositories. Absolute paths create machine-specific dependencies.
3. Combine with deny rules for sensitive subdirectories - If an additional directory contains both useful code and sensitive configuration, add deny rules for the sensitive subdirectories to maintain security boundaries.
4. Document the purpose of each directory - Team members should understand why each additional directory is included. Add comments or maintain a companion document explaining the rationale.
5. Review access periodically - As projects evolve, some additional directories may no longer be relevant. Remove unused entries to keep the access scope minimal and the configuration clean.

Common Issues

1. Path not found errors - Verify that the directory exists on your machine. Relative paths are resolved from the project root, not from the current working directory of your terminal.
2. Tilde expansion not working - Some environments do not expand ~ correctly. If you encounter issues, use the full absolute path instead of the tilde shorthand.
3. Permission denied on system directories - Directories like /opt/company-tools/ may require elevated permissions. Ensure your user account has read access to the specified paths.