Prelude

The open standard for machine-readable codebase context.

Prelude transforms your codebase into structured, AI-optimized context that makes working with LLMs 10x more effective.

Why Prelude?

Every time you start a new conversation with an AI assistant, you're forced to explain:

• What stack you're using
• How your codebase is organized
• What patterns and constraints you follow
• What decisions have been made

Prelude solves this.

Instead of repeating yourself, run prelude export and get a comprehensive, AI-optimized context document that captures:

• ✅ Your technology stack
• ✅ Project architecture and patterns
• ✅ Development constraints and preferences
• ✅ Key decisions and their rationale
• ✅ Recent changes and work sessions

Quick Start

# Install globally
npm install -g prelude-context

# Initialize in your project
cd your-project
prelude init

# Generate AI-optimized context
prelude export

The export is automatically copied to your clipboard - just paste it into Claude, ChatGPT, or any LLM!

Example Output

Here's what Prelude generates for a Next.js monorepo:

# Project Context
> Generated by Prelude

## 📋 Project Overview
**Name:** lucem-monorepo
**Description:** Universal operating system for verified work
**Version:** 1.0.0

## 🔧 Technology Stack
**Language:** TypeScript/JavaScript
**Runtime:** Node.js >=18.0.0
**Package Manager:** pnpm
**Frameworks:** Next.js, React
**Database:** Supabase, PostgreSQL
**ORM:** Drizzle ORM

## 🏗️ Architecture
**Type:** monorepo
**Patterns:** Component-based architecture, Server Components
**Key Directories:**
- apps/web - Next.js application
- packages/db - Database schemas and migrations

## ⚠️ Constraints & Preferences
**Must Use:**
- Turborepo for monorepo management
- TypeScript strict mode
- Server Components by default

See full example →

What Makes Prelude Different?

| Feature | Prelude | Manual Context | Other Tools | |---------|---------|----------------|-------------| | Automatic inference | ✅ | ❌ | ⚠️ | | Standards-based | ✅ | ❌ | ❌ | | Human-readable | ✅ | ✅ | ❌ | | Machine-optimized | ✅ | ❌ | ✅ | | Version controlled | ✅ | ⚠️ | ❌ | | Zero configuration | ✅ | N/A | ❌ | | Preserves manual edits | ✅ | ✅ | ❌ |

Core Commands

prelude init

Analyzes your codebase and creates a .context/ directory with:

• project.json - Project metadata
• stack.json - Technology stack
• architecture.json - Architecture patterns and structure
• constraints.json - Development rules and preferences
• decisions.json - Architecture decision records
• changelog.md - Project timeline

All files follow the Prelude specification and include JSON Schema validation.

Bootstrap from an existing CLAUDE.md:

prelude init --from-claude-md              # Uses ./CLAUDE.md
prelude init --from-claude-md docs/AI.md   # Custom path

Prelude parses your CLAUDE.md to extract project info, stack details, architecture, and constraints — then merges that with inference results. Your manual context gets preserved and structured.

prelude export

Generates a markdown document optimized for LLMs:

• Combines all context into a single, focused document
• Automatically copied to clipboard
• Perfect for starting new AI conversations

Export formats:

prelude export                      # Default markdown export
prelude export --format claude-md   # Generate a CLAUDE.md file
prelude export --format cursorrules # Generate a .cursorrules file
prelude export --format json        # Structured JSON export

The claude-md format generates a clean CLAUDE.md from your .context/ data — Prelude becomes the source of truth that outputs to whatever format your AI tool expects.

prelude validate

Validates all .context/ files against their JSON schemas:

prelude validate
# project.json — valid
# stack.json — valid
# architecture.json — valid
# constraints.json — valid
# decisions.json — valid
# All 5 file(s) passed validation.

Useful for CI pipelines to catch schema drift after manual edits. Exits with code 1 if any file fails.

prelude update

Re-analyzes your codebase and intelligently updates context:

prelude update
# Smart merge - preserves manual edits, updates inferred data

prelude update --dry-run
# Preview changes without applying them

prelude update --force
# Overwrite everything (except decisions/changelog)

Key features:

• ✅ Preserves manual edits - Never loses your customizations
• ✅ Shows what changed - Color-coded diff of updates
• ✅ Automatic backups - Saves history before every update
• ✅ Smart merging - Combines new inferred data with manual edits

prelude decision <title>

Logs architecture decisions:

prelude decision "Use Drizzle ORM instead of Prisma"
# Opens editor for you to document the decision and rationale

prelude query <topic> [options]

Scoped context lookup — search and filter your project context without exporting everything:

