# Useful but Little-Known Features of Claude Agent SDK
🌍 Grant your agent access to files outside the working directory with the additionalDirectories option.
Essential for monorepos, shared libraries, and any project spanning multiple directory trees.
📌 Title: Granting Access Beyond the Working Directory
🔗 URL:
🧩 Overview
`additionalDirectories` is a `query()` option that allows agents to access paths outside the working directory (cwd). By default, agents can only operate on files within cwd. When you specify additional directories, the agent gains read/write access to files in those paths as well. In `acceptEdits` permission mode, edits within additional directories are also auto-approved. This is especially useful for monorepo packages, shared libraries, or cross-project workflows.
🛠 Usage
Pass `add_dirs` (TypeScript: `additionalDirectories`) in the query options.
```python
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
# Grant access to multiple monorepo packages
async for message in query(
prompt="Update the shared utility functions and fix the imports in the web app",
options=ClaudeAgentOptions(
add_dirs=[
"/path/to/monorepo/packages/shared-utils",
"/path/to/monorepo/packages/web-app",
],
permission_mode="acceptEdits", # Auto-approve edits in additional dirs too
allowed_tools=["Read", "Edit", "Write", "Grep", "Glob"],
),
):
if isinstance(message, ResultMessage) and message.subtype == "success":
print(message.result)
# Access a shared library alongside the main project
async for message in query(
prompt="Check the shared library API and update our integration code",
options=ClaudeAgentOptions(
add_dirs=[
"/path/to/shared-library",
],
allowed_tools=["Read", "Edit", "Grep", "Glob"],
),
):
if isinstance(message, ResultMessage) and message.subtype == "success":
print(message.result)
```
🏗 Integration into Production Systems
- In monorepo setups, list related package paths in `add_dirs` to enable cross-package changes with dependency awareness
- Combined with `acceptEdits` mode, file edits (Edit, Write) and filesystem operations (mkdir, rm, mv, cp) in additional directories are auto-approved
- Writes to protected paths still prompt even when included in additional directories
💡 Use Cases
📦 Monorepo development: modify shared packages and individual apps simultaneously
📚 Shared library reference: read external library source to verify correct API usage while coding
🔧 Centralized config management: access and update configuration directories outside the project
⚠️ Caveats
- Access to paths outside both cwd and additional directories remains blocked or prompted
- `bypassPermissions` mode approves all paths regardless of `add_dirs` settings
- This expands the agent's security boundary — specify only the minimum necessary paths
- `acceptEdits` auto-approval is scoped to cwd and additional directories only
✨ additionalDirectories enables agents to work seamlessly across multiple directory trees, making cross-project and monorepo workflows practical.
#
ClaudeAgentSDK# #
AIAgent#