agdex

Embed compressed documentation indexes into local agent instruction files.

This package helps AI coding agents (Claude, Cursor, etc.) work with version-matched framework documentation by embedding a compressed docs index directly into your project's markdown file. Based on Vercel's research showing that embedded docs achieve 100% pass rates compared to 79% for skills.

Why?

AI coding agents rely on training data that becomes outdated. When agents don't know current APIs, they generate incorrect code. This tool:

1. Downloads version-matched documentation from GitHub
2. Creates a compressed index (~8KB for Next.js)
3. Stores the docs in local .agdex/ cache
4. Writes the full index to a dedicated DOCINDEX.md file
5. Adds a small Document Indices pointer section to your local agent instruction file (AGENTS.md / CLAUDE.md)
6. Agents can then retrieve specific docs on demand

The key instruction tells agents to prefer retrieval-led reasoning over pre-training-led reasoning.

Progressive disclosure

To keep your AGENTS.md / CLAUDE.md lean, agdex uses a progressive disclosure strategy. The full (potentially large) per-provider indexes live in DOCINDEX.md, while your agent file only gets a compact pointer section that is regenerated every time an index is added or removed:

## Document Indices

IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any of the docs found in DOCINDEX.md .

- NVIDIA TensorRT (`tensorrt`)
- Bun (`bun`)

Agents read this list, then open DOCINDEX.md only when they need the detailed file index for a specific library.

Installation

# Using bun
bun add -D agdex

# Using npm
npm install -D agdex

# Or run directly with npx
npx agdex

Configuration

You can configure agdex defaults using either .agdexrc.json or the agdex field in package.json.

Using .agdexrc.json

Create a .agdexrc.json file in your project root:

{
  "output": "CLAUDE.local.md"
}

Using package.json

Add an agdex field to your package.json:

{
  "name": "my-project",
  "agdex": {
    "output": "CLAUDE.local.md"
  }
}

Note: .agdexrc.json takes priority over package.json if both are present.

Configuration Options

| Option | Type | Default | Description | |----------|--------|-------------|-------------| | output | string | CLAUDE.local.md | Default output file for indexes |

CLI Usage

Interactive Mode

npx agdex

Prompts you with options to:

• Use a detected provider (if one is found in your project)
• Select a built-in provider
• Enter a GitHub repository URL or owner/repo
• Index a local directory
• Index Claude Code skills

When entering a GitHub URL, you can use various formats:

• owner/repo - indexes the detected docs directory
• https://github.com/owner/repo - same as above
• https://github.com/owner/repo/tree/main/docs - indexes a specific path

Built-in Providers

# Next.js (auto-detects version from package.json)
npx agdex --provider nextjs --output AGENTS.md

# With explicit version
npx agdex --provider nextjs --fw-version 15.1.0 --output CLAUDE.md

# React
npx agdex --provider react --fw-version 18.2.0 --output AGENTS.md

# Pixi (auto-detects from pixi.toml or installed version)
npx agdex --provider pixi --output AGENTS.md

# Pixi with explicit version
npx agdex --provider pixi --fw-version 0.63.2 --output AGENTS.md

# Bun (auto-detects from bun.lockb or bunfig.toml)
npx agdex --provider bun --output AGENTS.md

# Add custom description to the index
npx agdex --provider nextjs --description "Project uses App Router only"

Options:

-p, --provider <name>     Documentation provider (nextjs, react, etc.)
--fw-version <version>    Framework version (auto-detected if not provided)
-o, --output <file>       Target file (default: from config or CLAUDE.local.md)
-d, --description <text>  Additional description to include in the index
-g, --global              Use global cache ~/.cache/agdex/ instead of local .agdex/
-l, --local               Use local .agdex/ (default)

Custom GitHub Repository

npx agdex --repo owner/repo --docs-path docs --fw-version v1.0.0 --output AGENTS.md

Local Documentation

Build an index from an existing local docs directory:

npx agdex local ./docs --name "My Framework" --output AGENTS.md

Skills Indexing

Index Claude Code skills from your .claude directories, enabled plugins, and remote skills.sh repositories:

# Index skills (auto-detects from all sources)
npx agdex skills embed

# Index from a skills.sh-compatible GitHub repo
npx agdex skills embed --repo owner/repo

# List discovered skills
npx agdex skills list

# Index from a specific local path
npx agdex skills local ./my-skills --name "My Skills"

# Search skills.sh for community skills
npx agdex skills find "debugging"

# Search with a result limit
npx agdex skills find "frontend" --limit 10

Auto-detection sources:

• Enabled plugins - Reads ~/.claude/settings.json and .claude/settings.json to find enabled plugins, then indexes their skills from the plugin cache
• User skills - ~/.claude/skills (shared across projects)
• Project skills - .claude/skills (project-specific)
• Remote repos - Any GitHub repo with skills in standard locations (skills/, .claude/skills/, .agents/skills/)

Options for skills embed:

--plugins       Include enabled plugins from settings.json (default: true)
--no-plugins    Exclude enabled plugins
--user          Include ~/.claude/skills (default: true)
--no-user       Exclude ~/.claude/skills
--project       Include .claude/skills (default: true)
--no-project    Exclude .claude/skills
--plugin <path> Additional plugin repo paths (with plugins/ structure)
--repo <owner/repo>  Fetch and index from a skills.sh-compatible GitHub repo
-o, --output    Target file (default: AGENTS.md)

