Aware

Auto-detect your stack and generate AI context files. Part of the WhenLabs toolkit.

Aware scans your project, detects your tech stack, and generates context files for Claude Code, Cursor, GitHub Copilot, and AGENTS.md — all from a single source of truth.

Part of the WhenLabs toolkit — install all 6 tools with one command:

npx @whenlabs/when install

The Problem

Every AI coding tool reads a different context file:

• CLAUDE.md for Claude Code
• .cursorrules for Cursor
• .github/copilot-instructions.md for GitHub Copilot
• AGENTS.md for multi-agent workflows

You end up writing the same conventions three times, they drift apart, and none of them auto-detect your stack.

The Fix

$ aware init

Detected Stack
==================================================
  Framework          Next.js 15.1 (App Router) (95%)
  Language           TypeScript 5.5 (99%)
  Styling            Tailwind CSS 4.0 (95%)
  ORM                Drizzle ORM (95%)
  Database           PostgreSQL (90%)
  Testing            Vitest (95%), Playwright (95%)
  Linting            ESLint 9 (95%), Prettier (90%)
  Package Manager    pnpm (99%)
  Deployment         Vercel (95%)
  Auth               NextAuth.js v5 (95%)
  API Style          tRPC (95%)
==================================================

✓ .aware.json created
✓ CLAUDE.md (13 sections)
✓ .cursorrules (4 sections)
✓ .github/copilot-instructions.md (13 sections)
✓ AGENTS.md (6 sections)

One command. Full stack detection. Four context files. All in sync.

Install

Recommended: Install the full WhenLabs toolkit with npx @whenlabs/when install to get aware plus 5 other tools in one step.

npm install -g @whenlabs/aware

Or run directly:

npx @whenlabs/aware init

Requirements: Node.js >= 20.12

Commands

aware init

Scans your project, detects the stack, generates .aware.json and all context files.

aware init                          # Detect and generate
aware init -t claude,cursor         # Only specific targets
aware init --force                  # Overwrite existing files
aware init --no-detect              # Skip detection, create empty config
aware init --workspace              # Monorepo mode: scaffold a per-package .aware.json that extends the root

Options:

| Flag | Description | Default | |------|-------------|---------| | -t, --targets <targets> | Comma-separated targets: claude, cursor, copilot, agents, all | claude,cursor,copilot,agents | | -f, --force | Overwrite existing files without prompting | false | | --no-detect | Skip auto-detection, create empty config | detection on | | --workspace | Monorepo mode: discover workspace packages and scaffold a per-package .aware.json that extends the root | false |

aware sync

Regenerates context files from .aware.json after you've edited it.

aware sync                          # Regenerate all targets
aware sync --dry-run                # Preview changes without writing

aware diff

Shows what changed in your detected stack and generated files since the last sync.

aware diff                          # Human-readable diff, prompts to sync if drift found
aware diff --check                  # CI mode: exit 0 (clean) / 1 (stack drift) / 2 (tamper)
aware diff --json                   # Emit a machine-readable DriftReport as JSON
aware diff --target claude          # Narrow content drift to one target
aware diff --check --quiet          # Silent CI gate

Options:

| Flag | Description | Default | |------|-------------|---------| | --check | CI mode: exit 0/1/2 for clean/drift/tamper; no interactive prompt | false | | --json | Emit a machine-readable DriftReport as JSON | false | | --target <target> | Narrow content drift to one target (claude, cursor, copilot, agents) | all targets | | --quiet | Suppress human output (useful with --check) | false |

Exit codes for --check:

• 0 — No drift
• 1 — Stack drift detected (re-run aware sync to update generated files)
• 2 — Tamper detected (a generated file was edited by hand since the last sync)

How It Works

1. Detection

Aware reads your project files to detect your stack. All detectors run in parallel for speed:

| What | How | |------|-----| | Framework | package.json deps, Cargo.toml, requirements.txt, go.mod | | Language | tsconfig.json, .python-version, rust-toolchain.toml | | Styling | Tailwind config, styled-components/Emotion in deps | | ORM | Prisma schema, Drizzle config, SQLAlchemy in deps | | Database | DATABASE_URL in .env, docker-compose.yml | | Testing | Vitest/Jest/Playwright config or deps | | Linting | ESLint/Prettier/Biome config or deps | | Package Manager | Lock files (pnpm-lock.yaml, yarn.lock, etc.) | | Monorepo | turbo.json, nx.json, pnpm-workspace.yaml | | Deployment | vercel.json, netlify.toml, fly.toml, Dockerfile | | Auth | NextAuth, Clerk, Lucia, Passport, Supabase Auth, Better Auth in deps | | API Style | tRPC, GraphQL, OpenAPI files | | State Mgmt | Zustand, Redux Toolkit, Jotai, XState in deps | | CI/CD | .github/workflows/, .gitlab-ci.yml | | Bundler | Vite, Webpack, esbuild, tsup, SWC, Rollup configs |

