Codesight: AI-Ready Codebase Structure Generator

What It Is

Codesight is a command-line tool that generates a compact, structured overview of a codebase before AI assistants like Claude start exploring files. Instead of letting Claude burn through tens of thousands of tokens reading files to understand project structure, codesight creates a set of markdown files that map out routes, database schemas, components, environment variables, and import dependencies. The tool runs as a single npx command with zero runtime dependencies, parsing TypeScript, Python, and Go codebases using AST analysis rather than fragile regex patterns.

The generated .codesight/ directory contains focused documentation: CODESIGHT.md provides a 1-2k token architectural overview, routes.md catalogs API endpoints with HTTP methods and tags, schema.md documents database models and relationships, and graph.md shows import dependencies with a “blast radius” analysis that reveals which files would be affected by changes to any given module. Teams add a single instruction to their CLAUDE.md file pointing Claude to read these files first, transforming how AI assistants navigate the codebase.

Why It Matters

Token consumption in AI-assisted development has become a hidden tax on productivity. When Claude spends 40-60k tokens just figuring out where things are before writing a single line of code, developers face slower responses, higher API costs, and context windows filled with redundant exploration. The problem compounds on medium-to-large projects where the same architectural questions get asked in every conversation.

Codesight addresses this by front-loading the discovery phase. Real benchmarks show dramatic improvements: a 92-file Hono project dropped from an estimated 66k exploration tokens to 5k output tokens (12.9× reduction), while a 53-file HTTP service went from 46k to 4k tokens (11.7× reduction). These aren’t theoretical gains - they represent actual production codebases where developers measured token usage before and after implementation.

The broader impact extends beyond cost savings. When AI assistants start with accurate architectural context, they make better decisions about where to make changes. The blast-radius analysis particularly matters for refactoring work, showing exactly which routes, models, and components depend on a file before modifications begin. This shifts AI assistance from exploratory to strategic.

Getting Started

Install and run codesight with a single command:

The tool scans the current directory and generates documentation in .codesight/. For projects already using a CLAUDE.md file to guide AI behavior, add this instruction:

and related files (.codesight/routes.md,.codesight/schema.md, etc.) 
to understand the project structure.

The generated files update automatically on subsequent runs, so teams can integrate codesight into pre-commit hooks or CI pipelines to keep documentation synchronized with code changes. The full source and additional examples are available at https://github.com/Houseofmvps/codesight.

For projects with multiple workspaces or complex monorepo structures, codesight detects and documents each workspace separately, maintaining clear boundaries between different parts of the system.

Context

Codesight joins a growing category of tools designed to optimize AI-code interactions, but takes a different approach than alternatives. Repository indexing services like Sourcegraph or GitHub Copilot maintain live indexes but require persistent infrastructure. Documentation generators like TypeDoc focus on API references rather than architectural overviews optimized for AI consumption.

The tool works best for projects with established patterns - REST APIs, database models, component libraries. Highly dynamic codebases with runtime-generated routes or metaprogramming may see less benefit since static analysis can’t capture behavior that only exists at runtime. The current version supports TypeScript, Python, and Go, leaving other language ecosystems to alternative solutions.

The blast-radius analysis represents the most distinctive feature, transforming import graphs into actionable dependency maps. While developers could manually trace these relationships, having them pre-computed and formatted for AI consumption changes how confidently assistants can suggest refactoring strategies. This positions codesight not just as a token optimizer but as a tool that improves the quality of AI-generated suggestions.