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.

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

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

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! While the CLI is built with Node.js, the Prelude format works with any language. The inference currently focuses on JavaScript/TypeScript but the format is universal.

Roadmap

• [x] Smart context updates with manual edit preservation
• [x] Scoped context query engine (prelude query)
• [ ] Improved inference for Python, Rust, Go
• [ ] VS Code extension for inline context
• [ ] GitHub Action for automated updates
• [ ] Plugin system for custom inference
• [ ] CLI validation command
• [ ] Context diff tool

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