Each detection returns a confidence score (0-1) and the source it was detected from.

2. Single Source of Truth

Detection results go into .aware.json. Edit this file to customize conventions, add rules, and describe your project:

{
  "version": 1,
  "project": {
    "name": "my-app",
    "description": "A B2B SaaS platform",
    "architecture": "Next.js App Router with tRPC and Drizzle"
  },
  "stack": {
    "framework": "[email protected]:app-router",
    "language": "[email protected]",
    "orm": "drizzle"
    // ... auto-detected
  },
  "conventions": {
    "naming": {
      "files": "kebab-case",
      "components": "PascalCase"
    }
  },
  "rules": [
    "Use server components by default",
    "Never use any — define proper types"
  ],
  "structure": {
    "src/app/": "Next.js App Router pages and layouts",
    "src/components/": "Reusable UI components"
  },
  "targets": {
    "claude": true,
    "cursor": true,
    "copilot": true,
    "agents": true
  }
}

Conventions are auto-generated based on the detected language and framework (e.g., TypeScript projects get camelCase functions, PascalCase components; Python projects get snake_case).

3. Fragment System

Each detected stack component maps to a fragment — a chunk of context-aware best practices and conventions. Fragments cover frameworks, ORMs, testing tools, linting, deployment, auth, API patterns, state management, and CI/CD.

Fragments are resolved based on your detected stack and composed into a unified context. Only relevant fragments are included.

4. Output Adapters

Each AI tool gets the format it works best with:

| Target | File | Style | |--------|------|-------| | Claude Code | CLAUDE.md | Full markdown — verbose, all sections, fragment content included inline | | Cursor | .cursorrules | Concise flat rules — imperative style, condensed fragments | | GitHub Copilot | .github/copilot-instructions.md | Medium markdown, trimmed | | AGENTS.md | AGENTS.md | Structured sections (Context, Conventions, Constraints) |

Supported Stacks

Frameworks: Next.js (App/Pages Router), Remix, Astro, SvelteKit, Vite+React, Vite+Vue, Vue, Angular, NestJS, Express, Fastify, Hono, FastAPI, Django, Flask, Rust CLI, Go

Styling: Tailwind CSS (v3/v4), styled-components, CSS Modules

ORMs: Drizzle, Prisma, TypeORM, Kysely, Mongoose, SQLAlchemy

Databases: PostgreSQL, MySQL, MongoDB, SQLite (from .env, Docker Compose, or ORM config)

Testing: Vitest, Jest, Playwright, Cypress, pytest

Linting: ESLint (v8/v9), Prettier, Biome

Auth: NextAuth/Auth.js, Clerk, Lucia, Supabase Auth, Better Auth

API: tRPC, GraphQL, REST

State Management: Zustand, Redux Toolkit, Jotai, XState

CI/CD: GitHub Actions, GitLab CI

Deployment: Vercel, Netlify, Fly.io, Railway, Docker

Bundlers: Vite, Webpack, esbuild, tsup, SWC, Rollup, Turbopack, Parcel

Package Managers: pnpm, npm, Yarn, Bun, Cargo, Poetry, uv

Monorepos: Turborepo, Nx, pnpm workspaces

CI Integration

Add a drift gate to your CI so generated context files never fall out of sync with the actual stack:

# .github/workflows/aware.yml
name: AI Context Drift
on: [pull_request]
jobs:
  aware:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npx @whenlabs/aware diff --check --quiet

Tech Stack

• Language: TypeScript (ES2022, strict mode)
• CLI Framework: Commander.js
• Config Parsing: js-yaml, toml, dotenv
• File Globbing: fast-glob
• Output: chalk, ora
• Build: tsup (ESM, Node 20+ target)
• Testing: Vitest with fixture-based project testing

Development

# Install dependencies
pnpm install

# Run in development mode
pnpm dev [command]

# Build
pnpm build

# Run tests
pnpm test

# Type check
pnpm lint

License

MIT