Cocoa

Inspiration

As AI coding tools became more powerful, we noticed a growing problem: AI agents are great at generating code, but they struggle to understand large existing codebases efficiently. Instead of reasoning about a project’s structure, they often search through dozens of files, wasting huge amounts of context and missing important relationships between functions and modules.

We were inspired by the idea of giving AI coding agents a “GPS for codebases.” Humans use maps to navigate complex systems quickly, so we wanted to create a tool that helps AI navigate repositories the same way.

That idea became Cocoa — a system that transforms Python repositories into structured dependency maps so AI can understand, debug, and navigate large projects faster and more accurately.

What it does

Cocoa transforms Python repositories into structured dependency maps for AI coding agents.

Instead of forcing AI to blindly read entire files, Cocoa analyzes the repository and builds a graph of:

functions and classes
imports and dependencies
function call relationships
module connections
important code pathways

Using MCP tools, AI assistants like Claude Code can first view a high-level overview of a repository and then zoom into only the relevant parts of the codebase.

This helps AI coding agents:

understand projects faster
debug more accurately
reduce unnecessary context usage
navigate large codebases more efficiently

In simple terms, Cocoa gives AI coding agents a GPS for codebases.

How we built it

We built Cocoa using Python’s AST (Abstract Syntax Tree) module for static code analysis. The AST parser extracts important structural information from Python files without executing the code.

We then:

indexed repository files and directories
resolved imports and dependencies
built dependency graphs between functions and modules
generated structured XML outputs optimized for AI reasoning
integrated the system with MCP so Claude Code could query the codebase intelligently
added file watching to automatically re-index files when changes occur

Tech Stack

Python
AST
FastMCP
watchdog
FastAPI
Anthropic API
XML formatting

Challenges we ran into

One of the biggest challenges was dealing with Python’s dynamic nature. Static analysis works well for most code, but patterns like dynamic imports, decorators, and runtime-generated behavior are difficult to resolve perfectly without actually executing the program.

Another major challenge was token efficiency. Large repositories contain enormous amounts of information, so we had to carefully design progressive context loading systems to ensure AI agents only receive the most relevant information instead of wasting context on unnecessary files.

We also spent significant time designing a structured schema that both humans and AI agents could reliably understand while still preserving important dependency relationships between modules and functions.

Finally, integrating the system with MCP tools and keeping the repository index updated in real time required careful coordination between indexing, formatting, and file-watching systems.

Accomplishments that we're proud of

We’re proud that we built a system that turns large codebases into structured maps that AI agents can reason about efficiently.

Some accomplishments we’re especially excited about:

building a working dependency graph system using static analysis
integrating directly with MCP tools for AI-assisted development
creating progressive context loading to reduce token waste
designing structured outputs optimized specifically for AI reasoning
building a live-updating indexing system for changing repositories

Most importantly, we built a project that solves a real problem developers are beginning to face as AI coding workflows become more common.

What we learned

Through building Cocoa, we learned a lot about:

static code analysis
dependency graph construction
MCP architecture
token optimization for AI systems
how AI agents reason about structured versus unstructured information

One of our biggest takeaways was that AI coding assistants become dramatically more useful when they are given structured context instead of raw files.

We also learned how difficult it is to balance completeness with efficiency when designing systems for large language models, especially when working with large repositories and dynamic programming languages like Python.