codesight-ai-context

What this skill does

# CodeSight — AI Context Generator

> Skill by [ara.so](https://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`:

```bash
npx codesight
```

Or install globally:

```bash
npm install -g codesight
codesight
```

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

## Core Commands

```bash
# 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:

```bash
npx codesight --mcp
```

### MCP Tool Reference

| Tool | Description |
|---|---|
| `codesight_get_context` | Full codebase context map |
| `codesight_get_routes` | All API routes with methods and handlers |
| `codesight_get_models` | All database models and schema |
| `codesight_get_components` | UI components with props |
| `codesight_get_blast_radius` | Impact analysis for a specific file |
| `codesight_get_high_impact_files` | Files ranked by dependency count |
| `codesight_get_framework_info` | Detected frameworks and ORMs |
| `codesight_get_wiki_index` | Wiki catalog (~200 tokens) for session start |
| `codesight_get_wiki_article` | Read one wiki article by name |
| `codesight_lint_wiki` | Wiki health check (orphans, stale, missing links) |
| `codesight_get_knowledge` | Knowledge map from markdown notes |
| `codesight_benchmark` | Token savings analysis |
| `codesight_get_overview` | Project overview summary |

### Configuring MCP in Claude Code

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

```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:

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

## Language & Framework Support

| Language | AST Precision | Frameworks Detected |
|---|---|---|
| TypeScript | ✅ Full AST | Next.js, NestJS, Hono, Remix, SvelteKit, Nuxt, Express, Fastify |
| JavaScript | Regex | Express, Fastify, Koa, Hapi |
| Python | Regex | Django, FastAPI, Flask, SQLAlchemy |
| Go | Regex | Gin, Echo, Fiber, Chi |
| Ruby | Regex | Rails, Sinatra |
| PHP | Regex | Laravel, Symfony |
| Elixir | Regex | Phoenix |
| Java | Regex | Spring Boot |
| Kotlin | Regex | Ktor, Spring Boot |
| Rust | Regex | Axum, Actix |
| Dart | Regex | Flutter |
| Swift | Regex | Vapor |
| C# | Regex | ASP.NET Core |

## 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:

```bash
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:

```yaml
# .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 "[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

```bash
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

```bash
# 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

| Approach | Tokens per session | Savings vs baseline |
|---|---|---|
| Manual file exploration | 26K–47K | baseline |
| `npx codesight` (cont