Multi-Repo Support

Work across multiple repositories simultaneously with Blocks

Overview

Modern development often involves multiple repositories—microservices, frontend/backend splits, shared libraries, and more. Blocks understands this architecture and can:

• Search and analyze code across all your repositories
• Make changes to multiple repos in a single session
• Create coordinated PRs across repositories
• Answer questions about cross-repo interactions
• Generate status reports spanning multiple projects

How It Works

Blocks automatically identifies which repositories are relevant to your request based on:

• Workspace Configuration: Repositories connected to your workspace
• Context: The platform where you make the request (GitHub, Slack, Linear)
• Explicit Mentions: Repository names or paths you specify
• Request Analysis: Understanding which repos are needed for your task

You don’t need to manually specify repositories in most cases—Blocks intelligently determines what it needs to access although it ideal if possible.

Example Use Cases

Cross-Repo Search

Search for code patterns, functions, or configurations across all your repositories:

@blocks find all places where we're using the old authentication API
across all repos

Blocks will:

• Search through all connected repositories
• Identify matching files and lines
• Provide links to each location
• Summarize the findings

Multi-Repo Changes

Make coordinated changes across multiple repositories:

@blocks update the user model interface in both the backend and
frontend repos to add the new 'role' field

Blocks will:

• Modify files in multiple repositories
• Create separate PRs for each repo
• Ensure consistency across changes
• Link the PRs for easy tracking

Status Reports

Get comprehensive status reports across your entire project:

@blocks summarize all open PRs and recent commits across our microservices
repos from the last week

Blocks will:

• Analyze all relevant repositories
• Compile information from each
• Provide an organized summary
• Include links to PRs and commits

Architecture Analysis

Understand how your multi-repo architecture works:

@blocks explain how the user authentication flow works from the
React frontend through the API gateway to the auth service

Blocks will:

• Analyze code in frontend, API, and service repos
• Trace the data flow across boundaries
• Explain interactions between services
• Identify integration points

Consistency Checking

Verify consistency across repositories:

@blocks check if our error handling patterns are consistent between
the backend and frontend repos

Blocks will:

• Analyze patterns in each repository
• Identify inconsistencies
• Suggest improvements
• Recommend a unified approach

Viewing Connected Repositories

To see which repositories Blocks can access:

1. Open Blocks Dashboard
2. Go to Settings → Integrations → GitHub → View Repositories
3. View the list of connected repositories

Best Practices

Be Explicit When Needed

While Blocks is smart about finding relevant repos, you can be explicit:

@blocks /claude search for the User interface definition in the
'backend-api' and 'frontend-web' repos

Organize Repository Access

For team workspaces:

• Add only the repositories your team actively uses
• Remove archived or deprecated repos to reduce noise
• Use clear repository naming conventions
• Document which repos serve which purposes

Use Multi-Repo for Migrations

Multi-repo support is excellent for coordinated migrations:

@blocks update all our repos to use the new logging library v2.0
and create PRs for each

Leverage Cross-Repo Analysis

Take advantage of Blocks’ ability to see the big picture:

@blocks analyze our entire microservices architecture and identify
potential performance bottlenecks

Create Coordinated PRs

When making related changes across repos:

@blocks implement the new payment flow - update the frontend components
in 'web-app', the API endpoints in 'backend-api', and the processing
logic in 'payment-service'

Blocks will create linked PRs with consistent naming and descriptions.

Advanced Multi-Repo Workflows

Workflow 1: API Contract Changes

When updating an API that multiple services depend on:

@blocks we're adding a new 'metadata' field to the User API response.
Update the API definition in 'api-gateway', update clients in 'web-app'
and 'mobile-app', and ensure backward compatibility.

Blocks will:

1. Update the API schema
2. Modify client code in both apps
3. Add backward compatibility handling
4. Create PRs for all three repos
5. Link them with explanatory descriptions

Workflow 2: Shared Library Updates

When updating a shared library used across repos:

@blocks the new version of our shared-utils library has breaking changes.
Find all usages across our repos and update them to the new API.

Blocks will:

1. Identify all repositories using the library
2. Find all usage locations
3. Update code to match new API
4. Test compilation/linting
5. Create PRs for each affected repo

Workflow 3: Security Audits

For security reviews across your entire codebase:

@blocks /claude perform a security audit across all our repos looking
for hardcoded credentials, SQL injection risks, and XSS vulnerabilities

Blocks will:

1. Scan all connected repositories
2. Identify potential issues in each
3. Categorize by severity
4. Provide fix recommendations
5. Create issues or PRs as needed

Repository Context in Different Platforms

In GitHub

When you mention @blocks in a GitHub issue or PR:

• Blocks has access to the current repository by default
• You can reference other connected repos explicitly
• Blocks can create PRs in any accessible repo

In Slack

When you mention @blocks in Slack:

• Blocks has access to all connected repos
• You can specify which repos to focus on
• Ideal for cross-repo questions and status updates

In Linear

When you mention @blocks in a Linear issue:

• Blocks has access to all connected repos
• The Linear issue can link to multiple repos
• Blocks can create PRs and reference them in the issue

Limitations and Considerations

Permission Requirements

• Blocks can only access repositories you’ve explicitly granted access to
• In organization workspaces, permissions are managed at the workspace level
• Private repositories require appropriate GitHub App installation

Performance

• Very large operations across many repos may take longer
• Blocks processes repositories intelligently to optimize speed
• Complex cross-repo analyses benefit from specific scoping

Coordination

• When creating multiple PRs, review them together for consistency
• Use Plan Mode for complex multi-repo changes
• Link related PRs in descriptions for easy tracking

Troubleshooting

Blocks Can't Access a Repository

Solution: Grant Blocks access to the repository

1. Go to Dashboard → Settings → Integrations → GitHub
2. Click “Configure” to add more repositories
3. Select the repository and approve permissions

Blocks Searches Wrong Repositories

Solution: Be explicit about which repos to search

@blocks search only in 'backend-api' and 'auth-service' repos for...

Multi-Repo Operation Too Slow

Solution: Narrow the scope

• Specify which repositories to work with
• Break large operations into smaller chunks
• Use more specific queries to reduce search space

Next Steps

Getting Started

Learn the basics of using Blocks

Agents Overview

Choose the best agent for multi-repo tasks

Plan Mode

Plan complex multi-repo changes before implementing

Organization Workspaces

Manage team access to multiple repositories