Repository navigation
Add repository-level code graph support for AI-assisted navigation #1575
Description
Related to an existing integration?
No
Existing integration
N/A
Overview
CommunityToolkit/Aspire contains a growing number of integrations organized across src/, tests/, examples/, documentation, and repository-specific agent guidance.
AI coding assistants can navigate this today with text and code search, but they still need to repeatedly reconstruct relationships between an integration, its hosting extensions, resource types, tests, examples, documentation, and related projects.
I would like to propose adding repository-level code graph support so AI coding assistants can query a machine-readable representation of the repository before falling back to broad file searches.
Useful relationships could include:
- integration project → public hosting extension methods / resource types
- project → references → project / package
- implementation → related unit and integration tests
- implementation → related examples and documentation
- type / member → calls / uses / inherits → type / member
This would be repository tooling only and would not need to become a runtime dependency of any CommunityToolkit Aspire integration.
Graphify is one existing implementation that could be evaluated. The proposal is primarily about the artifact and capability, not a requirement to adopt this specific tool. The generated representation and tooling should remain replaceable.
The graph could be generated or refreshed in CI and then committed, published as an artifact, exposed through MCP, or generated on demand. That delivery choice could be decided separately.
I tested this approach on another .NET repository. The full source corpus was roughly 193k tokens, while graph-backed retrieval averaged roughly 4.3k tokens of relevant context per query. This is not intended as a formal benchmark, but it made repository exploration noticeably cheaper and more focused for an AI agent.
Usage example
Before modifying an Aspire hosting integration, an AI coding assistant could query the graph rather than broadly scanning the repository:
User: Update the hosting integration for a resource.
Agent:
1. Query the repository graph for the integration project.
2. Discover its public hosting extension methods and resource types.
3. Retrieve the related tests, examples, and documentation.
4. Load only those files into context.
5. Make the change and run the relevant test subset.
Another useful scenario is impact analysis:
Agent: What could be affected if this hosting extension changes?
Graph → hosting extension → resource type → referenced packages
→ integration tests → examples → documentation
This could also help human contributors with onboarding and architecture exploration. An interactive visualization could be generated from the same graph, but the main motivation is efficient machine-readable navigation for coding agents.
Breaking change?
No
Alternatives
Current alternatives include:
- letting each coding agent repeatedly use text search, file discovery, and symbol search;
- relying on IDE or LSP indexing available only in the local development environment;
- maintaining hand-written architecture documentation;
- allowing every contributor or agent to generate its own local index independently.
Those approaches work, but they duplicate repository-discovery effort and provide no shared, versioned structural representation of the codebase.
Another alternative would be to define a small CommunityToolkit Aspire-specific graph or index format rather than use Graphify. I would prefer evaluating an existing tool first while keeping the generated representation and tooling replaceable.
Additional context
The repository already includes guidance for AI-assisted development. A repository-level graph could complement that guidance by providing a current structural view of integrations, hosting APIs, tests, examples, documentation, and project dependencies.
The goal is not to make AI-generated changes autonomous or bypass review. It is simply to give tools a cheaper and more deterministic way to answer questions such as where is this implemented, what is connected to it, and which tests and examples are relevant?
Help us help you
Yes, but only if others can assist
Activity
[-]Add a machine-readable code graph for AI-assisted repository navigation[/-][+]Add repository-level code graph support for AI-assisted navigation[/+]aaronpowell commentedon Sep 7, 2026
Ironically, despite my personal heavy use of GitHub Copilot, this repo is horribly unoptimised for working with AI coding agents. There's a very basic copilot instructions file that I wrote ages ago and has some of what you note, but it probably makes more sense to turn that into a
AGENTS.mdfile.There's probably some value in generating a bunch of skills for the repo too - currently there are some Prompts and Chat Modes - both of which are pretty legacy in the design of current harnesses.
axies20 commentedon Sep 7, 2026
Thanks — I agree that an
AGENTS.mdplus repository-specific skills would be useful, especially for documenting conventions and common workflows.For the structural/navigation side, I also came across [CodeGraph](https://github.com/colbymchenry/codegraph), which may actually be a better fit for this proposal than Graphify.
It builds a local code graph and exposes it to agents through MCP, so the agent can retrieve relevant symbols, call paths, dependencies, and impact information instead of repeatedly reconstructing those relationships through search. It also has C# support and now understands ASP.NET Razor / Blazor relationships.
So these could potentially complement each other rather than compete:
AGENTS.md/ skills → repository conventions and workflowsThat also keeps the original idea fairly lightweight: the repo wouldn't need to maintain a custom graph format or use an LLM to generate the graph.
Odonno commentedon Sep 7, 2026
Note that there are graph tools that work locally on your machine.
nikolai-vysotskyi commentedon Sep 8, 2026
Disclosure: I maintain trace-mcp, which builds code graphs for coding agents across multiple languages including C#.
One architectural trap worth keeping in mind when evaluating code graph tools for this repository: C# namespace import fan-out.
Unlike Python modules or JS/TS files, a C#
using Acme.Store;directive does not mean the importing file depends on every file that declaresnamespace Acme.Store. When we benchmarked naive file-to-file dependency resolution on namespace imports in real .NET codebases (such as Newtonsoft.Json), it produced an average of 86 resolved dependency edges per file because C# namespaces routinely span dozens of files across a project.If a code graph tool creates edges for plain namespace
usingstatements, the graph becomes a dense hairball that pollutes the agent's context with hundreds of irrelevant connections. Clean graph extraction in C# requires distinguishing between:using Namespace;(which only opens scope and should not create file dependency edges).using static Namespace.Type;orusing Alias = Namespace.Type;), which map to exact declaring files.aaronpowell commentedon Sep 9, 2026
I'm not sure that we'd find a whole lot of value in this project from some tool that's doing indexing of the code because this repo isn't really that code heavy or containing much in the way of complex code - a lot of the integrations are really simplistic.
Additionally, there's very little intersection between the code in this repo. The repo is really just a monorepo of isolated projects. Integrations are referenced by their example and test projects, but there's not really anything more than that (yes, there is a small overlap with things like DbGate that are a meta package consumed in other packages).
I think we should start simple -
AGENTS.mdthat outlines the repo structure and the common patterns, then some skills which are for the specific tasks (how to write certain patterns, like the TypeScript tests, the container tags C# file, etc.). This also results in the lowest overhead - no need to bootstrap additional tools or anything.Odonno commentedon Sep 9, 2026
Probably a very lightweight
AGENTS.mdand some interesting skills like:And some useful ones I didn't consider.
aaronpowell commentedon Sep 12, 2026
I did write agents, well
chat-modesas they were called then, that did the first two, but they'd be woefully out of date 😅aaronpowell commentedon Oct 1, 2026
Following the research into the repo's current Copilot/AI configuration, we're going to undertake a guidance-first modernization focused primarily on the broad GitHub Copilot harness family—especially Copilot App and CLI, followed by cloud agent, code review, and IDE experiences. Compatibility with Claude, Codex, and other tools is useful where shared formats support it, but it is secondary.
The plan is to:
Establish clear instruction layers
.github/copilot-instructions.mdas a concise, universal Copilot baseline.AGENTS.mdfor cross-agent repository orientation without duplicating the Copilot instructions..github/instructions/*.instructions.mdfiles for areas such as tests, examples, generated API baselines, and workflows.Move repeatable workflows into skills
.agents/skills/for detailed, on-demand procedures.client-integration-authoringskill.Keep custom agents thin
Retire legacy customization formats
.chatmode.mdfile now that a custom agent and authoring skill replace it.my-issuesandmy-pull-requestsprompt files; prompt files are deprecated for current Agent Host sessions and these are not shared repository engineering guidance.Improve Copilot cloud-agent setup
copilot-setup-steps.ymlfrom only installinggh-awto preparing a deterministic baseline for common .NET restore/build/test work.Treat AI guidance as maintained repository infrastructure
We're explicitly parking repository code-graph tooling. This repo is largely a collection of isolated, convention-heavy integration packages, and we don't expect graph indexing, generated artifacts, required MCP setup, or benchmarking to provide enough value to justify their overhead. We can revisit that only if a concrete navigation problem emerges that instructions, skills, LSP, and normal repository search cannot solve.
chore: modernize repository AI guidance (CommunityToolkit#2216)