Stop Wasting 50K Tokens Per Conversation & Pre-Index Your Codebase for AI Assistants

The Problem

If you use AI coding assistants, Claude Code, Cursor, GitHub Copilot, Gemini, you've hit this wall: every new conversation starts with the AI re-reading your source files to understand the project. Routes, models, middleware, state management, API clients, database schema... it all gets re-parsed, every single time.

For a mid-sized project, that's easily 50,000+ tokens of context burned before you even ask your first question. That's tokens you could be using for actual work.

The Solution: stack-shared-ai

I built an open-source CLI tool that scans your codebase once and generates compact, structured markdown index files. Instead of your AI reading thousands of files, it reads a handful of focused summaries.

npx stack-shared-ai

One command. No config. It auto-detects your framework, walks the codebase, extracts the important structures, and writes everything to .stack-shared-ai/.

• npm: stack-shared-ai on npm
• GitHub: stack-shared-ai on GitHub

What It Extracts

The tool currently supports six frameworks, each with purpose-built scanners:

Flutter

• deps.md — packages from pubspec.yaml
• models.md — data classes with fields, Freezed/json_serializable models
• components.md — reusable widgets with constructor signatures
• screens.md — screens and GoRouter route definitions
• state.md — Riverpod/Provider/Bloc providers with methods
• api-client.md — Dio and http API endpoints

For Flutter projects, if the Dart SDK is installed, it uses the official analyzer package for accurate AST parsing instead of regex — handling edge cases like nested generics, complex constructors, and annotations correctly.

Express

• routes.md — Express routes with handlers and HTTP methods
• middleware.md — the middleware stack
• services.md — business logic modules
• schema.md — database schema (Prisma, etc.)
• config.md — environment variables and configuration

Works with both TypeScript and plain JavaScript projects.

NestJS

• controllers.md — @Controller classes with @Get/@Post/@Put/@Delete routes, resolved full paths, @UseGuards annotations
• modules.md — @Module definitions with imports, controllers, providers, exports
• providers.md — @Injectable services with public method signatures
• config.md — environment variables and ConfigService references

The scanner understands NestJS decorators, extracts guard chains, and resolves full route paths by combining controller prefixes with method-level paths.

Next.js

• routes.md — App Router pages and route handlers, with route groups stripped and dynamic params normalized ([slug] becomes :slug)
• layouts.md — layout, loading, error, not-found, template files per directory
• server-actions.md — all "use server" exported functions
• components.md — exported components tagged as (client) or (server)
• middleware.md — root middleware entry with route matchers
• config.md — next.config highlights, image domains, experimental flags

Bun

• routes.md — Bun.serve({ routes }) native routing (Bun 1.2+), plus Hono and Elysia chained routes
• config.md — bunfig.toml sections and bun-specific package.json scripts

TypeScript Libraries

• exports.md — package.json exports map (conditional + subpath), main/module/types, bin
• types.md — exported interfaces, types, and enums
• api.md — exported functions and classes with full signatures (via ts-morph AST parsing)

How to Use It With Your AI Tool

Claude Code

Add to your CLAUDE.md:

For an overview of this codebase, read the files in .stack-shared-ai/ before exploring source files directly.

Cursor

Add to .cursorrules:

For an overview of this codebase, read the files in .stack-shared-ai/ before exploring source files directly.

Any other tool

Point it at the .stack-shared-ai/ directory. The output is standard markdown, no lock-in, no special format.

Monorepo Support

If no framework is detected at the project root, the tool automatically scans subdirectories. This handles Turborepo, Nx, pnpm workspaces, and any other monorepo structure, each sub-project gets its own detection and scan.

CLI Options

# Preview without writing
npx stack-shared-ai --dry-run --verbose

# Force specific framework
npx stack-shared-ai --framework nextjs

# Custom output directory
npx stack-shared-ai --output .ai-context

# Scan specific directories only
npx stack-shared-ai --include src lib

# Exclude directories
npx stack-shared-ai --exclude tests __mocks__

You can also create a stack-shared-ai.config.json for team-wide defaults:

{
  "output": ".stack-shared-ai",
  "include": ["src", "lib", "app"],
  "exclude": ["tests", "__mocks__", "build"]
}

Architecture

The tool uses a pluggable scanner architecture. Each framework is a standalone scanner module that implements two methods:

• detect(rootDir) — returns true if the framework is present
• scan(options) — returns an array of files to generate

Adding a new framework means writing a new scanner, the core orchestration, file walking, and output formatting are all shared. There's also a plugin system for loading custom scanners from external files.

Try It

npx stack-shared-ai

• npm: stack-shared-ai on npm
• GitHub: stack-shared-ai on GitHub

MIT licensed. Contributions and framework requests welcome.