### Preflight Checklist - [x] I have searched [existing requests](https://github.com/anthropics/claude-code/issues?q=is%3Aissue%20label%3Aenhancement) and this feature hasn't been requested yet - [x] This is a single feature request (not multiple features) ### Problem Statement Summary Claude Code currently treats every repository as an isolated context. It has no mechanism to understand that repositories may be related — as siblings sharing conventions, as parent/child hierarchies, as provid

[FEATURE] Repository Relationship Awareness (Repo Topology)

Resolved 💬 2 comments Opened Feb 5, 2026 by kase1111-hash Closed Mar 6, 2026

Preflight Checklist

[x] I have searched existing requests and this feature hasn't been requested yet
[x] This is a single feature request (not multiple features)

Problem Statement

Summary
Claude Code currently treats every repository as an isolated context. It has no mechanism to understand that repositories may be related — as siblings sharing conventions, as parent/child hierarchies, as provider/consumer dependencies, or as forks/variants of common ancestry. Adding relationship-aware context loading would dramatically improve Claude Code's ability to maintain consistency across multi-repo ecosystems.
Problem
Developers working across multiple related repositories constantly fight context fragmentation:

Sister repos that should share architecture, naming conventions, and governance rules drift apart because Claude Code doesn't know they're related.
Breaking changes in a provider repo aren't flagged when working in a consumer repo.
Parent specs define interfaces that child implementations must honor, but Claude Code can't check compliance without manual context injection.
Forked or variant repos share ancestry but Claude Code can't reason about what diverged or why.

This is especially painful for developers maintaining ecosystems of 10+ interconnected repositories, where manually re-establishing context in every session is a significant tax on productivity.

Proposed Solution

<html>
<body>
<h3 class="text-text-100 mt-2 -mb-1 text-base font-bold">1. Relationship Declaration</h3>
A <code class="bg-text-200/5 border border-0.5 border-border-300 text-danger-000 whitespace-pre-wrap rounded-[0.4rem] px-1 py-px text-[0.9rem]">.claude/repo-relations.json</code> (or equivalent in <code class="bg-text-200/5 border border-0.5 border-border-300 text-danger-000 whitespace-pre-wrap rounded-[0.4rem] px-1 py-px text-[0.9rem]">CLAUDE.md</code>) file at the project root that declares how the current repo relates to others:
<div class="relative group/copy bg-bg-000/50 border-0.5 border-border-400 rounded-lg"><div class="sticky opacity-0 group-hover/copy:opacity-100 top-2 py-2 h-12 w-0 float-right"><div class="absolute right-0 h-8 px-2 items-center inline-flex z-10"><button class="inline-flex
items-center
justify-center
relative
shrink-0
can-focus
select-none
disabled:pointer-events-none
disabled:opacity-50
disabled:shadow-none
disabled:drop-shadow-none border-transparent
transition
font-base
duration-300
ease-[cubic-bezier(0.165,0.85,0.45,1)] h-8 w-8 rounded-md active:scale-95 backdrop-blur-md Button_ghost__BUAoh" type="button" aria-label="Copy to clipboard" data-state="closed"><div class="relative"><div class="transition-all opacity-100 scale-100" style="width: 20px; height: 20px; display: flex; align-items: center; justify-content: center;"><svg width="20" height="20" viewBox="0 0 20 20" fill="currentColor" xmlns="http://www.w3.org/2000/svg" class="transition-all opacity-100 scale-100" aria-hidden="true" style="flex-shrink: 0;"><path d="M12.5 3C13.3284 3 14 3.67157 14 4.5V6H15.5C16.3284 6 17 6.67157 17 7.5V15.5C17 16.3284 16.3284 17 15.5 17H7.5C6.67157 17 6 16.3284 6 15.5V14H4.5C3.67157 14 3 13.3284 3 12.5V4.5C3 3.67157 3.67157 3 4.5 3H12.5ZM14 12.5C14 13.3284 13.3284 14 12.5 14H7V15.5C7 15.7761 7.22386 16 7.5 16H15.5C15.7761 16 16 15.7761 16 15.5V7.5C16 7.22386 15.7761 7 15.5 7H14V12.5ZM4.5 4C4.22386 4 4 4.22386 4 4.5V12.5C4 12.7761 4.22386 13 4.5 13H12.5C12.7761 13 13 12.7761 13 12.5V4.5C13 4.22386 12.7761 4 12.5 4H4.5Z"></path></svg></div><div class="absolute inset-0 flex items-center justify-center"><div class="transition-all opacity-0 scale-50" style="width: 20px; height: 20px; display: flex; align-items: center; justify-content: center;"><svg width="20" height="20" viewBox="0 0 20 20" fill="currentColor" xmlns="http://www.w3.org/2000/svg" class="transition-all opacity-0 scale-50" aria-hidden="true" style="flex-shrink: 0;"><path d="M15.1883 5.10908C15.3699 4.96398 15.6346 4.96153 15.8202 5.11592C16.0056 5.27067 16.0504 5.53125 15.9403 5.73605L15.8836 5.82003L8.38354 14.8202C8.29361 14.9279 8.16242 14.9925 8.02221 14.9989C7.88203 15.0051 7.74545 14.9526 7.64622 14.8534L4.14617 11.3533L4.08172 11.2752C3.95384 11.0811 3.97542 10.817 4.14617 10.6463C4.31693 10.4755 4.58105 10.4539 4.77509 10.5818L4.85321 10.6463L7.96556 13.7586L15.1161 5.1794L15.1883 5.10908Z"></path></svg></div></div></div></button></div></div><div class="text-text-500 font-small p-3.5 pb-0">json</div><div><pre class="code-block__code !my-0 !rounded-lg !text-sm !leading-relaxed p-3.5" style="color: rgb(234, 236, 240); background: transparent; font-family: var(--font-mono);"><code class="language-json" style="color: rgb(234, 236, 240); background: transparent; font-family: var(--font-mono); white-space: pre;">{
 "identity": "boundary-daemon",
 "relations": [
 {
 "repo": "agent-os-core",
 "type": "parent",
 "path": "../agent-os-core",
 "notes": "Core spec — this repo implements the security boundary module"
 },
 {
 "repo": "auth-gateway",
 "type": "sister",
 "path": "../auth-gateway",
 "notes": "Shares authentication patterns and constitutional governance rules"
 },
 {
 "repo": "natlangchain-spec",
 "type": "provider",
 "path": "../natlangchain-spec",
 "notes": "Consumes protocol definitions from this repo"
 },
 {
 "repo": "boundary-daemon-legacy",
 "type": "fork",
 "url": "https://github.com/original-author/boundary-daemon",
 "notes": "Revived from abandoned repo — diverged at v0.3.0"
 }
 ]
}</code></pre></div></div>
<h3 class="text-text-100 mt-2 -mb-1 text-base font-bold">2. Relationship Types</h3>
<div class="overflow-x-auto w-full px-2 mb-6">
Type | Meaning | Claude Code Behavior
-- | -- | --
parent | This repo implements or extends the parent's spec | Pull in parent's API surface, interfaces, and architectural decisions as context. Warn on incompatible changes.
child | This repo is extended by the child | Awareness of downstream impact when making changes.
sister | Shared conventions, style, governance | Propagate patterns. Flag when one sister diverges from established conventions.
provider | This repo consumes from the provider | Load provider's public API/types. Flag breaking changes upstream.
consumer | This repo is consumed by the consumer | Awareness of downstream consumers when changing public interfaces.
fork | Diverged copy of another repo | Track divergence. Enable reasoning about what changed and why.

