CodeGraphy: Local-First Code Architecture Visualizer

DEV Community

I built a local-first architecture visualizer and MCP server so AI agents stop hallucinating about my codebase

Working with AI coding assistants on a growing codebase usually hits the same wall: once a project crosses a few dozen files, the LLM starts losing track of how modules actually connect. You end up burning context window tokens just explaining your folder structure, or worse, watching the AI hallucinate imports that don't exist. To fix this in my own workflow, I built CodeGraphy — a local-first software architecture visualizer and Model Context Protocol (MCP) server. What it does Instead of static documentation that goes out of date the moment you commit, CodeGraphy parses your project locally and turns it into an interactive node graph, while exposing that same structural map directly to AI tools via MCP. 100% Local-First: Your code never leaves your machine. No cloud indexing, no API keys required for parsing. Interactive Visual Graph: Built with React Flow, letting you explore file dependencies, imports, and module boundaries visually instead of jumping through endless IDE tabs. Native MCP Server: Connects directly to MCP-compatible clients (like Claude Desktop, Cursor, etc.), allowing your AI assistant to query the actual dependency graph before suggesting architectural changes. Zero-Config CLI: You can spin up a lightweight version right from your terminal. Under the Hood I wanted the tool to be fast to run locally without heavy setup overhead: Backend & AST Parsing: Python + FastAPI Frontend & Graph Rendering: React, React Flow, and Zustand for state management Distribution: Available as a standalone desktop app and a lightweight Python package Try it out If you want to test it on your own repo, you can install the Lite version directly via pip: Bash pip install codegraphy-lite And run it inside your project directory: Bash codegraphy-lite (Insert a screenshot of the MCP tool call in action or the CLI output here) For the full desktop experience, pre-built binaries, and source code, check out the site: 👉 site: click What's next? I'm currently refining multi-language parsing support and optimizing graph layouts for larger monorepos. If you give it a spin, I'd love to hear what breaks, what's missing, or how you're currently giving your AI assistants architectural context. Drop a comment below!

Powered by Readybot.io