Claude Code now supports working across multiple directories in a single session using the --add-dir flag and /add-dir interactive command. This eliminates constant context switching between projects.
What Is Multi-directory Support
Core Functionality
The --add-dir /path/to/dir flag adds directories to your Claude Code session without changing your working directory. Use /add-dir <path> during interactive sessions to expand your workspace dynamically.
Claude Code maintains file relationships across different directory structures while preserving performance. The system handles path resolution automatically when you reference files from added directories.
Key Use Cases
Monorepos
Work across frontend, backend, and shared modules without switching sessions. Large applications with logical separation benefit from unified access to all components.
Shared Configuration Files
Access configuration files, documentation, and development artifacts stored in separate locations. Personal productivity files and team documentation become consistently available across sessions.
Cross-Project Development
Manage interconnected repositories simultaneously. API clients stay synchronized with server implementations. Documentation updates alongside code changes.
Implementation Strategies
Workspace Setup
- Identify your primary working directory
- Add related directories using
--add-dir - Create shell aliases for common configurations
- Establish team-wide directory patterns
Performance Optimization
- Add only directories you actively use
- Avoid directories with build artifacts
- Monitor context token usage with large configurations
- Use absolute paths for reliable access
Development Integration
Multi-directory support works with existing Git workflows, CI systems, and deployment pipelines. API development tools like Apidog can monitor specifications across multiple project directories.
Practical Examples
Microservices Architecture
Access service implementations, shared libraries, configuration templates, and deployment scripts in one session. Reference existing patterns while developing new services.
Open Source Contributions
Work with forked repositories, upstream sources, and personal configurations simultaneously. Maintain clean contributions while accessing all relevant codebases.
Infrastructure as Code
Manage application definitions, deployment configurations, and monitoring setups across multiple repositories. Maintain consistency during infrastructure changes.
Best Practices
Configuration Management
Use absolute paths to avoid resolution issues. Verify read permissions for all directories. Create standardized setups for team consistency.
Security Considerations
Review directory contents before adding them. Exclude sensitive information and production credentials. Use dedicated development directories.
Performance Monitoring
Watch memory usage with extensive directory structures. Local directories provide better performance than network-mounted ones. Remove unused directories from sessions.
Advanced Features
Command-Line Integration
claude-code --add-dir /path/to/backend --add-dir /path/to/frontend
Interactive Commands
/add-dir /path/to/shared-config
/add-dir /path/to/documentation
Team Workflows
Standardize multi-directory configurations across teams. Document common patterns for consistent developer experience. Integrate with onboarding processes.
API Development Workflow
Multi-directory support enhances API-first development. Backend services, documentation, client SDKs, and test suites often exist in separate repositories but require synchronized updates.
Apidog provides unified testing interfaces that work across your multi-directory workspace. This ensures API consistency as you develop features spanning multiple projects.
Troubleshooting Common Issues
Path Resolution Problems
- Use absolute paths instead of relative ones
- Verify symbolic links work correctly
- Check directory permissions
Performance Issues
- Limit added directories to necessary ones
- Monitor system resources
- Remove unused directories during long sessions
Access Control
- Ensure proper read permissions
- Avoid adding directories with sensitive data
- Use development-specific directory structures
Future Enhancements
The community requests configuration files for persistent workspace setups. This would enable team-wide standardization and reduce repetitive setup tasks.
Integration opportunities with development platforms continue expanding. API development tools, project management systems, and collaboration platforms can leverage enhanced workspace capabilities.
Conclusion
Claude Code Multi-directory support eliminates workflow friction in modern development. Monorepos, microservices, and cross-project collaboration become seamless without context switching overhead.
Start with simple two-directory configurations and expand based on project needs. The minimal learning curve delivers significant productivity improvements as project complexity grows.
Combined with comprehensive API testing tools like Apidog, multi-directory support creates streamlined end-to-end development experiences. Experiment with configurations that match your specific project requirements for maximum benefit.
