Using Additional Directories with --add-dir

Overview

The --add-dir flag in Claude Code allows you to extend your workspace beyond the current working directory by temporarily including additional directories in your project context. This powerful feature enables Claude to access and understand code from multiple locations without requiring you to change your primary working directory.

What You'll Learn

• How to use the --add-dir flag to work across multiple project folders
• Security considerations and permission management
• Common use cases and best practices
• Advanced usage patterns for complex workflows

Prerequisites

• Claude Code CLI installed
• Basic understanding of terminal navigation
• Understanding of file system permissions

Basic Usage

Command Line Syntax

# Using full absolute path
claude --add-dir ~/path/to/additional/directory

# Using relative path from current location
claude --add-dir ../../shared-libraries

# Adding multiple directories
claude --add-dir ../backend-api --add-dir ~/shared/configs --add-dir ../docs

Interactive Session Usage

You can also add directories dynamically during an active Claude Code session using slash commands:

/add-dir /path/to/other/project
/add-dir ../backend-api
/add-dir ~/shared/libraries

Verification

Ask Claude to list the contents of an added directory to confirm it's available:

/ls ../scripts

Common Use Cases

1. Microservices Architecture

When working on interconnected services that share common code:

# Frontend project referencing backend API
claude --add-dir ../backend-api

# Multiple microservices sharing common models
claude --add-dir ../user-service --add-dir ../auth-service --add-dir ../shared-models

2. Shared Resources and Libraries

Access company-wide configurations, templates, or utility libraries:

# Access shared company configurations
claude --add-dir ~/company/shared-configs

# Reference template repositories
claude --add-dir ~/templates/react-components

# Include utility libraries
claude --add-dir ~/utils/common-functions

3. Legacy System Integration

When modernizing projects that need to reference existing systems:

# Modernizing while referencing legacy code
claude --add-dir ../legacy-system --add-dir ../migration-scripts

4. Documentation and Examples

Include reference materials and example code:

# Access documentation and examples
claude --add-dir ../project-docs --add-dir ../code-examples

Security Considerations

Default Security Boundaries

Claude Code implements several security measures when using additional directories:

• Folder Access Restriction: Claude Code can only access the folder where it was started and its subfolders, plus explicitly added directories via --add-dir
• No Upstream Access: Claude cannot access parent directories unless explicitly granted via --add-dir
• Permission System: All file operations still require appropriate permissions based on your configured settings

Permission Configuration

When using --add-dir, Claude Code inherits your existing permission settings. Configure permissions through:

1. Global Settings: ~/.claude/settings.json
2. Project Settings: .claude/settings.json (shared with team)
3. Local Settings: .claude/settings.local.json (personal preferences)

Example permission configuration:

{
  "permissions": {
    "allow": [
      "Read(*)",
      "Bash(npm run test:*)",
      "Edit(src/**/*)"
    ],
    "deny": [
      "Bash(curl:*)"
    ]
  }
}

Security Best Practices

1. Principle of Least Privilege: Only add directories that are necessary for your current task
2. Review Added Directories: Be mindful of what directories you're exposing to Claude
3. Use Project-Specific Settings: Configure permissions appropriately for each project
4. Monitor File Access: Claude will still request permission for sensitive operations

Advanced Usage Patterns

Git Worktrees Integration

Combine --add-dir with Git worktrees for parallel development:

# Create worktrees for different features
git worktree add ../project-feature-a feature-a
git worktree add ../project-feature-b feature-b

# Work on feature A while referencing feature B
cd ../project-feature-a
claude --add-dir ../project-feature-b

Multi-Repository Analysis

Analyze patterns across multiple repositories:

claude --add-dir ~/repo1 --add-dir ~/repo2 --add-dir ~/repo3 \
  -p "Compare authentication patterns across these three repositories"

Model Selection with Additional Directories

Specify model while adding directories:

claude --model claude-sonnet-4-20250514 --add-dir ../backend-api \
  -p "Compare authentication patterns between current and shared directory"

Example Workflows

Cross-Service Development

# Start in frontend directory
cd ~/projects/frontend

# Add backend and shared libraries
claude --add-dir ../backend --add-dir ../shared-lib

# Now ask Claude to analyze or modify code across all three directories

Documentation Generation

# Include multiple codebases for comprehensive documentation
claude --add-dir ../api-server --add-dir ../web-client --add-dir ../mobile-app \
  -p "Generate API documentation that covers all client implementations"

Tips & Variations

• Combine --add-dir with --allowedTools for fine-grained permissions
• Use absolute paths for directories outside your project root
• Use descriptive prompts to specify which directories contain what
• Include relevant information about the relationship between directories
• Regular cleanup: Use /clear to reset context when switching tasks

Important Notes

• When adding directories that are separate Git repositories, Claude Code will respect each repository's boundaries
• Git operations in each directory will affect only that repository
• Use caution when making changes across multiple repositories in a single session
• Consider using Git worktrees if you need multiple views of the same repository
• Large directory structures may impact performance

Troubleshooting

Common Issues

1. Directory Not Recognized

   • Ensure the path exists and you have read permissions
   • Check for typos in the path

2. Relative Path Problems

   • Verify relative paths are correct from your starting location
   • Consider using absolute paths for clarity

3. Permission Denied

   • Check file system permissions
   • Review Claude Code permission settings

4. Claude says a file does not exist

   • Ensure the directory was added correctly
   • Verify the path is accurate

Known Limitations

• Some users have reported issues with --add-dir not being recognized in certain versions
• The feature is relatively new and may have edge cases in specific environments
• Large directory structures may impact performance

Best Practices Summary

1. Start Small: Begin with your main project directory and add others as needed
2. Use Descriptive Prompts: Clearly specify which directories contain what when asking Claude to work across multiple locations
3. Maintain Context: Include relevant information in your prompts about the relationship between directories
4. Regular Cleanup: Use /clear to reset context when switching between different multi-directory tasks
5. Version Control Integration: Consider how added directories interact with your Git workflow

The --add-dir feature transforms Claude Code from a single-project tool into a powerful cross-codebase assistant, enabling more sophisticated development workflows while maintaining security and permissions boundaries.

References

• Official Claude Code Documentation
• Claude Code Best Practices
• Claude Code Security Documentation
• Claude Code Settings Configuration
• Claude Code GitHub Repository