handoff-md

One command to generate a portable AI context file from any repo.

  $ npx handoff-md

  ✅ HANDOFF.md generated (~2,847 tokens)
     /Users/dev/stitchops/HANDOFF.md

Problem

Every time you switch AI models — Claude to GPT, Cursor to Copilot, or even between sessions — the new model starts from zero. It doesn't know your architecture, conventions, or what you were working on five minutes ago. You either waste 10 minutes re-explaining everything, or the model writes code that doesn't match your project.

Install

npx handoff-md

No config. No API keys. No dependencies. Just Node.js + git.

Example Output

Running npx handoff-md on a real project (StitchOps) generates:

# HANDOFF — stitchops
> Generated by `handoff` at 2026-02-27 14:32:08
> Branch: `feat/payment-flow` | Last commit: a3f8c1d Add Stripe webhook handler

## Stack
Next.js + TypeScript | pnpm
ORM: Prisma | DB: PostgreSQL | Auth: NextAuth | Deploy: Vercel | Test: Vitest

## Structure
├── src/
│   ├── app/           # App router pages
│   ├── components/    # React components
│   ├── lib/           # Shared utilities
│   ├── server/        # tRPC routers
│   └── styles/        # Global styles
├── prisma/            # Database schema
└── tests/             # Test suites

## Conventions
- Naming: kebab-case files, PascalCase components
- API: tRPC routers in src/server/
- State: Zustand stores in src/lib/stores/

## Recent Activity
- `a3f8c1d` Add Stripe webhook handler (2 hours ago)
- `b7e2f09` Create payment intent API route (3 hours ago)
- `c91a3d4` Add pricing page UI (yesterday)

## Current State
**Uncommitted changes (3 files):**
- M src/server/routers/payment.ts
- M prisma/schema.prisma
- A src/lib/stripe.ts

## Known Issues
- **TODO** `src/server/routers/payment.ts:42` Handle subscription cancellation
- **FIXME** `src/components/PricingCard.tsx:18` Currency formatting for non-USD

Paste this into any AI model — Claude, GPT, Gemini, Codex, local models — and it instantly understands your project.

CLI Options

Flag	Description
[path]	Target repository path (default: .)
-c, --copy	Copy output to clipboard
-s, --stdout	Print to stdout instead of writing file
-v, --verbose	Show detailed analysis info
-f, --format <level>	compact (~1.5K tokens), standard (~3K), full (~5K)
--install-hook	Install as git post-commit hook

Why not CLAUDE.md?

	HANDOFF.md	CLAUDE.md
Updates	Auto-generated from repo state — always current	Manually written — goes stale
Portability	Works with Claude, GPT, Gemini, Copilot, Codex, any model	Claude-only by design
Scope	Git activity, uncommitted changes, TODOs, live project state	Static rules and conventions

HANDOFF.md complements CLAUDE.md — if you have one, handoff reads it and includes your rules in the output.

Contributing

Contributions welcome. Open an issue or submit a PR.

git clone https://github.com/guvencem/handoff-md.git
cd handoff-md
npm install
npm run build
node dist/index.js

License

MIT