create-ai-context

A CLI tool to bootstrap an AI Context Layer (.ai/) for codebases. It creates human-maintained rules and generates machine indexes so AI coding tools (Codex / Cursor / Claude Code / Aider) can understand your project faster and follow your team conventions.

Quick Start (Recommended)

Run at your project root (must contain package.json):

npx @zhanglichen/create-ai-context --yes

This will:

• Create .ai/ (lowercase human-maintained spec files)
• Add scripts/ai/generate-ai-context.mjs
• Add ai:context script to package.json
• (Optional) append .gitignore rules for generated artifacts
• (Optional) run npm run ai:context

Installation (Optional)

Global install

npm i -g @zhanglichen/create-ai-context

Then run:

create-ai-context --yes

Note: This package is published as @zhanglichen/create-ai-context.

Usage

Initialize (default)

npx @zhanglichen/create-ai-context init --yes

Options:

• -y, --yes - non-interactive, accept defaults
• --skip-run - do not run ai:context after init
• --skip-gitignore - do not append .gitignore rules

Examples:

npx @zhanglichen/create-ai-context init --yes --skip-run

Scan / Generate indexes

Run whenever the codebase structure changes (new components/hooks/services, moved folders, etc.):

npx @zhanglichen/create-ai-context scan

Or:

npm run ai:context

Doctor (diagnostics)

Useful when setup or generation fails:

npx @zhanglichen/create-ai-context doctor

Update (placeholder)

npx @zhanglichen/create-ai-context update

Output

Human-maintained (lowercase, commit to git)

These files define your team rules and should be reviewed/maintained:

• .ai/agent.md
• .ai/stack.md
• .ai/architecture.md
• .ai/conventions.md
• .ai/codebase.md
• .ai/task_workflow.md
• .ai/readme.md

Generated (uppercase, do not edit manually)

Generated by npm run ai:context:

• .ai/AI_CONTEXT.json
• .ai/COMPONENT_MAP.md
• .ai/COMPONENT_TREE.json
• .ai/HOOK_MAP.json
• .ai/API_MAP.json
• .ai/ROUTE_MAP.json
• .ai/DEP_GRAPH.json
• .ai/COMPONENT_RELATION_GRAPH.json
• .ai/HOOK_DEP_GRAPH.json
• .ai/API_SCHEMA_MAP.json

Generated files may be ignored in git (recommended). See .gitignore section below.

Recommended .gitignore

Commit the lowercase files, ignore generated uppercase artifacts:

# AI Context Layer (generated)
.ai/AI_CONTEXT.json
.ai/COMPONENT_*.*
.ai/HOOK_*.json
.ai/API_*.json
.ai/ROUTE_*.json
.ai/DEP_*.json
.ai/*_GRAPH.json
.ai/*_MAP.json
.ai/*_TREE.json

Prompt Template (Works Great in Codex/Cursor)

Copy this into your AI tool:

Follow `.ai/agent.md`.
Before coding, read: `.ai/stack.md`, `.ai/architecture.md`, `.ai/COMPONENT_MAP.md`, `.ai/AI_CONTEXT.json`.

Notes

• Run this tool from the project root where package.json exists.
• If .ai/ already exists, the tool will not overwrite existing files.
• After large refactors, run npm run ai:context to keep indexes up to date.