Enhancement: Multi-Directory Workspace Support

[allenhutchison]

Overview

This proposal outlines a mechanism to allow the CLI to operate on an expanded set of directories beyond the initial working directory. The goal is to enable users to include files and folders from disparate locations within a single session, creating a virtual workspace. This will improve workflow flexibility, especially when related project files are spread across different folders.

Proposed Solution

1. Command-Line Argument

A new command-line argument will be introduced to define a set of "included" root directories at startup:

• Argument: --include-directories
• Format: A comma-separated list of paths.
• Example: gemini --include-directories /path/to/project-a/src,/path/to/shared-lib/

2. Slash Commands

A new command group, /directory, will be introduced for managing the workspace during a session:

• /directory add <path>: Dynamically adds the specified directory (absolute or relative) to the workspace for the current session.
• /directory show: Displays a list of all absolute directory paths currently included in the workspace.

Technical Implementation Details

Tool Integration

All file-system-aware tools (glob, read_file, write_file, list_directory, replace) must be updated to consult a new WorkspaceContext that maintains the set of allowed directory paths.

• Path Validation: Before any file operation, the target absolute path must be validated to ensure it is a child of any directory in the WorkspaceContext.
• Discovery Tools (glob, list_directory): These tools will be modified to execute their search across all directories in the WorkspaceContext and merge the results. All returned paths will be absolute to avoid ambiguity.

Path Resolution and Ambiguity

To prevent ambiguity, all file system tools will operate exclusively on absolute paths. When a user provides a relative path, it will be resolved against the initial working directory (cwd) only. Discovery tools are the exception and will return absolute paths from all workspace directories.

Symbolic Link Handling

To ensure security and consistency, the feature will follow symbolic links but will validate the canonical, resolved path against the workspace.

• Before any file operation, fs.promises.realpath() will be used to resolve the true absolute path.
• This resolved path will then be checked against the allowed directories, preventing sandbox escapes via symlinks pointing outside the workspace.

Sandboxing Analysis

The feature's behavior will depend on the active sandbox profile:

• restrictive-closed Profiles:

  • --include-directories: Supported. The paths will be used to generate a more permissive sandbox profile at startup.
  • /directory add: Not supported. This command will be disabled and return an explanatory message, as the sandbox cannot be altered dynamically.

• permissive-open / permissive-proxied Profiles:

  • Both --include-directories and /directory add will be fully supported, as the application's internal path validation is the primary security mechanism.

Non-Goals

• This feature will not create a virtual file system or merge directory structures.
• Dynamic removal of directories from the workspace (e.g., a /directory remove command) is explicitly out of scope to prevent loss of context and other potential issues. Users should restart the session to narrow the workspace.

[darkblitzrc]

YES WE NEED THIS!!

[TzachiNoy]

In addition to the proposed command-line argument and slash commands, it would be highly beneficial to have an option to define these included directories within a configuration file (e.g., .geminidirs) located in the main workspace. This would streamline setup for multi-directory projects.