Codesight: AI-Optimized Codebase Documentation Tool

What It Is

Codesight is a command-line tool that generates structured documentation maps of codebases specifically designed for AI assistants like Claude. Instead of letting Claude spend tens of thousands of tokens exploring a project’s file structure through repeated read operations, codesight pre-analyzes the codebase and creates compact reference files that Claude can read once at the start of each session.

The tool scans TypeScript, Python, and Go projects using AST parsing to extract meaningful patterns: API routes with their HTTP methods and authentication requirements, database schemas with relationships, React components with their props, environment variables with usage locations, and an import dependency graph. All this information gets written to a .codesight/ directory as markdown files totaling just 1-2k tokens for the main overview.

Developers add a single instruction to their project’s CLAUDE.md file directing the AI to consult these pre-generated maps before exploring the file tree. This shifts the orientation phase from runtime exploration to upfront context loading.

Why It Matters

The token economics of AI-assisted coding have a hidden cost that most developers don’t track carefully. When Claude starts a conversation on a medium-sized project without context, it typically makes 15-30 file exploration calls to understand the architecture before writing a single line of code. Each exploration burns tokens that count against rate limits and usage costs.

Real measurements from production codebases show the impact. A 92-file Hono application that previously required an estimated 66,040 exploration tokens now uses just 5,129 output tokens with codesight - a 12.9× reduction. A 53-file project dropped from 46,020 to 3,945 tokens, an 11.7× improvement. These aren’t theoretical projections but actual token counts from working sessions.

Teams working on larger codebases benefit most dramatically. Projects with multiple workspaces, microservices, or complex dependency graphs see Claude spend the majority of early conversation tokens just building a mental model. Codesight front-loads that work into a one-time scan that runs in seconds via npx codesight scan.

The blast-radius analysis provides particular value for refactoring work. When Claude needs to understand “what breaks if I change this file,” it can consult the import graph instead of recursively reading every potential dependent file.

Getting Started

Install and run codesight with a single command:

This generates the .codesight/ directory with all documentation maps. For projects using Claude Desktop or similar AI assistants, add this instruction to the project’s CLAUDE.md file:

The tool requires no configuration for standard project structures. It automatically detects frameworks like Hono, Express, FastAPI, and Gin, identifies database ORMs like Drizzle and Prisma, and recognizes React component patterns.

For ongoing projects, run npx codesight scan after significant architectural changes or before starting new feature work. The scan completes in seconds even on large codebases since it only parses structure, not content.

The full source and documentation live at https://github.com/Houseofmvps/codesight

Context

Codesight addresses a specific inefficiency in AI-assisted development rather than replacing existing tools. It complements project documentation, not replaces it - human-readable docs still matter for onboarding and architectural decisions.

Alternative approaches exist. Some teams write custom context files manually, but these quickly become stale. Others rely on AI tools with larger context windows, but even 200k token windows get expensive when filled with redundant file reads. Repository-wide embeddings offer semantic search but don’t provide the structured architectural view that helps AI assistants understand system boundaries.

The tool works best on projects with clear architectural patterns. Highly dynamic codebases that generate routes or schemas at runtime may not capture complete information through static analysis. Projects mixing multiple languages or using unconventional file structures might need manual supplementation of the generated maps.

The zero-dependency design means codesight runs via npx without adding to project dependencies, but this also limits extensibility. Teams needing custom analysis patterns would need to fork rather than configure.