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 codesightcodesight

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 browsernpx codesight --open
# Start as MCP server (13 tools) for Claude Code / Cursornpx codesight --mcp
# Show blast radius for a specific filenpx codesight --blast src/lib/db.ts
# Generate optimized config for a specific AI toolnpx codesight --profile claude-codenpx codesight --profile cursornpx codesight --profile copilotnpx codesight --profile codex
# Show token savings breakdownnpx codesight --benchmark
# Map markdown knowledge base (ADRs, meeting notes, Obsidian vault)npx codesight --mode knowledgenpx codesight --mode knowledge ~/vaultnpx codesight --mode knowledge ./docs
# Watch mode — regenerate on file changesnpx codesight --watch
# Git hook — regenerate on every commitnpx 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.ymlname: Update AI Contexton:  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 "[email protected]"          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 docsnpx codesight --mode knowledge ./docs/decisions
# Map full Obsidian vaultnpx 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