contextai

Universal context engineering CLI for AI coding agents. Define your project's conventions, stack, and architecture in a single context.config.ts file, then generate AI-readable context files for multiple tools from that single source of truth.

Website: www.contextai.run

Supported output targets

Target	File
OpenAI Codex / generic agents	AGENTS.md
Claude	CLAUDE.md
Cursor	.cursorrules
GitHub Copilot	.github/copilot-instructions.md
LLMs.txt	llms.txt
Kiro (AWS)	.kiro/steering/*.md
Windsurf	.windsurf/rules/*.md
Gemini CLI / Antigravity	GEMINI.md
Custom	any path via config

Quick start

npm install -g contextai

# Interactive setup — creates context.config.ts
contextai init

# Generate all enabled output files
contextai generate

Commands

Command	Description
contextai init	Interactive setup wizard
contextai generate	Generate output files from config
contextai generate --dry-run	Preview output without writing files
contextai generate --format json	Output JSON IR to stdout instead of writing files
contextai validate	Check output files are fresh and well-structured
contextai diff	Show diff between config and on-disk outputs
contextai watch	Watch config for changes and regenerate automatically

Configuration

Create a context.config.ts at your project root:

import { defineContext } from 'contextai';

export default defineContext({
  project: {
    name: 'my-app',
    stack: ['TypeScript', 'React', 'Node.js'],
    architecture: 'Monorepo with shared packages',
  },
  conventions: {
    code: [
      {
        title: 'Naming',
        items: ['camelCase for variables', 'PascalCase for components'],
      },
    ],
  },
  outputs: {
    'AGENTS.md': true,
    'CLAUDE.md': true,
    '.cursorrules': true,
    '.github/copilot-instructions.md': true,
    'llms.txt': true,
    '.kiro/steering': true,
    '.windsurf/rules': true,
    'GEMINI.md': true,
  },
});

Custom generators

export default defineContext({
  // ...
  outputs: {
    'CLAUDE.md': true,
    custom: [
      {
        path: 'docs/ai-context.md',
        generator: (config) => `# ${config.project.name}\n${config.project.architecture}`,
      },
    ],
  },
});

Built-in templates

Detected frameworks get convention templates applied automatically. Supported: nextjs, nestjs, express, remix, sveltekit.

export default defineContext({
  // ...
  templates: ['nextjs'],
});

Convention scopes

Each convention section can have an optional scope:

• 'agent-only' — included only in AI-facing output files
• 'human-only' — excluded from generated output
• omitted — included everywhere

conventions: {
  security: [
    {
      title: 'Auth',
      items: ['Use JWT tokens', 'Rotate secrets quarterly'],
      scope: 'agent-only',
    },
  ],
},

Git hook

During contextai init, you can optionally install a pre-commit git hook that runs contextai generate and stages the output files automatically.

Programmatic API

import { DefaultConfigParser, DefaultTemplateRegistry, defineContext } from 'contextai';

const parser = new DefaultConfigParser();
const config = await parser.load('./context.config.ts');

Requirements

• Node.js >= 20

License

MIT

---

www.contextai.run · GitHub · npm