prelude query "error handling"              # topic search across everything
prelude query --scope src/api/              # architecture + constraints for a directory
prelude query --type constraints            # just constraints
prelude query "prisma" --type decisions --format json   # combined filters
prelude query --type stack --max-tokens 500 # budget-capped output

| Flag | Description | |------|-------------| | <topic> | Deep-search keyword across all context files | | --scope <path> | Filter to architecture/constraints relevant to a directory | | --type <type> | Return only one context type: project, stack, architecture, constraints, or decisions | | --format <md\|json> | Output format (default: md) | | --max-tokens <n> | Truncate output to fit a token budget |

Output goes to stdout (pipe-friendly), token estimate to stderr. At least one filter (topic, scope, or type) is required.

prelude watch

Tracks development sessions:

prelude watch
# Monitors file changes and logs your work session
# Press Ctrl+C when done to save the session

prelude serve

Starts Prelude as an MCP server over stdio transport:

prelude serve                    # Serve context for current directory
prelude serve --root ~/my-project  # Serve context for a specific project

AI tools connect to this server to query your project context programmatically — no clipboard needed.

prelude mcp-config

Prints the configuration snippet to connect Prelude to your AI tool:

prelude mcp-config --client claude-code      # Default
prelude mcp-config --client claude-desktop
prelude mcp-config --client cursor

MCP Server Integration

Prelude can run as an MCP (Model Context Protocol) server, making your project context directly available to AI tools like Claude Code, Claude Desktop, and Cursor — no copy-paste required.

Quick Setup (Claude Code)

# From your project directory (must have .context/ — run prelude init first)
prelude mcp-config --client claude-code

This prints the command to register Prelude as an MCP server. Once connected, your AI tools have access to three tools:

| Tool | Description | |------|-------------| | prelude_query | Full-power context queries with topic, scope, and type filtering | | prelude_compact | Token-efficient context for prompt injection (~800 tokens) | | prelude_status | Check which context files are available |

And three resources for passive context discovery:

| Resource URI | Description | |-------------|-------------| | prelude://context/full | Complete project context as markdown | | prelude://context/compact | Token-efficient summary | | prelude://context/{type} | Individual context files (project, stack, architecture, constraints, decisions) |

Other Clients

prelude mcp-config --client claude-desktop
prelude mcp-config --client cursor

Manual Setup

Start the server directly:

prelude serve --root /path/to/your/project

The server uses stdio transport. Configure your MCP client to run this command.

prelude mcp-config [options]

Prints the configuration snippet for connecting Prelude to your AI tool:

prelude mcp-config                          # Claude Code (default)
prelude mcp-config --client claude-desktop   # Claude Desktop
prelude mcp-config --client cursor           # Cursor
prelude mcp-config --root /path/to/project   # Specify project root

GitHub Action

Prelude ships with a GitHub Action to automatically keep .context/ files up to date:

# .github/workflows/prelude.yml
name: Update Context
on:
  push:
    branches: [main]
    paths: [package.json, pyproject.toml, Cargo.toml, go.mod, "src/**"]

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: adjective-rob/prelude@main

The action runs prelude update and opens a PR if .context/ files changed. See action.yml for configuration options.

Use Cases

🎯 Starting New Conversations

Paste your Prelude export to instantly give any LLM full context:

Here's my project context:

[paste prelude export]

I want to add user authentication. What's the best approach given our stack?

🐛 Debugging

Here's my project context:

[paste prelude export]

I'm seeing this error: [error]
In file: apps/web/app/api/route.ts

What's likely causing this?

🏗️ Architecture Decisions

Here's my project context:

[paste prelude export]

Should I use Server Actions or API routes for [feature]?
Consider our existing patterns and constraints.

🔍 Scoped Context for AI Agents

# Feed only relevant context to an AI agent working on a specific directory
prelude query --scope src/api/ --format json | my-agent

# Quick lookup before asking an LLM about a topic
prelude query "authentication" --max-tokens 500

📚 Onboarding

Share your .context/ directory with new team members so they can:

• Understand the stack instantly
• Learn architectural patterns
• See past decisions and rationale

🔄 Keeping Context Fresh

# After adding dependencies
npm install @tanstack/react-query
prelude update

# After restructuring
prelude update --dry-run  # Preview changes first
prelude update            # Apply updates

The Prelude Format

Prelude is an open standard - not just a CLI tool. The format is:

• Versioned - Semantic versioning for safe evolution
• Validated - JSON Schema for every file type
• Extensible - Add custom fields as needed
• Language-agnostic - Implement in any language

See the full specification →

