Codesight AI Context

CodeSight — AI Context Generator

Skill by ara.so — Daily 2026 Skills collection.

CodeSight compiles your codebase into a compact, structured context map (routes, models, components, dependencies) that AI coding assistants can read in one shot — eliminating thousands of tokens spent on manual file exploration. Supports 14 languages, 30+ frameworks, 13 ORM parsers, and an MCP server with 13 tools.

Installation

No installation required. Run directly with npx:

npx codesight

Or install globally:

npm install -g codesight
codesight

Requirements: Node.js >= 18, no API keys, no config files needed.

Core Commands

# Generate context map (default — outputs .codesight/CODESIGHT.md)
npx codesight

# Generate persistent wiki knowledge base (.codesight/wiki/)
npx codesight --wiki

# Generate AI tool config files (CLAUDE.md, .cursorrules, codex.md, AGENTS.md)
npx codesight --init

# Open interactive HTML report in browser
npx codesight --open

# Start as MCP server (13 tools) for Claude Code / Cursor
npx codesight --mcp

# Show blast radius for a specific file
npx codesight --blast src/lib/db.ts

# Generate optimized config for a specific AI tool
npx codesight --profile claude-code
npx codesight --profile cursor
npx codesight --profile copilot
npx codesight --profile codex

# Show token savings breakdown
npx codesight --benchmark

# Map markdown knowledge base (ADRs, meeting notes, Obsidian vault)
npx codesight --mode knowledge
npx codesight --mode knowledge ~/vault
npx codesight --mode knowledge ./docs

# Watch mode — regenerate on file changes
npx codesight --watch

# Git hook — regenerate on every commit
npx codesight --hook

What Gets Generated

Default Scan (npx codesight)

Outputs .codesight/CODESIGHT.md — a structured map including:

• Project metadata (stack, language, framework, package manager)
• All routes with HTTP methods and handler locations
• Database models with fields and relations
• UI components with props
• High-impact files ranked by dependency count
• Framework and ORM detection results

Wiki Knowledge Base (--wiki)

Outputs .codesight/wiki/ directory:

.codesight/wiki/
  index.md      — catalog of all articles (~200 tokens)
  overview.md   — architecture, subsystems, high-impact files
  auth.md       — auth routes, middleware, session flow
  payments.md   — payment routes, webhook handling, billing flow
  database.md   — all models, fields, relations
  users.md      — user management routes and models
  ui.md         — UI components with props
  log.md        — append-only operation log

AI Tool Config Files (--init)

Generates project-root files for each AI tool:

• CLAUDE.md — Claude Code project instructions
• .cursorrules — Cursor rules file
• codex.md — OpenAI Codex context
• AGENTS.md — general agent instructions

MCP Server Mode

Start CodeSight as an MCP server to give Claude Code or Cursor direct tool access:

npx codesight --mcp

MCP Tool Reference

Configuring MCP in Claude Code

Add to your Claude Code MCP config (~/.claude/mcp_settings.json or project .mcp.json):

{
  "mcpServers": {
    "codesight": {
      "command": "npx",
      "args": ["codesight", "--mcp"],
      "cwd": "/path/to/your/project"
    }
  }
}

Configuring MCP in Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "codesight": {
      "command": "npx",
      "args": ["codesight", "--mcp"]
    }
  }
}

Language & Framework Support

ORM / Database Support

Drizzle, Prisma, TypeORM, Sequelize, Mongoose, MikroORM, SQLAlchemy, Django ORM, ActiveRecord, Eloquent, Ecto, GORM, and more (13 total).

Real Usage Patterns

Pattern 1: Session Start with Wiki

At the beginning of every AI session, load the wiki index instead of the full context map:

# In Claude Code or Cursor, at session start:
Use codesight_get_wiki_index to get project overview, 
then codesight_get_wiki_article for "auth" to understand authentication.

Pattern 2: Blast Radius Before Refactoring

Before modifying a shared file, check what breaks:

npx codesight --blast src/lib/database.ts

Output shows every file that imports the target, ranked by impact — critical before refactoring database connections, shared utilities, or types.

Pattern 3: CI/CD Integration

Keep context fresh on every push:

# .github/workflows/codesight.yml
name: Update AI Context
on:
  push:
    branches: [main]

jobs:
  update-context:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Generate context map
        run: npx codesight
      - name: Generate wiki
        run: npx codesight --wiki
      - name: Generate knowledge map
        run: npx codesight --mode knowledge ./docs
      - name: Commit updated context
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add .codesight/
          git diff --staged --quiet || git commit -m "chore: update AI context [skip ci]"
          git push

Pattern 4: Git Hook for Local Freshness

npx codesight --hook

This installs a post-commit hook that regenerates .codesight/CODESIGHT.md automatically after every commit.

Pattern 5: Knowledge Mapping for Decision Records

# Map ADRs and architecture docs
npx codesight --mode knowledge ./docs/decisions

# Map full Obsidian vault
npx codesight --mode knowledge ~/vault

# Outputs .codesight/KNOWLEDGE.md with:
# - Key decisions extracted from ADR files
# - Open questions surfaced from notes
# - Meeting notes indexed by date
# - Specs and PRDs cataloged

Consuming the Output in AI Sessions

Loading Context in Claude Code (manual)

Read .codesight/CODESIGHT.md for project context before answering questions.

Loading Wiki at Session Start

Read .codesight/wiki/index.md first. 
Then read the relevant article (e.g. .codesight/wiki/auth.md) 
only when questions about that domain arise.

Loading Combined Context

Read .codesight/CODESIGHT.md for code structure and 
.codesight/KNOWLEDGE.md for architectural decisions.

Token Savings Reference

Real benchmark results from production codebases:

.codesight Directory Structure

.codesight/
  CODESIGHT.md       — main context map (commit this)
  KNOWLEDGE.md       — knowledge/decision map (commit this)
  wiki/
    index.md         — wiki catalog (commit this)
    overview.md
    auth.md
    database.md
    payments.md
    users.md
    ui.md
    log.md

Add .codesight/ to git to persist context across sessions and team members. The wiki survives session restarts — every new conversation starts with full codebase knowledge from the first message.

Troubleshooting

Routes not detected:

• Ensure you're running from the project root (where package.json or equivalent lives)
• TypeScript projects get full AST parsing; other languages use regex — check that route files follow standard framework conventions
• For Python FastAPI, ensure router files use standard @app.get() / @router.post() decorators

Models showing 0 for MongoDB:

• This is correct behavior — codesight parses SQL ORM declarations. MongoDB collections without Mongoose schemas won't appear. Define Mongoose schemas explicitly to get model detection.

Wiki articles missing:

• Run npx codesight --wiki first to generate the wiki directory
• Use codesight_lint_wiki MCP tool or check .codesight/wiki/log.md for generation errors

Large monorepos (10K+ files) are slow:

• Add a .codesightignore file (same syntax as .gitignore) to exclude build artifacts, generated files, and node_modules subdirectories
• Typical scan time: 186ms–890ms for projects under 5K files

MCP server not connecting:

• Verify Node.js >= 18: node --version
• Check cwd in MCP config points to the actual project root
• Run npx codesight --mcp manually first to confirm it starts without errors

--init overwrites existing CLAUDE.md:

• Back up existing files before running --init on a project with custom AI instructions
• Generated files are additive starting points — merge with your existing content manually