Options for skills find:

-l, --limit <n>   Max results (default: 20)
-o, --output       Target file for embedding

Running skills find without a query argument launches interactive mode, where you can search and immediately embed a selected result.

Skills are discovered by looking for SKILL.md files with YAML frontmatter:

---
name: My Skill
description: What this skill does
---

The index includes skill names, descriptions, and all sibling files (recursively).

Removing Indexes

Remove embedded indexes interactively or by flag:

# Interactive mode - select which indexes to remove
npx agdex remove

# Remove a specific provider's docs index
npx agdex remove --provider nextjs

# Remove only docs or skills indexes
npx agdex remove --docs
npx agdex remove --skills

Maintaining Indexes

Successful embeds write local maintenance state to .agdex/agdex.lock. The lockfile records the target agent instruction file, marker, source metadata, cache path, and display command for each last-known-good index. It is generated local state and should stay unversioned with .agdex/.

Inspect index health:

npx agdex status
npx agdex status --check
npx agdex status --json
npx agdex status --output AGENTS.md

Refresh lockfile-backed indexes:

npx agdex refresh
npx agdex refresh --force
npx agdex refresh --repair
npx agdex refresh --provider nextjs

Create lockfile entries for existing embedded docs markers when agdex can safely infer marker and cache metadata:

npx agdex migrate
npx agdex migrate --output AGENTS.md

List Available Providers

npx agdex list

Programmatic API

import { embed, nextjsProvider, createProvider } from 'agdex'

// Use built-in provider
const result = await embed({
  cwd: process.cwd(),
  provider: nextjsProvider,
  output: 'CLAUDE.local.md'
})

// Create custom provider
const myProvider = createProvider({
  name: 'my-framework',
  displayName: 'My Framework',
  repo: 'myorg/myframework',
  docsPath: 'docs',
  packageName: 'my-framework', // for auto-detection
})

await embed({
  cwd: process.cwd(),
  provider: myProvider,
  version: '1.0.0',
  output: 'CLAUDE.local.md'
})

Building Index Manually

import {
  collectDocFiles,
  buildDocTree,
  generateIndex,
  applyDocIndex
} from 'agdex'

// Collect doc files
const files = collectDocFiles('./docs', {
  extensions: ['.md', '.mdx']
})

// Build tree structure
const sections = buildDocTree(files)

// Generate compressed index
const index = generateIndex({
  docsPath: './docs',
  sections,
  providerName: 'My Docs',
  instruction: 'Use retrieval-led reasoning.'
})

// Progressive disclosure: write the full index to DOCINDEX.md and refresh
// the "## Document Indices" summary section in the agent file.
applyDocIndex({
  cwd: process.cwd(),
  agentFile: 'CLAUDE.md',
  providerName: 'my-docs',
  indexContent: index,
  // docIndexFile defaults to DOCINDEX.md
})

Output Format

The generated index uses a compressed pipe-delimited format:

[Next.js Docs Index]|root: ./.nextjs-docs|IMPORTANT: Prefer retrieval-led reasoning...|01-app/01-getting-started:{01-installation.mdx,02-project-structure.mdx}|...

This format:

• Minimizes context window usage (~8KB for Next.js)
• Provides enough structure for agents to find relevant docs
• Includes instructions for retrieval-led reasoning
• Wraps in HTML comments for clean updates

Available Providers

| Provider | Status | Repository | |----------------|--------|------------| | Next.js | ✓ | vercel/next.js | | React | ✓ | reactjs/react.dev | | Pixi | ✓ | prefix-dev/pixi | | rattler-build | ✓ | prefix-dev/rattler-build | | Tauri | ✓ | tauri-apps/tauri-docs | | conda-forge | ✓ | conda-forge/conda-forge.github.io | | CUDA Feedstock | ✓ | conda-forge/cuda-feedstock | | Bun | ✓ | oven-sh/bun | | Svelte | ✓ | sveltejs/svelte | | SvelteKit | ✓ | sveltejs/kit | | shadcn-svelte | ✓ | huntabyte/shadcn-svelte | | Tailwind CSS | ✓ | tailwindlabs/tailwindcss.com | | Ruff | ✓ | astral-sh/ruff | | ty | ✓ | astral-sh/ty | | basedpyright | ✓ | DetachHead/basedpyright | | Convex | ✓ | get-convex/convex-backend | | Polars | ✓ | pola-rs/polars | | delta-rs | ✓ | delta-io/delta-rs | | Obsidian | ✓ | obsidianmd/obsidian-developer-docs | | Obsidian Excalidraw | ✓ | zsviczian/obsidian-excalidraw-plugin | | FFmpeg | ✓ | FFmpeg/FFmpeg | | Manim | ✓ | ManimCommunity/manim |

How It Works

1. Detection: Reads package.json to detect framework version
2. Download: Uses git sparse-checkout to fetch only docs folder
3. Index: Builds a tree of all doc files
4. Compress: Generates pipe-delimited format
5. Write index: Writes/updates the full index in DOCINDEX.md (one marked block per provider)
6. Summarize: Refreshes the ## Document Indices pointer section in AGENTS.md / CLAUDE.md with the current list of indices
7. Gitignore: Adds docs directory to .gitignore

Contributing

Contributions welcome! To add a new provider:

1. Create src/lib/providers/[name].ts
2. Export provider from src/lib/providers/index.ts
3. Add to provider list in CLI

License

MIT