All schemas are hosted at: https://adjective.us/prelude/schemas/v1/

Advanced Usage

Manual Edits

The .context/ files are human-readable JSON. Edit them directly:

{
  "$schema": "https://adjective.us/prelude/schemas/v1/constraints.json",
  "version": "1.0.0",
  "mustUse": [
    "TypeScript strict mode",
    "Server Components by default"
  ],
  "preferences": [
    {
      "category": "state-management",
      "preference": "Prefer URL state over client state",
      "rationale": "Improves sharability and reduces bugs"
    }
  ]
}

Manual edits are preserved when you run prelude update - the smart merge system tracks what's inferred vs. what you've customized.

Custom Fields

Add project-specific fields - the schemas allow additional properties:

{
  "$schema": "https://adjective.us/prelude/schemas/v1/project.json",
  "version": "1.0.0",
  "name": "my-app",
  "customField": "your data",
  "team": [
    { "name": "Alice", "role": "Tech Lead" }
  ]
}

Integration

Use Prelude in your tools:

import { readFileSync } from 'fs';
import { join } from 'path';

// Read project context
const project = JSON.parse(
  readFileSync(join(process.cwd(), '.context/project.json'), 'utf-8')
);

console.log(`Project: ${project.name}`);
console.log(`Stack: ${project.stack?.language}`);

Requirements

• Node.js >= 18.0.0
• Git (optional, for tracking changes)

Project Structure

your-project/
├── .context/              # Created by Prelude
│   ├── project.json      # Project metadata
│   ├── stack.json        # Technology stack  
│   ├── architecture.json # Architecture patterns
│   ├── constraints.json  # Development rules
│   ├── decisions.json    # Architecture decisions
│   ├── changelog.md      # Project timeline
│   └── .prelude/         # State tracking (gitignore *.session.json)
│       ├── state.json    # Tracks inferred vs manual fields
│       └── history/      # Automatic backups
├── .gitignore            # Add .context/*.session.json
└── ...

Note: Commit .context/ to version control (except *.session.json files).

FAQ

Should I commit .context/ to git?

Yes! The context is part of your project documentation. Exception: .context/*.session.json should be gitignored (it's for local work tracking).

How often should I update the context?

Run prelude update after major changes (new dependencies, restructuring). Run prelude export whenever you need fresh context for an AI conversation.

What happens to my manual edits?

They're preserved! Prelude tracks which fields are inferred vs. manually edited. When you run update, it only changes auto-detected data while keeping your customizations.

Can I use this with any LLM?

Yes! The export format is optimized for Claude, ChatGPT, Gemini, and any text-based AI assistant.

What if my project structure is unusual?

Prelude's inference is smart but not perfect. Just edit the .context/ files directly - they're human-readable JSON.

Does this work with non-JavaScript projects?

Yes! Prelude has full inference support for JavaScript/TypeScript, Python, Rust, and Go — including dependency parsing, framework detection, testing tools, and conventions. The format itself is language-agnostic.

Roadmap

• [x] Smart context updates with manual edit preservation
• [x] Scoped context query engine (prelude query)
• [x] MCP server for AI tool integration (prelude serve)
• [x] Full inference for Python (pyproject.toml, requirements.txt)
• [x] Full inference for Rust (Cargo.toml) and Go (go.mod)
• [x] CLAUDE.md / .cursorrules export (prelude export --format claude-md)
• [x] Bootstrap from CLAUDE.md (prelude init --from-claude-md)
• [x] Schema validation command (prelude validate)
• [x] GitHub Action for automated updates
• [ ] VS Code extension for inline context
• [ ] Plugin system for custom inference
• [ ] Context diff tool
• [ ] Temporal brain layer (learned heuristics from AI tool usage)

Design Principles

1. Human-readable first - All files are readable JSON/Markdown
2. AI-optimized - Structured for maximum LLM effectiveness
3. Standards-based - Open spec, not proprietary format
4. Zero lock-in - Edit files manually, use any tool
5. Incremental adoption - Works with partial information
6. Preserve intent - Never lose manual customizations

Examples

• Next.js Monorepo - Turborepo + Drizzle + Supabase
• Express API - REST API with PostgreSQL
• Vite React App - Frontend SPA

Contributing

Areas we'd love help with:

• Improved inference patterns
• Support for more languages/frameworks
• Example projects
• Documentation improvements
• Bug reports and feature requests

License

MIT © Adjective

Links

• Specification
• Schema Documentation
• Examples
• NPM Package
• Issues & Feature Requests

Built by Adjective - Sovereign Software for AI-Native Teams