Using Additional Directories with --add-dir

Overview

The --add-dir flag in OpenAI Codex allows you to extend your workspace beyond the current working directory by temporarily including additional directories in your project context. This powerful feature enables OpenAI Codex 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

• OpenAI Codex CLI installed
• Basic understanding of terminal navigation
• Understanding of file system permissions

Basic Usage

Command Line Syntax

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

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

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

Interactive Session Usage

You can also add directories dynamically during an active OpenAI Codex session using slash commands:

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

Verification

Ask OpenAI Codex 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
codex --add-dir ../backend-api

# Multiple microservices sharing common models
codex --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
codex --add-dir ~/company/shared-configs

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

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

3. Legacy System Integration

When modernizing projects that need to reference existing systems:

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

4. Documentation and Examples

Include reference materials and example code:

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

Security Considerations

Default Security Boundaries

OpenAI Codex implements several security measures when using additional directories:

• Folder Access Restriction: OpenAI Codex can only access the folder where it was started and its subfolders, plus explicitly added directories via --add-dir
• No Upstream Access: OpenAI Codex 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, OpenAI Codex inherits your existing permission settings. Configure permissions through:

1. Global Settings: ~/.codex/settings.json
2. Project Settings: .codex/settings.json (shared with team)
3. Local Settings: .codex/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 OpenAI Codex
3. Use Project-Specific Settings: Configure permissions appropriately for each project
4. Monitor File Access: OpenAI Codex 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
codex --add-dir ../project-feature-b

Multi-Repository Analysis

Analyze patterns across multiple repositories:

codex --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:

codex --model codex-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
codex --add-dir ../backend --add-dir ../shared-lib

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

Documentation Generation

# Include multiple codebases for comprehensive documentation
codex --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, OpenAI Codex 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 OpenAI Codex permission settings

4. OpenAI Codex 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 OpenAI Codex 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 OpenAI Codex from a single-project tool into a powerful cross-codebase assistant, enabling more sophisticated development workflows while maintaining security and permissions boundaries.

References

• Official OpenAI Codex Documentation
• OpenAI Codex Best Practices
• OpenAI Codex Security Documentation
• OpenAI Codex Settings Configuration
• OpenAI Codex GitHub Repository