Workspace Management in code-graph-rag: How to Handle Multiple Repositories

The workspace feature in code-graph-rag lets users manage any number of independent source-code repositories under a single logical context through TOML-based configuration files stored in ${CGR_HOME}/workspaces.

Working with multiple codebases is a common challenge in modern development. The vitali87/code-graph-rag project solves this through a lightweight workspace management system that tracks repositories without requiring a database. This article explains how the workspace management in code-graph-rag handles multiple repositories using plain TOML files and Pydantic validation.

How Workspaces Store Multiple Repositories

Each workspace is persisted as a *.cgr-workspace file inside ${CGR_HOME}/workspaces, as defined by workspaces_dir in codebase_rag/workspaces/storage.py. The file follows the schema defined by WorkspaceConfig in codebase_rag/workspaces/models.py.

The WorkspaceConfig model contains three key fields:

• name – the unique workspace identifier
• description – optional free-text documentation
• repos – a list of WorkspaceRepo objects, each storing the absolute path of a repository and its inferred project_name

This structure allows a single workspace to reference repositories located anywhere on the filesystem.

Adding Repositories to a Workspace

The add_repo(name, repo_path, …) function in codebase_rag/workspaces/storage.py handles repository registration. It performs four operations:

1. Resolves the supplied path to an absolute path
2. Validates that the directory exists
3. Checks for duplicate entries
4. Appends a new WorkspaceRepo to the workspace's repos list before persisting the updated TOML file

from codebase_rag.workspaces.storage import create_workspace, add_repo

# Create an empty workspace named "my-project"

ws_cfg, _ = create_workspace("my-project", description="Demo workspace")

# Add the first repository

ws_cfg, _ = add_repo("my-project", "~/src/repo-one")

# Add a second repository, overriding the inferred name

ws_cfg, _ = add_repo("my-project", "~/src/repo-two", project_name="custom-two")

Removing Repositories from a Workspace

The remove_repo(name, repo_path, …) function in codebase_rag/workspaces/storage.py reverses the process. It loads the workspace, locates the matching repository via WorkspaceConfig.find_repo, removes it from the internal list, and rewrites the workspace file.

from codebase_rag.workspaces.storage import remove_repo

ws_cfg, removed = remove_repo("my-project", "~/src/repo-one")
print(f"Removed {removed.project_name}")

Listing and Enumerating Workspaces

To discover available workspaces, list_workspaces() in codebase_rag/workspaces/storage.py enumerates all *.cgr-workspace files in the workspaces directory and returns the sorted base names.

from codebase_rag.workspaces.storage import list_workspaces

print("Available workspaces:", list_workspaces())

CLI Integration for Workspace Management

The codebase_rag/workspaces/cli.py module exposes terminal commands that invoke the storage functions:

• cgr workspace add-repo – adds a repository to a workspace
• cgr workspace remove-repo – removes a repository from a workspace
• Additional commands for creation, deletion, and listing

This CLI interface allows users to manipulate multiple repositories without writing Python code directly.

Design Philosophy: Lightweight and Portable

The workspace management in code-graph-rag is deliberately minimal. By using plain TOML for persistence and Pydantic for validation, the system achieves:

• Fast file I/O – no database connection overhead
• Human-readable configuration – users can inspect and edit .cgr-workspace files directly
• Version control friendly – workspace files can be committed alongside project documentation
• Cross-platform compatibility – absolute paths work on any system where the repositories exist

Summary

• Workspaces are stored as TOML files (*.cgr-workspace) in ${CGR_HOME}/workspaces
• Each workspace tracks multiple repositories through a list of WorkspaceRepo objects containing absolute paths and project names
• add_repo() and remove_repo() in codebase_rag/workspaces/storage.py handle repository lifecycle operations
• list_workspaces() provides enumeration of all defined workspaces
• The CLI in codebase_rag/workspaces/cli.py exposes these functions as terminal commands
• The design prioritizes speed and simplicity over complex database-driven approaches

Frequently Asked Questions

What file format does code-graph-rag use for workspace storage?

Workspaces are stored as TOML files with the extension .cgr-workspace. This format was chosen for human readability and easy editing without specialized tools. The files reside in the ${CGR_HOME}/workspaces directory.

Can two workspaces reference the same repository path?

Yes. The workspace management in code-graph-rag does not enforce exclusive ownership of repository paths. Multiple workspaces can independently reference the same absolute path, and the same repository can be added to a single workspace with different project_name values if needed.

How does the system handle repository paths that don't exist?

The add_repo() function validates path existence before adding to a workspace. If the supplied path cannot be resolved or does not point to a valid directory, the operation fails before modifying the workspace configuration.

Is there a limit to how many repositories a workspace can contain?

No artificial limit exists. Because workspaces are simple TOML files, the practical constraint is file size and parse time. The lightweight design uses standard file I/O, so workspaces can scale to hundreds of repositories without performance degradation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}