When debugging code, experienced developers don't start by reading every file in the repository. They trace execution paths, follow function calls, and leverage their understanding of the system architecture. Yet many AI coding tools today work like developers who haven't learned these navigation skills—they rely on basic file listings and attempt to cram as much code as possible into their limited context windows. With most models capped at 200K tokens, this brute force approach quickly hits limits, especially when dealing with large codebases. Even with the latest models' expanded context windows, indiscriminately loading files is neither efficient nor effective.
Think about how you actually solve coding problems. If you're debugging a database timeout, you don't need to see the UI components or authentication logic; you just need to understand the query construction, database access patterns, and perhaps relevant configuration settings. The same principle applies to AI coding assistants: more context isn't always better. What they need is relevant context.
How AI coding agents search code today
Modern AI coding assistants use several approaches to navigate and understand codebases, each with their own strengths and opportunities for improvement:
- Agentic search: AI agents like Open Hands use filesystem navigation tools (similar to
ls,cat,grep) to explore codebases organically. While flexible, this can be inefficient as agents may need to explore many paths before finding relevant code. - Repository map: Tools like Aider maintain a structured view of the codebase, mapping functions, docstrings, and hierarchies. In the limit of infinite context, this is a list of every function in the repo and the associated doc-strings and types and function hierarchies for those functions. Unfortunately, we don't have access to infinite context LLMs. To work within context limits, representations like repo map use techniques like PageRank in order to focus on smaller code sections, by prioritizing functions that are called most frequently. While this approach can reduce the size of the map effectively, it can miss important contextual relationships.
- Semantic search: This approach embeds code chunks into vector space to enable natural language queries. While promising, the challenge lies in bridging the gap between code and natural language semantics. Some systems improve results by having LLMs generate intermediate descriptions, but the approach still faces challenges with technical precision.
Each approach has improved our ability to help AI understand codebases, but there's still room for improvement in combining their strengths while addressing their limitations.
Introducing the Nuanced code graph
Experienced developers navigate code by following function calls and understanding data flows–they instinctively know how to trace execution paths to find what matters. While call graphs try to mimic this behavior, most current tools lack the rich understanding of code relationships needed to do this effectively.
This is where the Nuanced code graph comes in. Instead of front-loading large amounts of potentially irrelevant code, we provide AI coding tools with a rich, queryable knowledge graph that uses static analysis to surface:
- Call graphs showing function relationships and execution paths
- Data flow analysis revealing how information moves through the system
- Dependency maps highlighting external service interactions
- Architecture-aware navigation that understands your system's structure
For example, when investigating a database timeout issue, an AI assistant using Nuanced can:
- Identify the specific query causing the timeout
- Trace backwards through the call graph to see how that query is constructed
- Find similar queries elsewhere in the codebase that might have related optimizations
- Understand what configuration settings affect query timeout behavior
We compress the information needed to make it efficiently queryable. Rather than overwhelm AI assistants with raw data, we provide a distilled representation that captures the essential relationships and behaviors they need to understand.
This focused approach means AI assistants spend less time processing irrelevant code and more time solving the actual problem. It's like giving them an experienced developer's intuition about where to look and what matters.
Building the Nuanced CLI: a peek at what’s coming
We're developing tools to help AI coding assistants understand your code the way experienced developers do. Here's an early look at what we're building.
We're building a CLI that will let you do the following:
# Initialize the knowledge graph
nuanced init <repo-path>
# Get rich context for any function
nuanced enrich src/auth.py:45:10
The enrich command turns static code into a rich, navigable context that helps AI assistants work more effectively. By generating smart call graphs, it helps AIs understand not just where functions are defined, but how they're actually used throughout your codebase. Combined with detailed analysis of data modifications, type information, and execution paths, this gives AI assistants the context they need to make informed decisions.
Most importantly, by surfacing side effects and state changes, it helps prevent the kind of subtle bugs that plague AI-generated code today.
Help shape our direction
We're starting with Python support, focusing on precise function-level analysis. While our initial release requires specific code locations, we're also exploring natural language queries that automatically find relevant code.
Our aim is to build our knowledge graph to go beyond simple static analysis by incorporating information about runtime behavior patterns, system architecture information, common failure modes and edge cases, as well as providing an interface for builders to define team-specific patterns and conventions.
We're in early stages and would love to hear from developers and AI companies building in this space. What context do your AI tools need? What problems are you trying to solve?
Join our waitlist for early access, updates on new features, and input on our roadmap, or get in touch on X or email at ayman@nuanced.dev.