Persistence

Stop AI from hallucinating about your codebase.

Persistence scans your project and generates a ground truth document that AI coding tools actually read. No more wrong imports, phantom functions, or made-up API routes.

Quick Start

npx persistence-cli scan

That's it. Your AI tools now know the truth about your project.

What It Does

Persistence scans your project and extracts:

| What | Where | |------|-------| | Tech Stack | package.json — frameworks, ORMs, key libraries | | Database Schema | Prisma schemas, Drizzle definitions, or SQL migrations | | Environment Variables | .env.example / .env — variable names only, never values | | TypeScript Config | tsconfig.json — path aliases, strict mode, target | | Project Structure | src/ or app/ directory tree, 3 levels deep | | Scripts | package.json scripts — dev, build, test, deploy |

What It Generates

| File | Purpose | |------|---------| | PERSISTENCE.md | Standalone ground truth document | | .cursorrules | Injected into Cursor AI rules | | CLAUDE.md | Injected into Claude Code context | | .github/copilot-instructions.md | Injected into GitHub Copilot instructions | | .windsurfrules | Injected into Windsurf AI rules |

Existing content in these files is preserved — Persistence prepends the ground truth above your existing rules with a clear separator.

Supported AI Tools

• Cursor — .cursorrules
• Claude Code — CLAUDE.md
• GitHub Copilot — .github/copilot-instructions.md
• Windsurf — .windsurfrules
• Aider — Use PERSISTENCE.md directly with /read PERSISTENCE.md

CLI Reference

persistence scan

Scan the project and inject ground truth into AI config files.

persistence scan                              # Default: cursor + claude
persistence scan --targets cursor,claude,copilot,windsurf  # All targets
persistence scan --dry-run                    # Preview without writing
persistence scan --verbose                    # Show detailed parser output

| Flag | Description | |------|-------------| | --targets <list> | Comma-separated targets: cursor, claude, copilot, windsurf. Default: cursor,claude | | --dry-run | Print output without writing any files | | --verbose | Show what each parser found or skipped |

persistence init

First-time setup: runs scan and configures .gitignore.

persistence init
persistence init --targets cursor,claude,copilot,windsurf

Before & After

Without Persistence

You: "Add a new API route for orders"

AI: import { db } from '@/lib/database'        ← wrong path
    import { OrderModel } from '@/models'       ← doesn't exist
    export default function handler(req, res) {  ← wrong pattern (you use App Router)

With Persistence

You: "Add a new API route for orders"

AI: import { db } from '@/db/client'            ← correct path
    import { Order } from '@prisma/client'       ← real type from your schema
    export async function GET(request: Request) { ← correct App Router pattern

The AI reads your PERSISTENCE.md and knows:

• Your actual path aliases (@/db/* → ./src/db/*)
• Your real database schema (Order table with its actual columns)
• Your project structure (App Router in src/app/)

How It Works

1. Scan — Reads your config files and source structure
2. Generate — Produces a compact markdown summary
3. Inject — Prepends into AI tool config files
4. Preserve — Your existing rules stay intact below a separator

Re-run persistence scan whenever your project changes significantly (new tables, new dependencies, restructured folders).

Contributing

Contributions welcome! Areas that could use help:

• New parsers — Django, Rails, Go modules, Rust Cargo
• New targets — Additional AI tools
• Smarter detection — Better framework/library identification
• Testing — Unit tests for parsers

git clone https://github.com/nitishsm/persistence-cli.git
cd persistence-cli
npm install
npm run build
npm link  # Test locally with `persistence scan`

License

MIT