I got tired of re-explaining my codebase to AI every session — so I built prepcli

Here's a scene that probably feels familiar.

You open Claude Code, Cursor, or Codex. You type a request. The AI asks, “What's your stack?” You tell it — again. It writes code that ignores a constraint you mentioned last week. You correct it. Halfway through you remember the auth module is frozen and say “oh, don't touch that” — and it backs out the change it already made. Twenty minutes later you've got a fix, but half that time went to re-teaching the AI things it should have already known.

I kept hitting this, every day. So I built prepcli to fix it — live on npm today as @prepcli/prepcli@0.3.1. Here's what was broken, and how I solved each piece.

The problem

Four things quietly break in every AI session

None of these are the model's fault. They're context problems — the AI carries nothing between sessions, and your tools don't help it remember.

The fix

So I built prepcli

prepcli isn't another AI tool — it's a thin layer underneath the ones you already use: Claude Code, Cursor, Codex. It installs a set of slash commands — a universal /prepcli plus focused ones (/debug, /plan, /prep, /refactor, /review, /write) — that you trigger like /prepcli the login redirect loop, and it takes those four problems apart one at a time.

Fix 1 · Context

It reads your project before it asks anything

When you run prepcli init, it scans your codebase — the framework and the libraries you actually depend on, how the project is wired, your package manager and folder layout — and saves a compact picture of it to a small .prepclirc. Then you add the things a scan can't infer: your conventions and hard limits — the rules the AI keeps getting wrong.

From then on, every workflow loads that context silently — before it asks you a single question — and the AI is told not to announce it. So it never asks “what's your stack?”: it already knows it's Next.js + tRPC + Prisma. And it follows your project's rules without being reminded — for example:

• “Don't pull in a new date library — use the existing dayjs wrapper.”
• “Shared helpers go in lib/utils and get imported — never re-written inline in feature files.”
• “Never call fetch directly — go through the apiClient.”

That's the context worth remembering every session — how this codebase is built and the patterns it expects. The cold start is gone, and the AI stops fighting your conventions — that's problems one and two handled.

Fix 2 · Decisions

It records the why into git

When you finish and run git push, a pre-push hook quietly asks one question — “Final summary?” — and you type one sentence. prepcli writes a structured record: what was done, why this approach, what was ruled out, which commit it maps to.

Where does it go? Not your source tree (noise), not a database you have to trust (lock-in). It goes into a hidden git branch: prepcli/shadow/v1.

It's an orphan branch — it shares no history with your code and never touches your working tree, yet it travels with the repo. Anyone who clones it runs git fetch origin prepcli/shadow/v1 and reads the whole decision history with plain git show — no account, no service, no internet required. The reasoning now lives where the code lives, forever. That's problem three solved: the why is a first-class artifact.

Fix 3 · Self-improving

It learns the questions you forget to answer

This is the thesis the whole project rests on:

Most bad AI output isn't a bad model — it's a bad prompt, missing context the AI couldn't have known to ask for.

So before doing any work, the workflow asks four sharp, task-specific questions, assembles a structured prompt — role, goal, constraints, scope — and shows it to you. You approve by typing GO. A precise prompt up front means the AI gets it right on the first try instead of three rounds of correction. The win isn't faster typing — it's fewer redos.

And here's the part that compounds. Anything you reveal after GO — “it also needs to work on mobile,” “don't touch the NextAuth config” — is a delta: the gap between what you should have said and what you did. prepcli classifies each one and stores it as a generalized question — never your raw words, just “Are there modules that must not be touched?” When the same gap recurs enough times on a workflow, it gets promoted into the four questions you're asked up front next time. The prompt literally learns what you keep forgetting. Watch the trend with prepcli stats — and it's all a local counter: no embeddings, no vector database, no cloud. That's problem four — fixed, and re-fixing itself every session.

In practice

What a session actually looks like

Say you're chasing a timezone bug. You type:

/prepcli poll times show the wrong time for people in other timezones

prepcli already knows your stack and layout, so it doesn't ask about those. It asks only what it can't infer — one question at a time:

Three answers later, it hands the AI a complete brief — your answers plus the context it already had — and waits for your GO:

━━━ STRUCTURED TASK PROMPT ━━━

ROLE
  Senior Next.js engineer, fluent in timezone handling with dayjs.

GOAL
  Make poll times render in each viewer's local timezone — display only.

CONTEXT
  - Stack: Next.js + tRPC + Prisma + Postgres     (from project context)
  - Dates go through lib/date (dayjs wrapper) — never add a new date lib
  - Feature code in app/, shared helpers in lib/  (from structure scan)

SPECIFICS
  - Current: correct for IST viewer, wrong for other timezones
  - DB already stores correct UTC — the bug is display-side only
  - Target: every viewer sees times in their own local timezone

OUTPUT RULES
  - Patch the formatting layer only; do not touch storage
  - Use the existing lib/date wrapper — no new dependencies

Reply GO and the AI starts with the full picture — right library, right layer, nothing off-limits — instead of guessing. Three quick answers turn a vague one-liner into a prompt the AI can't misread.

By design

Built to stay out of your way

Three things I decided early, because a tool you invite into every project has to be safe to trust:

• It never touches your code. prepcli keeps its records in a separate, hidden corner of git — it never edits, moves, or reformats your files. Your working directory is exactly as you left it.
• It works with no account, fully offline. Context, decision history, and the learning loop all run on your own machine. An account is optional — only needed later if you want to sync across machines.
• There's no lock-in. Your decision history lives inside your own git repo, readable with plain git commands. Stop using prepcli tomorrow and everything you recorded is still right there — nothing trapped in someone else's database.

Status

Where it stands today

Built and live today: context injection (including a scan of your codebase structure), the shadow-branch decision log, offline/online modes, and the self-improving delta loop. Coming next: optional cloud sync across machines, semantic retrieval for the question pool, and team sharing — but I'm not pretending those exist yet. The single-developer experience is complete, and it's the part that earns its keep.

Open source

It's open — come build it with me

prepcli is MIT-licensed and fully open on GitHub. It's early, and the roadmap — cloud sync, retrieval for the question pool, team sharing — is wide open. If you have an idea, hit a rough edge, or there's a workflow you wish existed, I'd love the input:

• Open an issue for bugs, ideas, or “this confused me” — all three are useful.
• Send a PR — new tool targets, better gap detection, docs, anything.
• Just tell me what breaks when you run the shadow branch on a real repo.

Star it, fork it, or file the issue you wish someone else would — github.com/bhavviik/prepcli.

# install
npm install -g @prepcli/prepcli
# …or
curl -fsSL https://prepcli.in/install.sh | bash

# then, in your project
prepcli install   # add workflows to Claude Code / Cursor / Codex
prepcli init      # scan your stack and set up context

I'd genuinely love feedback — especially from anyone who runs the shadow branch on a real repo. Tell me what breaks.