</div>
<h3 class="text-text-100 mt-2 -mb-1 text-base font-bold">3. Context Loading Behavior</h3>
When Claude Code opens a repo with declared relations:
<ul class="[li_&]:mb-0 [li_&]:mt-1 [li_&]:gap-1 [&:not(:last-child)_ul]:pb-1 [&:not(:last-child)_ol]:pb-1 list-disc flex flex-col gap-1 pl-8 mb-3">
<li class="whitespace-normal break-words pl-2">Lazy load: Don't pull everything — load related context on demand when the current task touches a boundary (import, API call, shared pattern).</li>
<li class="whitespace-normal break-words pl-2">Convention inheritance: Sister and parent repos' <code class="bg-text-200/5 border border-0.5 border-border-300 text-danger-000 whitespace-pre-wrap rounded-[0.4rem] px-1 py-px text-[0.9rem]">CLAUDE.md</code> conventions could be inherited or merged, with local overrides taking precedence.</li>
<li class="whitespace-normal break-words pl-2">Change impact awareness: When modifying a public interface, Claude Code could check declared consumers/children and flag potential breakage.</li>
</ul>
<h3 class="text-text-100 mt-2 -mb-1 text-base font-bold">4. Workspace-Level Declaration (Optional)</h3>
For developers managing many repos, a workspace-level manifest could define the full topology in one place:
<div class="relative group/copy bg-bg-000/50 border-0.5 border-border-400 rounded-lg"><div class="sticky opacity-0 group-hover/copy:opacity-100 top-2 py-2 h-12 w-0 float-right"><div class="absolute right-0 h-8 px-2 items-center inline-flex z-10"><button class="inline-flex
items-center
justify-center
relative
shrink-0
can-focus
select-none
disabled:pointer-events-none
disabled:opacity-50
disabled:shadow-none
disabled:drop-shadow-none border-transparent
transition
font-base
duration-300
ease-[cubic-bezier(0.165,0.85,0.45,1)] h-8 w-8 rounded-md active:scale-95 backdrop-blur-md Button_ghost__BUAoh" type="button" aria-label="Copy to clipboard" data-state="closed"><div class="relative"><div class="transition-all opacity-100 scale-100" style="width: 20px; height: 20px; display: flex; align-items: center; justify-content: center;"><svg width="20" height="20" viewBox="0 0 20 20" fill="currentColor" xmlns="http://www.w3.org/2000/svg" class="transition-all opacity-100 scale-100" aria-hidden="true" style="flex-shrink: 0;"><path d="M12.5 3C13.3284 3 14 3.67157 14 4.5V6H15.5C16.3284 6 17 6.67157 17 7.5V15.5C17 16.3284 16.3284 17 15.5 17H7.5C6.67157 17 6 16.3284 6 15.5V14H4.5C3.67157 14 3 13.3284 3 12.5V4.5C3 3.67157 3.67157 3 4.5 3H12.5ZM14 12.5C14 13.3284 13.3284 14 12.5 14H7V15.5C7 15.7761 7.22386 16 7.5 16H15.5C15.7761 16 16 15.7761 16 15.5V7.5C16 7.22386 15.7761 7 15.5 7H14V12.5ZM4.5 4C4.22386 4 4 4.22386 4 4.5V12.5C4 12.7761 4.22386 13 4.5 13H12.5C12.7761 13 13 12.7761 13 12.5V4.5C13 4.22386 12.7761 4 12.5 4H4.5Z"></path></svg></div><div class="absolute inset-0 flex items-center justify-center"><div class="transition-all opacity-0 scale-50" style="width: 20px; height: 20px; display: flex; align-items: center; justify-content: center;"><svg width="20" height="20" viewBox="0 0 20 20" fill="currentColor" xmlns="http://www.w3.org/2000/svg" class="transition-all opacity-0 scale-50" aria-hidden="true" style="flex-shrink: 0;"><path d="M15.1883 5.10908C15.3699 4.96398 15.6346 4.96153 15.8202 5.11592C16.0056 5.27067 16.0504 5.53125 15.9403 5.73605L15.8836 5.82003L8.38354 14.8202C8.29361 14.9279 8.16242 14.9925 8.02221 14.9989C7.88203 15.0051 7.74545 14.9526 7.64622 14.8534L4.14617 11.3533L4.08172 11.2752C3.95384 11.0811 3.97542 10.817 4.14617 10.6463C4.31693 10.4755 4.58105 10.4539 4.77509 10.5818L4.85321 10.6463L7.96556 13.7586L15.1161 5.1794L15.1883 5.10908Z"></path></svg></div></div></div></button></div></div><div class="text-text-500 font-small p-3.5 pb-0">json</div><div><pre class="code-block__code !my-0 !rounded-lg !text-sm !leading-relaxed p-3.5" style="color: rgb(234, 236, 240); background: transparent; font-family: var(--font-mono);"><code class="language-json" style="color: rgb(234, 236, 240); background: transparent; font-family: var(--font-mono); white-space: pre;">{
 "workspace": "agent-os-ecosystem",
 "repos": {
 "agent-os-core": { "path": "./agent-os-core", "role": "spec" },
 "boundary-daemon": { "path": "./boundary-daemon", "role": "implementation" },
 "auth-gateway": { "path": "./auth-gateway", "role": "implementation" }
 },
 "groups": [
 {
 "name": "security-modules",
 "type": "sister",
 "members": ["boundary-daemon", "auth-gateway"]
 }
 ],
 "hierarchy": [
 { "parent": "agent-os-core", "children": ["boundary-daemon", "auth-gateway"] }
 ]
}</code></pre></div></div>
</body>
</html>

