> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codealive.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-Repository & Workspaces

> Search and analyze across multiple repositories and workspaces

## Overview

CodeAlive lets you search and analyze code across multiple repositories simultaneously. Group related repos into workspaces — for example, all backend services, or your entire platform — and query them as a single unit.

This is essential for microservices architectures, monorepo setups, and organizations with code spread across many repositories.

## Setting Up

<Steps>
  <Step title="Connect Your Providers">
    In the [CodeAlive dashboard](https://app.codealive.ai):

    1. Navigate to **Providers**
    2. Connect your GitHub, GitLab, or Bitbucket account
    3. Authorize CodeAlive to access your repositories
  </Step>

  <Step title="Import Repositories">
    1. Go to **Data Sources**
    2. Click **Import Repositories**
    3. Select the repositories you want to index
    4. Wait for initial indexing (5-15 minutes per repository)
  </Step>

  <Step title="Create Workspaces">
    Group related repositories into workspaces:

    1. Go to **Workspaces** in the dashboard
    2. Click **Create Workspace**
    3. Give it a name (e.g., "backend-services", "platform-team")
    4. Add repositories to the workspace
  </Step>
</Steps>

## Workspaces

Workspaces let you group repositories and query them together. This is useful when:

* Your backend is split across multiple services
* You want to search across a team's repositories
* You need to trace data flows between services

### Querying Workspaces

Use the `workspace:` prefix to search across all repos in a workspace:

```bash theme={null}
# Search across all backend services
python scripts/search.py "error handling patterns" workspace:backend-team

# Chat about the whole platform
python scripts/chat.py "How do services communicate?" workspace:platform
```

### Querying Individual Repositories

Target specific repositories by name:

```bash theme={null}
# Search one repo
python scripts/search.py "JWT validation" auth-service

# Search multiple repos
python scripts/search.py "user model" auth-service user-service billing-service
```

## Cross-Repository Search

When searching across repositories, CodeAlive understands relationships between services:

```
"How does the auth service communicate with the user service?"
"Find all API contracts between frontend and backend"
"Show me shared database models across services"
"Trace the order flow from API to payment to notification"
```

## Data Sources

The `get_data_sources` tool lists all available repositories and workspaces:

| Type           | Description           | Example                  |
| -------------- | --------------------- | ------------------------ |
| **Repository** | Single codebase       | `my-backend-api`         |
| **Workspace**  | Group of repositories | `workspace:backend-team` |

Use `get_data_sources` to discover what's available before searching:

```bash theme={null}
python scripts/datasources.py                                # Ready-to-use sources
python scripts/datasources.py --all                          # All (including processing)
python scripts/datasources.py --query "add OAuth to checkout" # Only sources relevant to a task
```

<Tip>
  With many repositories indexed, pass your task as `query` (MCP) or `--query` (skill scripts). An AI
  relevance filter returns only the matching sources, each with a `relevanceReason`, so the agent
  starts from a focused shortlist instead of the full inventory.
</Tip>

## Best Practices

<CardGroup cols={2}>
  <Card title="Organize by Team" icon="users">
    Create workspaces per team or domain (backend, frontend, infrastructure)
  </Card>

  <Card title="Keep Repos Synced" icon="sync">
    Regularly sync repositories in the dashboard for accurate cross-repo analysis
  </Card>

  <Card title="Scope Searches" icon="target">
    Use specific repos for targeted queries, workspaces for cross-cutting concerns
  </Card>

  <Card title="Name Clearly" icon="tag">
    Use descriptive workspace names that match your team's vocabulary
  </Card>
</CardGroup>

## Related Resources

<CardGroup cols={2}>
  <Card title="Semantic Search" icon="magnifying-glass" href="/features/semantic-search">
    Search across repos by meaning and intent
  </Card>

  <Card title="Codebase Chat" icon="comments" href="/features/codebase-chat">
    Ask questions across your entire codebase
  </Card>

  <Card title="MCP Integration" icon="plug" href="/integrations/mcp">
    Connect multi-repo to your AI assistant
  </Card>

  <Card title="Dashboard" icon="gauge" href="https://app.codealive.ai">
    Manage repositories and workspaces
  </Card>
</CardGroup>