🧠 promptpilot-ai

The AI context layer for your codebase

Works with Claude Code · Cursor · Both

Scan your project once → AI understands everything → no more blind file hunting

🤔 The Problem

Every time you ask Claude or Cursor to build something, it starts from zero:

AI: Let me look at your project structure...
AI: Reading package.json...
AI: Reading src/app/...
AI: Reading components/...
AI: Hmm, where is the auth module?

That's 8–12 file reads (~25,000 tokens) just to understand context — before writing a single line of code.

✅ The Solution

Run promptpilot-ai init once. It scans your codebase and writes structured context files that AI tools read automatically.

AI: (reads .claude/context/architecture.md → knows everything)
AI: Got it. Here's the implementation plan...

2–3 reads. ~6,000 tokens. Straight to the code.

🚀 Quick Start

# In your project directory
npx promptpilot-ai@latest init

You'll be asked which AI tool you're using:

? Which AI tool are you using?
  ❯ Claude Code
    Cursor
    Both

That's it. Open your project in Claude or Cursor — context is loaded automatically.

🗂️ What Gets Generated

For Claude Code

your-project/
├── CLAUDE.md                        ← context index (auto-loaded by Claude)
├── .claude/
│   ├── settings.json                ← permissions pre-configured
│   ├── commands/
│   │   ├── ask.md                   ← /ask slash command
│   │   ├── plan.md                  ← /plan slash command
│   │   └── sync.md                  ← /sync slash command
│   └── context/
│       ├── architecture.md          ← project structure
│       ├── stack.md                 ← tech stack & commands
│       ├── patterns.md              ← naming & code conventions
│       └── modules/
│           ├── auth.md
│           ├── components.md
│           └── ...
└── .git/hooks/post-commit           ← auto-sync on commit

For Cursor

your-project/
└── .cursor/
    └── rules/
        ├── architecture.mdc         ← always loaded (alwaysApply: true)
        ├── stack.mdc                ← always loaded
        ├── patterns.mdc             ← always loaded
        └── modules/
            ├── auth.mdc             ← loaded when you open auth files
            ├── components.mdc       ← loaded when you open component files
            └── ...

💡 Cursor's .mdc rules use alwaysApply: true for global context and file-glob matching for module-level context — so you only pay for what's relevant.

🏗️ Multi-Repo Workspace (Frontend + Backend)

your-workspace/        ← run init here
  backend/             ← NestJS / Express
  frontend/            ← Next.js / React

cd your-workspace
npx promptpilot-ai@latest init

promptpilot-ai auto-detects both repos and generates a bridge map:

## Endpoint Map

| Method | Path        | Frontend File               | Backend File                    | Handler   |
|--------|-------------|-----------------------------|---------------------------------|-----------|
| GET    | /users      | src/app/users/page.tsx      | src/users/users.controller.ts   | findAll() |
| POST   | /auth/login | src/app/auth/login/page.tsx | src/auth/auth.controller.ts     | login()   |

Now when you say /ask add a user profile page, AI reads bridge.md, finds the matching endpoint, and implements both frontend and backend in one pass.

📊 Token Savings

| | Without promptpilot-ai | With promptpilot-ai | |---|---|---| | File reads per task | 8–12 | 2–3 | | Tokens per task | ~25,000 | ~6,000 | | Savings | — | ~70% fewer tokens | | Multi-repo cross-lookup | Manual, many reads | Auto via bridge.md |

⚡ Commands

CLI

| Command | Description | |---|---| | npx promptpilot-ai init | First-time setup — scan project and generate context | | npx promptpilot-ai sync | Re-scan after major restructuring or new modules |

Claude Code Slash Commands (after init)

| Command | Description | |---|---| | /ask <request> | Natural language → plan → execute (cross-repo aware) | | /plan <request> | Generate a plan only — review before executing | | /sync | Trigger a context sync from inside Claude Code |

🛠️ Supported Stacks

| Category | Supported | |---|---| | Frontend | Next.js (App + Pages Router), React (Vite), Vue, Svelte, Astro, Remix | | Backend | NestJS, Express, Fastify, Hono, Koa | | Languages | TypeScript, JavaScript | | Databases | PostgreSQL, MySQL, MongoDB, SQLite | | ORMs | Prisma, Drizzle, TypeORM | | Package Managers | pnpm, npm, yarn | | Testing | Vitest, Jest |

🔄 Keeping Context Fresh

| Trigger | What happens | |---|---| | git commit | Post-commit hook auto-updates changed modules | | New module or endpoint | Run npx promptpilot-ai sync manually | | Major refactor | Run npx promptpilot-ai sync manually |

❓ FAQ

Do I need an API key? No. Uses your existing Claude Code plan or Cursor subscription — no extra API keys.

Does it work without git? Yes. Without .git, the filesystem is walked directly (skipping node_modules, dist, .next, etc.).

Can I use it with both Claude and Cursor? Yes — select "Both" during init. It generates .claude/ and .cursor/rules/ simultaneously.

Is it safe to commit the generated files? Yes, commit them. Teammates get context immediately without running init themselves.

📄 License

MIT