Alternative Solutions

Alternatives Considered

Monorepos: Solve some of these problems but aren't always practical, especially for ecosystems mixing original work with forked/revived repos.
Manual context via CLAUDE.md: Works today but requires developers to manually paste or reference related repos every session. Doesn't scale.
Git submodules: Handle dependency fetching but provide no semantic relationship information.

Priority

Medium - Would be very helpful

Feature Category

Other

Use Case Example

Ecosystem consistency: "Update the error handling pattern in boundary-daemon" → Claude Code checks sister repos to match the established pattern rather than inventing a new one.
Spec compliance: "Add a new endpoint to auth-gateway" → Claude Code pulls the parent spec to ensure the endpoint follows the defined interface contract.
Breaking change detection: "Rename this exported function" → Claude Code flags that 3 consumer repos import this function.
Fork management: "What's different between our version and the original?" → Claude Code can reason about divergence from the fork origin.
Convention propagation: Updating a linting rule or governance doc in a parent repo could prompt Claude Code to suggest the same update across children/sisters.

Additional Context

This feature would be especially valuable for:

Developers maintaining plugin/extension ecosystems
Teams working across microservice architectures
Anyone reviving or forking abandoned repositories who needs to track divergence
Projects using constitutional or governance-driven development patterns where rules must be consistent across related repos

The core insight is that project topology is structured knowledge that Claude Code could use to make better decisions, but currently there's no way to express it.

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