Modern software rarely lives in a single repository. Microservices, shared libraries, and modular monorepos mean that changing one function might break code in a completely different repo.

CKB's federation preset solves this. Here's how to use it for cross-repo refactoring.

The Cross-Repo Problem

You want to rename UserService.GetUser() to UserService.FetchUser(). Sounds simple, but:

3 microservices import your user library
A shared SDK wraps this function
2 internal tools call it directly
Documentation references the old name

Without federation, you're grep-ing across repos, hoping you found everything. With federation, CKB traces all dependencies automatically.

Setting Up Federation

1. Index All Repositories

Each repo needs a CKB index:

# In each repository
cd ~/repos/user-service && ckb init && ckb index
cd ~/repos/api-gateway && ckb init && ckb index
cd ~/repos/mobile-backend && ckb init && ckb index
cd ~/repos/shared-sdk && ckb init && ckb index

2. Configure Federation

Create a federation config that links them:

// ~/.ckb/federation.json
{
  "repositories": [
    { "name": "user-service", "path": "~/repos/user-service" },
    { "name": "api-gateway", "path": "~/repos/api-gateway" },
    { "name": "mobile-backend", "path": "~/repos/mobile-backend" },
    { "name": "shared-sdk", "path": "~/repos/shared-sdk" }
  ],
  "dependencies": {
    "api-gateway": ["user-service", "shared-sdk"],
    "mobile-backend": ["user-service", "shared-sdk"]
  }
}

3. Use the Federation Preset

{
  "mcpServers": {
    "ckb": {
      "command": "npx",
      "args": ["@tastehub/ckb", "mcp", "--preset=federation"]
    }
  }
}

Refactoring Workflow

Let's walk through renaming UserService.GetUser() across all repos.

Step 1: Find All Usages

User: "Find all usages of UserService.GetUser across all repos"

AI: [calls federatedSearch for "GetUser"]
    [calls findReferences with federation scope]

"Found 47 references across 4 repositories:

user-service (origin):
- user_service.go:45 - definition
- user_service_test.go:23, 67, 89 - tests

shared-sdk:
- client.go:123 - wrapper function
- client_test.go:45 - test

api-gateway:
- handlers/user.go:34, 78 - HTTP handlers
- handlers/auth.go:56 - auth flow

mobile-backend:
- api/users.go:23, 45, 67 - REST endpoints
- api/profile.go:12 - profile endpoint"

Step 2: Assess Cross-Repo Impact

User: "What's the impact of renaming GetUser to FetchUser?"

AI: [calls federatedImpact for the rename]

"Cross-repository impact:

Direct callers requiring updates: 12
Transitive impact: 23 additional files

Breaking changes by repo:
- shared-sdk: BREAKING - public API change
- api-gateway: Internal only, safe
- mobile-backend: Internal only, safe

Suggested order:
1. Update user-service (source)
2. Update shared-sdk (re-export or alias for compatibility)
3. Update api-gateway and mobile-backend in parallel
4. Remove compatibility alias after deployment"

Step 3: Check for Version Constraints

User: "Are there any version constraints I need to worry about?"

AI: [calls getDependencyVersions]

"Version analysis:

api-gateway imports user-service@v2.3.1
mobile-backend imports user-service@v2.3.0

Concern: mobile-backend is one patch behind.
Recommendation: Update mobile-backend to v2.3.1 first,
then coordinate the rename across all repos simultaneously."

Step 4: Generate Migration Plan

User: "Create a migration plan"

AI: [aggregates analysis]

"## Migration Plan: GetUser → FetchUser

### Phase 1: Preparation
- [ ] Update mobile-backend to user-service@v2.3.1
- [ ] Ensure all repos are on compatible versions

### Phase 2: Backward-Compatible Change
- [ ] user-service: Add FetchUser as alias for GetUser
- [ ] user-service: Mark GetUser as deprecated
- [ ] Release user-service@v2.4.0

### Phase 3: Consumer Updates
- [ ] shared-sdk: Update to use FetchUser, release v1.5.0
- [ ] api-gateway: Update all 2 call sites
- [ ] mobile-backend: Update all 4 call sites

### Phase 4: Cleanup
- [ ] user-service: Remove GetUser alias
- [ ] Release user-service@v3.0.0 (breaking)

### Files to Modify
Total: 14 files across 4 repositories
Tests affected: 8 files"

Federation Tools

`federatedSearch`

Search symbols across all federated repositories:

{
  "query": "GetUser",
  "scope": "all",  // or specific repo names
  "kind": "function"
}

`federatedImpact`

Analyze impact across repository boundaries:

{
  "target": "ckb:user-service:sym:abc123",
  "changeType": "rename",
  "includeTransitive": true
}

`getDependencyGraph`

Visualize how repositories depend on each other:

{
  "root": "user-service",
  "depth": 2,
  "includeVersions": true
}

`federatedReferences`

Find all references across repos with grouping:

{
  "symbolId": "ckb:user-service:sym:abc123",
  "groupBy": "repository"
}

Best Practices

1. Index Regularly

Set up automated indexing to keep federation data fresh:

# Cron job or CI step
ckb index --incremental
ckb federation sync

2. Use Semantic Versioning

CKB's impact analysis is most accurate when repos use semver properly. Breaking changes should bump major versions.

3. Plan Breaking Changes

For public API changes:

Add new method alongside old
Deprecate old method
Update all consumers
Remove old method in next major version

4. Coordinate Releases

Use the migration plan to coordinate releases across teams. CKB identifies the safe order based on dependency analysis.

Enterprise Considerations

For large organizations:

Repository discovery - CKB can scan organization folders to find related repos
Access control - Federation respects repo-level permissions
Incremental indexing - Only re-index changed files for speed
Central server - Optional CKB server for shared indexes

Real-World Example

A fintech company used CKB federation to rename their core Transaction type across 12 microservices:

Without CKB: Estimated 2 weeks of grep-ing, testing, and coordinating
With CKB: Complete impact analysis in 10 minutes, migration completed in 3 days

The key win: CKB found 3 usages in a deprecated service that would have been missed manually.

Links: