aidoc-kit

AI-native documentation scanner for JS/TS projects

v1.2.0 — Battle-tested on Next.js 16 projects with 135+ files.

The problem

When AI agents (GitHub Copilot, Cursor, Claude) work on large Next.js projects with 200–400 files, they lose context between sessions. They re-discover architecture, miss existing conventions, and break established patterns.

How it works

1. Scan — aidoc-kit reads your entire project via TypeScript's native AST compiler
2. Generate — it creates @ai-* doc blocks on every file and builds a reverse dependency graph
3. Agents understand — Copilot and any AI agent reads .codemod/ and AGENTS.md to instantly understand your project without reading 400 files

Installation

# Install once as a dev dependency (recommended — avoids interactive prompts every run):
npm install -D aidoc-kit

Or run directly with npx --yes to skip the download confirmation:

npx --yes aidoc-kit init

Quick start

# Install once (skip the npm download prompt on every run):
npm install -D aidoc-kit

# 1. Detect your stack and generate aidoc.config.ts automatically:
npx aidoc-kit init

# 2. Preview generated @ai-* blocks without writing anything:
npx aidoc-kit scan --dry

# 3. Write blocks to all files (asks confirmation):
npx aidoc-kit scan --write

# 4. Summarise large files for agents:
npx aidoc-kit chunk

# 5. Enrich @ai-context with an LLM (uses the provider detected at init):
npx aidoc-kit enrich --dry

That's all a new user needs. init reads package.json, detects frameworks, auth libraries, databases, AI SDKs and generates a ready-to-use aidoc.config.ts.

AI Setup

npx aidoc-kit init asks how you use AI and configures the project accordingly.

Profile 1 — API Key (Anthropic, OpenAI, Gemini…)

aidoc-kit detects your provider from the environment variables found in .env / .env.local and queries the provider's /models endpoint to let you pick a model interactively. The generated aidoc.config.ts stores the key reference, never the key value.

// aidoc.config.ts — generated by `npx aidoc-kit init`
export default {
  enrich: {
    provider: 'anthropic',
    keyEnv: 'ANTHROPIC_API_KEY', // reference, not value
    // model: not set — resolved at runtime via /models API
  }
}

Run npx aidoc-kit models at any time to list available models for your configured provider.

Profile 2 — GitHub Copilot / VS Code Agent

No API key needed. aidoc-kit generates ready-to-use prompt files in .aidoc/prompts/ that you paste into Copilot Chat or your VS Code agent. Use npx aidoc-kit inject --input output.md to write the results back into source files.

Profile 3 — No AI (manual mode)

aidoc-kit generates empty @ai-context skeletons with inline comments guiding you to fill them manually. No LLM required.

Do I need to configure AI agents first?

No. aidoc-kit works out of the box with any AI coding tool.

How it works with your existing tools

| Tool | How it reads @ai-* blocks | |------|--------------------------| | GitHub Copilot | Reads open files automatically — no setup needed | | Cursor | Reads project context automatically — no setup needed | | Copilot Chat | Reads files you reference in the chat | | Claude / ChatGPT | Reads files you paste or attach | | Any AI agent | Reads AGENTS.md as entry point |

The @ai-agent tag is a label, not a configuration

When aidoc-kit generates:

/**
 * @ai-agent firebase-admin-expert
 */

It doesn't create or configure anything. It tells the AI reading the file: "treat this file as Firebase Admin domain — apply that expertise when suggesting changes."

Think of it like a job title on a business card. It informs, it doesn't configure.

The one thing you should do

Tell your AI agent to read AGENTS.md at the start of each session.

GitHub Copilot Chat:

Read AGENTS.md before we start. It contains the project architecture.

Cursor — add to .cursorrules:

Always read AGENTS.md and .codemod/ai-knowledge-base.json
before suggesting changes to any file.

Claude Projects: Add AGENTS.md content to the project instructions.

That's it. No agents to create, no pipelines to configure.

Want to go further?

If you use custom AI agents or MCP servers, aidoc-kit exposes its knowledge base as a structured JSON file: .codemod/ai-knowledge-base.json

Any agent that can read a file can consume this directly.

What gets generated

On each file (auto-generated block)

/**
 * @ai-agent auth-expert
 * @ai-runtime CLIENT UNIQUEMENT
 *
 * @ai-context
 * [GÉNÉRÉ] Ce fichier exporte : AuthProvider, useAuthContext
 * Importé dans : src/app/layout.tsx, src/hooks/use-auth.ts
 *
 * @ai-when-modifying
 * 1. Vérifier les fichiers en cascade ci-dessous
 * 2. Lancer @ai-validate après toute modification
 *
 * @ai-cascade
 * - src/hooks/use-auth.ts
 * - src/lib/types.ts
 *
 * @ai-validate
 * npm run typecheck
 */

At project root

• AGENTS.md — entry point for any AI agent working on the project
• .codemod/ai-knowledge-base.json — full indexed knowledge base (agents, cascade graph, runtime map)

Supported @ai-* tags

| Tag | Description | Required | |-----|-------------|----------| | @ai-context | What this file does and exposes | Always | | @ai-cascade | Files that must be checked after modifying this one | Always | | @ai-validate | Command to run after modifications | Always | | @ai-when-modifying | Rules to follow when editing | Always | | @ai-agent | Specialist agent type | Recommended | | @ai-agent-hint | Agent switch suggestion (auto-generated) | Auto | | @ai-runtime | Execution context (omitted when deductible from 'use client') | Optional | | @ai-enriched | Enrichment date (set by enrich command) | Metadata | | @ai-agents-related | Other agents to consult when modifying | Optional | | @ai-when-reading | How to consume this file correctly | Optional | | @ai-always | Invariants that must always be respected | Optional | | @ai-never | Absolute prohibitions | Optional | | @ai-pattern | Correct usage code example | Optional |

Runtime auto-detection

aidoc-kit detects the execution environment automatically:

| Signal | Runtime | |--------|---------| | 'use client' directive | CLIENT UNIQUEMENT | | 'use server' directive | SERVER UNIQUEMENT | | firebase-admin import | SERVER UNIQUEMENT | | useState / useEffect usage | CLIENT UNIQUEMENT | | None of the above | UNIVERSEL |

Agent inference

The responsible agent is inferred from imports and file path, in priority order:

1. Custom rules from aidoc.config.js — your project-specific mappings
2. Built-in rules — firebase-admin → firebase-admin-expert, stripe → billing-expert, @tanstack/react-query → data-fetching-expert, zustand → state-expert, react-hook-form → forms-expert, …
3. Path heuristics — /hooks/ → hooks-expert, /api/ → api-expert, /components/ → ui-expert, …

Configuration

Run npx aidoc-kit init to generate a pre-filled aidoc.config.ts automatically. Or create it manually:

// aidoc.config.ts
export default {
  agents: {
    'firebase-admin': 'firebase-admin-expert',
    'stripe': 'billing-expert',
    '@/lib/permissions': 'permissions-expert',
  },
  ignore: ['src/generated/', '*.test.ts', '*.spec.ts'],
  validate: 'npm run typecheck',
}

Also supported: aidoc.config.js (CommonJS module.exports) and aidoc.config.json.

AI-powered context enrichment

Once scan --write has generated the base @ai-* blocks, run enrich to replace the generic [GÉNÉRÉ] descriptions with real LLM-written context:

# Set your API key, then run — model is resolved automatically:
export ANTHROPIC_API_KEY=sk-ant-...
npx aidoc-kit enrich --provider anthropic

export OPENAI_API_KEY=sk-...
npx aidoc-kit enrich --provider openai

export GEMINI_API_KEY=...
npx aidoc-kit enrich --provider gemini

export GROQ_API_KEY=gsk_...
npx aidoc-kit enrich --provider groq

# Fully local — no key needed:
npx aidoc-kit enrich --provider ollama

# List available models for your configured provider:
npx aidoc-kit models

Security note: Never pass API keys via --key — they appear in shell history and process lists. aidoc-kit reads keys from environment variables automatically: ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, GROQ_API_KEY, MISTRAL_API_KEY.

Use --dry to preview which files would be enriched without making any changes.

You can also set the default provider in aidoc.config.ts to avoid repeating flags:

export default {
  enrich: {
    provider: 'anthropic',
    key: process.env.ANTHROPIC_API_KEY,   // never hardcode keys
  },
}

Choosing your provider

| Provider | Cost | Speed | Best for | |----------|------|-------|----------| | Ollama | Free | Medium | Local dev, privacy, confidential code | | Groq | Very low | Ultra fast | CI/CD, large projects | | Gemini | Very low | Fast | Daily use | | Anthropic | Low | Fast | Best code quality | | Mistral | Low | Fast | European data residency | | OpenAI | Low | Fast | General use |

Run npx aidoc-kit models to see which models are currently available for your configured provider.

Privacy note: Ollama runs entirely on your machine — no code ever leaves your network. This makes it the right choice for client projects or proprietary codebases.

Setting up your API key

aidoc-kit reads API keys from environment variables. How you load them into your environment is up to you:

Option 1 — Export in your shell

export ANTHROPIC_API_KEY=sk-ant-...
npx aidoc-kit enrich

Option 2 — Load your .env file first

source .env && npx aidoc-kit enrich
# or with .env.local:
source .env.local && npx aidoc-kit enrich

Option 3 — dotenv-cli (recommended for scripts)

npx dotenv -e .env.local -- aidoc-kit enrich

Option 4 — aidoc.config.ts (recommended for teams)

export default {
  enrich: {
    provider: 'anthropic',
    key: process.env.ANTHROPIC_API_KEY,
  }
}

Then run normally — the key is resolved at runtime from your env.

Environment variables per provider

| Provider | Environment variable | |-----------|---------------------| | Anthropic | ANTHROPIC_API_KEY | | OpenAI | OPENAI_API_KEY | | Gemini | GOOGLE_AI_API_KEY or GEMINI_API_KEY | | Groq | GROQ_API_KEY | | Mistral | MISTRAL_API_KEY | | Ollama | No key needed |

Why doesn't aidoc-kit read .env files automatically? Managing secrets is your responsibility, not aidoc-kit's. This is intentional — it keeps the library zero-dependency and avoids any risk of accidentally exposing secrets. This is the same approach used by Prisma, Firebase CLI, and Stripe CLI.

Large file chunking

AI agents often truncate large files — reading only the first 50-100 lines of a 500-line file. aidoc-kit chunk solves this by pre-summarising every file over 150 lines into a structured Markdown file inside .codemod/chunks/.

npx aidoc-kit chunk
# 📦 src/contexts/auth-context.tsx (320 lignes)
# 📦 src/lib/firebase.ts (210 lignes)
#
# ✓ 2 fichier(s) chunkés → .codemod/chunks/

Each generated chunk looks like:

# Chunk — src/contexts/auth-context.tsx
> 320 lignes — généré par aidoc-kit chunk

## Exports publics
- `AuthProvider` (function) — ligne 45
- `AuthContextType` (interface) — ligne 12
- `useAuthContext` (const) — ligne 89

## Imports critiques
- firebase/auth (getAuth, onAuthStateChanged, signInWithEmailAndPassword)
- react (createContext, useContext, useState, useEffect)
- @/lib/types (User, UserRole)

## Structure du fichier
- L. 1-50 : imports
- L. 51-100 : types et interfaces
- L. 101-150 : hooks React
- L. 151-200 : fonctions asynchrones
- L. 201-320 : rendu JSX

## Fonctions et méthodes
| Nom | Lignes | Paramètres | Retour |
|-----|--------|------------|--------|
| AuthProvider | 45-180 | children: ReactNode | JSX.Element |
| useAuthContext | 181-200 | — | AuthContextType |

## Importé par
- `src/app/layout.tsx`
- `src/hooks/use-auth.ts`

Tell your AI agent: "Read .codemod/chunks/ before modifying any large file."

CLI reference

aidoc-kit — AI-native documentation toolkit

Commands:
  scan    Scan a project and build the knowledge base
          --path <dir>   Project root (default: .)
          --write        Write missing @ai-* blocks (interactive confirmation)
          --dry          Preview generated blocks without writing anything

  chunk   Summarise large files (≥150 lines) into .codemod/chunks/*.md
          --path <dir>   Project root (default: .)

  models  List available models for the configured provider

  enrich  Enrich @ai-context blocks with real LLM-generated descriptions
          --provider     openai | anthropic | gemini | groq | mistral | ollama
          --model        Override model (run `npx aidoc-kit models` to list available)
          --host         Ollama host (default: http://localhost:11434)
          --path <dir>   Project root (default: .)
          --dry          List files without modifying

  agents  Generate .github/copilot/<agent>.md instruction files from @ai-agent tags
          --path <dir>   Project root (default: .)

  run     Apply transformation rules
          --path <dir>   Project root (default: .)
          --dry          Preview changes without writing

Reverse dependency graph

One of aidoc-kit's core features is the reverse import map: for every file, it resolves which other files import it (via the TypeScript AST, not text search). This powers the accurate @ai-cascade section — when you touch types.ts, the agent knows exactly which 4 files depend on it.

Why zero dependencies?

aidoc-kit uses only Node.js built-ins + the TypeScript compiler already installed in every TypeScript project. No extra packages, no version conflicts, no supply chain risk.

All generated @ai-* blocks are 100% ASCII. No Unicode characters are ever injected into source files — ensuring compatibility with SWC, Turbopack, Babel, and esbuild across all Next.js versions.

The ASCII contract

Rule: @ai-* blocks injected into .ts / .tsx source files must contain only printable ASCII characters (U+0020–U+007E).

Why it matters: SWC, Turbopack, Babel, and esbuild parse source files with varying Unicode tolerance. A character as common as → (U+2192) or > in a comment can crash SWC inside a .tsx file with "Unexpected token". Since aidoc-kit injects blocks into files that will be compiled, ASCII-only is the only universally safe choice.

Where characters outside ASCII are allowed: CLI output (console.log), chunk .md files, AGENTS.md, .codemod/ai-knowledge-base.json — these are never parsed by a JS/TS compiler.

Roadmap

• [ ] VS Code extension with @ai-* tag highlighting and hover docs
• [ ] MCP server to expose scan/transform as AI agent tools
• [ ] --watch mode (rebuild knowledge base on save)
• [ ] Public rules registry for popular lib migrations (Next.js, Firebase, Stripe)
• [ ] CI/CD integration to validate @ai-* coverage on each PR
• [ ] HTML visual report of the dependency graph

Contributing

See CONTRIBUTING.md.

Author

Made by Clément Tournier

If aidoc-kit is useful to you, a ⭐ on GitHub helps a lot → github.com/Clemsrec/aidoc-kit