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

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

# 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

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:

npx codescope
git add .codescope/

Or add to package.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