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

> Learn how code-graph-rag manages multiple repositories seamlessly using TOML-based configuration. Explore efficient workspace management for your code projects.

- Repository: [Vitali Avagyan/code-graph-rag](https://github.com/vitali87/code-graph-rag)
- Tags: how-to-guide
- Published: 2026-08-16

---

**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`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/workspaces/storage.py). The file follows the schema defined by `WorkspaceConfig` in [`codebase_rag/workspaces/models.py`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/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

```python
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`](https://github.com/vitali87/code-graph-rag/blob/main/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.

```python
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`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/workspaces/storage.py) enumerates all `*.cgr-workspace` files in the workspaces directory and returns the sorted base names.

```python
from codebase_rag.workspaces.storage import list_workspaces

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

```

## CLI Integration for Workspace Management

The [`codebase_rag/workspaces/cli.py`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/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.