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

• 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/

.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

codesight_get_context

codesight_get_routes

codesight_get_models

codesight_get_components

codesight_get_blast_radius

codesight_get_high_impact_files

codesight_get_framework_info

codesight_get_wiki_index

codesight_get_wiki_article

codesight_lint_wiki

codesight_get_knowledge

codesight_benchmark

codesight_get_overview

Configuring MCP in Claude Code

Add to your Claude Code MCP config (

~/.claude/mcp_settings.json

.mcp.json

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

Configuring MCP in Cursor

Add to

.cursor/mcp.json

{
  "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

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

npx codesight

--wiki

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/

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

• 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