claude-snap 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohammad Ali Shuvo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,342 @@
+<div align="center">
+
+<img src="assets/claude-snap-banner.svg" alt="claude-snap banner" width="100%" />
+
+<br/>
+<br/>
+
+<img src="assets/claude-snap-logo.svg" alt="claude-snap logo" width="80" />
+
+# claude-snap
+
+**Never re-explain your codebase to Claude again.**
+
+`claude-snap` is a zero-config CLI that snapshots your project context — stack, architecture, conventions, git state — and restores it in Claude in seconds. Works across unlimited sessions.
+
+<br/>
+
+[![npm version](https://img.shields.io/npm/v/claude-snap.svg?style=flat-square&color=cb3837)](https://www.npmjs.com/package/claude-snap)
+[![npm downloads](https://img.shields.io/npm/dm/claude-snap.svg?style=flat-square&color=blue)](https://www.npmjs.com/package/claude-snap)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D16.0.0-brightgreen?style=flat-square)](https://nodejs.org)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://github.com/shuvo18103107/claude-snap/pulls)
+
+<br/>
+
+[Installation](#-installation) · [How It Works](#-how-it-works) · [Commands](#-commands) · [Supported Stacks](#-supported-stacks) · [Contributing](#-contributing)
+
+</div>
+
+---
+
+## The Problem
+
+You're deep in a feature with Claude — architecture decided, patterns set, halfway through a refactor. Then the token limit hits.
+
+**New session. Claude knows nothing.** You spend 10 minutes re-explaining the stack, the conventions, what you were doing, why.
+
+Every. Single. Time.
+
+---
+
+## The Solution
+
+`claude-snap` maintains two files per project:
+
+| File | Purpose |
+|------|---------|
+| `CLAUDE.md` | Project bible — stack, architecture, conventions, rules. Auto-generated from your codebase. |
+| `.claude/state.md` | Live session state — what's in progress, next action, blockers. Claude writes this at session end. |
+
+One command at the start of a session. Claude reads both files and comes back fully oriented in ~5 seconds.
+
+```
+claude-snap end    →  Claude writes exact state to file
+claude-snap start  →  Claude reads files → back in flow instantly
+```
+
+---
+
+## Demo
+
+**`claude-snap init` — auto-detects your entire project in seconds**
+
+![claude-snap init demo](assets/demo-init.png)
+
+<br/>
+
+**`claude-snap start` — session-start prompt, copied to clipboard**
+
+![claude-snap start demo](assets/demo-start.png)
+
+<br/>
+
+**`claude-snap status` — see your live session state at a glance**
+
+![claude-snap status demo](assets/demo-status.png)
+
+<br/>
+
+**`claude-snap end` — session-end prompt, copied to clipboard**
+
+![claude-snap end demo](assets/demo-end.png)
+
+---
+
+## Installation
+
+```bash
+npm install -g claude-snap
+```
+
+That's it. No config files, no accounts, no API keys.
+
+---
+
+## Quick Start
+
+```bash
+# 1. Go to any project
+cd your-project
+
+# 2. Initialize — auto-detects everything
+claude-snap init
+
+# 3. Start a session — paste into Claude
+claude-snap start
+
+# 4. End a session — paste into Claude
+claude-snap end
+```
+
+**The workflow:**
+
+1. Run `claude-snap start` → prompt copied to clipboard
+2. Paste into Claude → Claude reads `CLAUDE.md` + `state.md`, replies with a crisp status
+3. Work with Claude normally
+4. When session ends (or token limit hits), run `claude-snap end` → paste into Claude
+5. Claude writes the exact state to `.claude/state.md`
+6. Next session: repeat from step 1
+
+---
+
+## How It Works
+
+### `claude-snap init`
+
+Scans your project and auto-generates `CLAUDE.md` — your project bible:
+
+| What | How It's Detected |
+|------|------------------|
+| Language | `tsconfig.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pubspec.yaml` |
+| Framework | `package.json` deps — React, Next.js, Express, NestJS, Django, FastAPI, Gin, Axum... |
+| UI Library | Tailwind, shadcn/ui, Material UI, Chakra, Radix, Mantine, Ant Design |
+| Test setup | Jest, Vitest, pytest, Playwright, Cypress |
+| Package manager | `pnpm-lock.yaml`, `yarn.lock`, `bun.lockb`, `package-lock.json` |
+| Commands | `package.json` scripts (dev, test, build) |
+| Git history | Recent commits, most active files, current branch |
+| Design system | Figma URLs, design tokens, Storybook, Tailwind config |
+
+Then asks ~5 questions for things static analysis can't detect: architecture overview, coding conventions, domain concepts, critical rules.
+
+### `claude-snap start`
+
+Generates a compact prompt (~50 tokens) that tells Claude to:
+- Read `CLAUDE.md` + `.claude/state.md`
+- Reply with current project, in-progress task, next action, and blockers
+- Then wait for your instruction
+
+### `claude-snap end`
+
+Generates a detailed prompt that tells Claude to write directly to `.claude/state.md` with:
+- Every incomplete task (file paths, function names, what's done vs left)
+- The single most important next step
+- Open questions and blockers
+- Carry-over context a cold session would need
+
+### `claude-snap checkpoint`
+
+A lighter mid-session sync. Updates only "In Progress" and "Next Action". Run it after a big commit.
+
+---
+
+## Commands
+
+```bash
+claude-snap init          # Set up a project (interactive, auto-detects stack)
+claude-snap start         # Session start — loads context prompt to clipboard
+claude-snap end           # Session end — state-update prompt to clipboard
+claude-snap checkpoint    # Mid-session quick sync (after big commits)
+claude-snap status        # View current state.md in terminal
+claude-snap decisions     # View decision log
+claude-snap scan          # Re-scan project and regenerate CLAUDE.md
+```
+
+### Flags
+
+```bash
+claude-snap init --yes    # Skip prompts, use all auto-detected values
+claude-snap start --no-copy   # Print prompt only, don't copy to clipboard
+claude-snap end --no-copy     # Print prompt only, don't copy to clipboard
+```
+
+---
+
+## What Gets Created
+
+```
+your-project/
+├── CLAUDE.md                      ← Project bible (auto-generated, you refine)
+├── .claudeignore                  ← Tells Claude which files to skip
+└── .claude/
+    ├── state.md                   ← Live session state (Claude writes this)
+    ├── decisions.md               ← Key architectural decision log
+    ├── settings.json              ← Claude Code Stop hook (session-end reminder)
+    └── prompts/
+        ├── session-start.md       ← The start prompt
+        ├── session-end.md         ← The end prompt
+        └── checkpoint.md          ← The checkpoint prompt
+```
+
+> **Pro tip:** Commit `.claude/` to git. State syncs across machines and teammates automatically. New team member? They run `claude-snap start` and Claude already knows the architecture and what's in progress.
+
+---
+
+## Example Files
+
+<details>
+<summary><strong>CLAUDE.md — generated output</strong></summary>
+
+```markdown
+# ironforge-api
+> High-performance REST API for the Esois platform
+
+## Stack
+TypeScript, Express, Prisma, Jest
+**Testing:** Jest
+**UI:** (none)
+
+## Structure
+src/routes/
+src/services/
+src/db/
+src/types/
+tests/
+
+### Key Directories
+- `src/routes/`   → Express route handlers
+- `src/services/` → Business logic layer
+- `src/db/`       → Database queries (raw SQL via pg client)
+- `src/types/`    → Shared TypeScript interfaces
+
+## Architecture
+REST API → Service layer → DB queries. No ORM — raw SQL in src/db/queries/.
+Auth via JWT (access + refresh tokens). Redis for session storage.
+
+## Coding Conventions
+- Async/await everywhere, no .then() chains
+- Custom AppError class for all thrown errors
+- Never inline SQL — all queries in src/db/queries/
+
+## Commands
+\`\`\`bash
+# Dev
+npm run dev
+
+# Test
+npm test
+
+# Build
+npm run build
+\`\`\`
+
+## Critical Rules
+- Never inline SQL — use src/db/queries/
+- Never expose raw errors to the client
+```
+
+</details>
+
+<details>
+<summary><strong>state.md — what Claude writes after a session</strong></summary>
+
+```markdown
+# Session State
+_Last updated: 2025-04-04 | Project: ironforge-api_
+
+## Status
+🟡 In progress
+
+## Currently In Progress
+- [ ] `src/services/auth.ts` → `refreshToken()` method
+  - Done: input validation, token decode, expiry check (~line 89)
+  - Remaining: DB update for token rotation, emit `auth.refresh` event
+
+## Next Action
+> Add DB update call in refreshToken() around line 89, then emit the event.
+> Pattern reference: src/services/user.ts:createUser() for event emission.
+
+## Open Questions
+- Should refresh tokens be single-use? Leaning yes for security.
+
+## Carry-over Context
+- Mid-refactor: old token pattern used sessions table, new uses token_store table. 40% migrated.
+```
+
+</details>
+
+---
+
+## Supported Stacks
+
+| Language | Frameworks Detected |
+|----------|-------------------|
+| **JavaScript / TypeScript** | React, Next.js, Remix, Nuxt, Vue, Angular, Svelte, Astro, SolidJS, Express, Fastify, NestJS, Koa, Hono, tRPC, GraphQL |
+| **Python** | Django, FastAPI, Flask |
+| **Rust** | Axum, Actix |
+| **Go** | Gin, Echo, Fiber |
+| **Java / Kotlin** | Maven (pom.xml), Gradle (build.gradle) |
+| **Dart / Flutter** | pubspec.yaml |
+| **Ruby** | Gemfile |
+| **PHP** | composer.json |
+| **Elixir** | mix.exs |
+
+---
+
+## Claude Code Integration
+
+If you use the **Claude Code CLI**, `CLAUDE.md` is read automatically at session start — no paste needed.
+
+`claude-snap init` also writes `.claude/settings.json` with a **Stop hook** that reminds you to run `claude-snap end` whenever a Claude Code session ends.
+
+---
+
+## For Teams
+
+Commit `.claude/` to your repository. Benefits:
+
+- **Onboarding** — new engineers run `claude-snap start` and Claude already knows the full architecture
+- **Context sync** — state stays consistent across machines
+- **Decision log** — `.claude/decisions.md` tracks key architectural choices over time
+- **No setup** — teammates install `claude-snap` globally, then just use it
+
+---
+
+## Contributing
+
+Contributions welcome!
+
+```bash
+git clone https://github.com/shuvo18103107/claude-snap.git
+cd claude-snap
+npm install
+npm link
+```
+
+Open issues or PRs → [github.com/shuvo18103107/claude-snap](https://github.com/shuvo18103107/claude-snap)
+
+---
+
+## License
+
+MIT © [Mohammad Ali Shuvo](https://github.com/shuvo18103107)

package/bin/claude-snap.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+'use strict';
+
+const { Command } = require('commander');
+const pkg = require('../package.json');
+
+const program = new Command();
+
+program
+  .name('claude-snap')
+  .description('Multi-session Claude context manager — keeps Claude in sync across sessions')
+  .version(pkg.version);
+
+program
+  .command('init')
+  .description('Set up Claude context for a project (auto-detects stack, structure, git history)')
+  .option('-y, --yes', 'Accept all auto-detected values without prompts')
+  .action((opts) => require('../src/commands/init')(opts));
+
+program
+  .command('scan')
+  .description('Re-scan project and regenerate CLAUDE.md (non-destructive, shows diff)')
+  .action(() => require('../src/commands/scan')());
+
+program
+  .command('start')
+  .description('Generate session-start prompt and copy to clipboard')
+  .option('--no-copy', 'Print only, do not copy to clipboard')
+  .action((opts) => require('../src/commands/start')(opts));
+
+program
+  .command('end')
+  .description('Generate session-end prompt and copy to clipboard')
+  .option('--no-copy', 'Print only, do not copy to clipboard')
+  .action((opts) => require('../src/commands/end')(opts));
+
+program
+  .command('checkpoint')
+  .description('Generate mid-session checkpoint prompt and copy to clipboard')
+  .option('--no-copy', 'Print only, do not copy to clipboard')
+  .action((opts) => require('../src/commands/checkpoint')(opts));
+
+program
+  .command('status')
+  .description('Show current session state from .claude/state.md')
+  .action(() => require('../src/commands/status')());
+
+program
+  .command('decisions')
+  .description('Show decision log from .claude/decisions.md')
+  .action(() => require('../src/commands/decisions')());
+
+// Show help if no command given
+if (process.argv.length === 2) {
+  program.outputHelp();
+  process.exit(0);
+}
+
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "claude-snap",
+  "version": "1.0.0",
+  "description": "Multi-session Claude context manager for engineers and designers — auto-detects your project, keeps Claude in sync across sessions with zero manual work.",
+  "keywords": [
+    "claude",
+    "claude-ai",
+    "claude-code",
+    "ai",
+    "context-management",
+    "developer-tools",
+    "productivity",
+    "llm",
+    "ai-tools",
+    "session",
+    "context",
+    "workflow",
+    "engineering",
+    "coding-assistant"
+  ],
+  "author": {
+    "name": "Mohammad Ali Shuvo",
+    "email": "shuvo105746@gmail.com",
+    "url": "https://github.com/shuvo18103107"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/shuvo18103107/claude-snap#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shuvo18103107/claude-snap.git"
+  },
+  "bugs": {
+    "url": "https://github.com/shuvo18103107/claude-snap/issues"
+  },
+  "bin": {
+    "claude-snap": "bin/claude-snap.js"
+  },
+  "main": "./src/index.js",
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "commander": "^11.1.0",
+    "inquirer": "^8.2.6"
+  },
+  "scripts": {
+    "dev": "node bin/claude-snap.js"
+  }
+}

package/src/commands/checkpoint.js

@@ -0,0 +1,33 @@
+'use strict';
+
+const chalk = require('chalk');
+const { findProjectRoot, getProjectName } = require('../utils/project');
+const { generateCheckpointPrompt } = require('../templates');
+const { copyToClipboard } = require('../utils/clipboard');
+const ui = require('../utils/ui');
+
+module.exports = async function checkpoint(opts = {}) {
+  const projectRoot = findProjectRoot();
+
+  if (!projectRoot) {
+    ui.error('No Claude context found. Run ' + chalk.cyan('claude-snap init') + ' first.');
+    process.exit(1);
+  }
+
+  const prompt = generateCheckpointPrompt();
+
+  console.log('');
+  console.log(chalk.bold.blue('◆  Checkpoint for:'), chalk.cyan(getProjectName(projectRoot)));
+  console.log('');
+
+  ui.promptBox('CHECKPOINT — Paste this into Claude', prompt);
+
+  if (opts.copy !== false) {
+    const copied = copyToClipboard(prompt);
+    if (copied) {
+      ui.clipboardSuccess();
+    } else {
+      ui.clipboardFail();
+    }
+  }
+};

package/src/commands/decisions.js

@@ -0,0 +1,51 @@
+'use strict';
+
+const chalk = require('chalk');
+const { findProjectRoot, readFile, getProjectName, DECISIONS_FILE } = require('../utils/project');
+const ui = require('../utils/ui');
+
+module.exports = async function decisions() {
+  const projectRoot = findProjectRoot();
+
+  if (!projectRoot) {
+    ui.error('No Claude context found. Run ' + chalk.cyan('claude-snap init') + ' first.');
+    process.exit(1);
+  }
+
+  const content = readFile(projectRoot, DECISIONS_FILE);
+  const projectName = getProjectName(projectRoot);
+
+  if (!content) {
+    ui.error('.claude/decisions.md not found. Run ' + chalk.cyan('claude-snap init'));
+    process.exit(1);
+  }
+
+  console.log('');
+  console.log(chalk.bold.cyan(`● ${projectName} — Decision Log`));
+  console.log('');
+
+  // Parse and display decisions nicely
+  const decisions = content.split(/(?=^## \[)/m).slice(1); // Split on ## [DATE]
+
+  if (!decisions.length) {
+    ui.info('No decisions logged yet.');
+    console.log(chalk.dim('  Add entries to .claude/decisions.md'));
+    return;
+  }
+
+  decisions.slice(0, 10).forEach(block => {
+    const lines = block.split('\n');
+    const titleLine = lines[0]; // ## [DATE] Title
+    const titleMatch = titleLine.match(/^## \[(.+?)\] (.+)/);
+
+    if (titleMatch) {
+      console.log(chalk.bold.yellow(`  [${titleMatch[1]}] ${titleMatch[2]}`));
+      lines.slice(1).forEach(line => {
+        if (line.trim() && !line.startsWith('---')) {
+          console.log(chalk.white('  ' + line));
+        }
+      });
+      console.log('');
+    }
+  });
+};

package/src/commands/end.js

@@ -0,0 +1,36 @@
+'use strict';
+
+const chalk = require('chalk');
+const { findProjectRoot, getProjectName } = require('../utils/project');
+const { generateEndPrompt } = require('../templates');
+const { copyToClipboard } = require('../utils/clipboard');
+const ui = require('../utils/ui');
+
+module.exports = async function end(opts = {}) {
+  const projectRoot = findProjectRoot();
+
+  if (!projectRoot) {
+    ui.error('No Claude context found. Run ' + chalk.cyan('claude-snap init') + ' first.');
+    process.exit(1);
+  }
+
+  const prompt = generateEndPrompt();
+
+  console.log('');
+  console.log(chalk.bold.yellow('⏹  Ending session for:'), chalk.cyan(getProjectName(projectRoot)));
+  console.log('');
+
+  ui.promptBox('SESSION END — Paste this into Claude', prompt);
+
+  if (opts.copy !== false) {
+    const copied = copyToClipboard(prompt);
+    if (copied) {
+      ui.clipboardSuccess();
+    } else {
+      ui.clipboardFail();
+    }
+  }
+
+  console.log(chalk.dim('After Claude updates state.md, your next session will start exactly here.'));
+  console.log('');
+};