npm package: @houseofmvps/codescope
Description: Universal AI context generator. Scans any codebase and generates compact context files for Claude Code, Cursor, Copilot, Codex, and more.
Author: Houseofmvps
Latest version: 1.0.0

# codescope

Universal AI context generator. Scans any codebase and generates compact context files that save your AI assistant thousands of tokens per conversation.

Works with **Claude Code, Cursor, GitHub Copilot, Codex, Windsurf, Cline** and any AI coding tool.

## Why

Every time you start a conversation with an AI coding assistant, it spends tokens exploring your codebase to understand the structure. codescope pre-generates that context into compact markdown files so your AI assistant starts with full project understanding immediately.

## Quick Start

```bash
npx codescope
```

That's it. Run it in any project root. It generates a `.codescope/` directory with context files.

## What It Detects

| Category | Supported |
|---|---|
| **Routes** | Hono, Express, Fastify, Next.js (App + Pages), Koa, FastAPI, Flask, Django, Go (net/http, Gin, Fiber) |
| **Schema** | Drizzle, Prisma, TypeORM, SQLAlchemy |
| **Components** | React, Vue, Svelte (filters out shadcn/radix primitives) |
| **Libraries** | TypeScript/JavaScript, Python, Go exports with signatures |
| **Config** | Environment variables, config files, key dependencies |
| **Middleware** | Auth, rate limiting, CORS, validation, logging, error handling |
| **Monorepos** | pnpm, npm, yarn workspaces |
| **Languages** | TypeScript, JavaScript, Python, Go |

## Output

```
.codescope/
  CODESCOPE.md      # Combined context (point your AI here)
  routes.md         # All API routes with methods and tags
  schema.md         # Database models with fields, types, relations
  components.md     # UI components with props
  libs.md           # Library exports with signatures
  config.md         # Env vars, config files, key dependencies
  middleware.md     # Auth, rate limiting, CORS, etc.
```

### Example Output

```markdown
# myapp — AI Context Map

> **Stack:** hono | drizzle | react | typescript
> **Monorepo:** @myapp/api, @myapp/web, @myapp/shared

> 65 routes | 18 models | 16 components | 36 lib files | 22 env vars | 5 middleware
```

## Options

```bash
npx codescope                      # Scan current directory
npx codescope ./my-project         # Scan specific directory
npx codescope -o .ai-context       # Custom output directory
npx codescope --json               # Output JSON instead of markdown
npx codescope -d 5                 # Limit directory depth
```

## How to Use with AI Tools

### Claude Code
Add to your `CLAUDE.md`:
```
Read .codescope/CODESCOPE.md for full project context before making changes.
```

### Cursor
Add to `.cursorrules`:
```
Reference .codescope/CODESCOPE.md for project structure and conventions.
```

### GitHub Copilot
Add to `.github/copilot-instructions.md`:
```
See .codescope/CODESCOPE.md for project context including routes, schema, and components.
```

## Keep It Fresh

Add to your pre-commit hook or CI:

```bash
npx codescope
git add .codescope/
```

Or add to `package.json`:
```json
{
  "scripts": {
    "codescope": "codescope"
  }
}
```

## Zero Dependencies

codescope has zero runtime dependencies. It uses only Node.js built-ins for maximum compatibility and speed.

## License

MIT