claude-code-smart-fork 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial release of Claude Code Smart Fork
+- Semantic search for sessions across projects
+- Support for multiple embedding providers (local, OpenAI, Ollama)
+- Support for multiple vector stores (local JSON, ChromaDB, Pinecone)
+- CLI commands: `detect`, `fork-to`, `index`, `list`, `status`, `config`
+- Claude Code slash command integration
+- Session indexing and management
+- Cross-project search capability
+- Local data storage with privacy-focused design
+- Configuration management
+- Export and import session functionality
+
+## [1.0.0] - 2026-03-01
+
+### Added
+- First stable release
+- Complete documentation (English and Chinese)
+- GitHub Actions CI/CD workflow
+- Issue and PR templates
+- Contributing guidelines
+- Code of conduct
+- Security policy
+- MIT License
+
+[Unreleased]: https://github.com/yourusername/claude-code-smart-fork/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/yourusername/claude-code-smart-fork/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Claude Code Smart Fork Contributors
+
+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,317 @@
+# Claude Code Smart Fork
+
+🔀 **Smart session forking for Claude Code** - Find and resume relevant historical sessions across all your projects using AI-powered semantic search.
+
+[![npm version](https://badge.fury.io/js/claude-code-smart-fork.svg)](https://www.npmjs.com/package/claude-code-smart-fork)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js CI](https://github.com/yourusername/claude-code-smart-fork/actions/workflows/ci.yml/badge.svg)](https://github.com/yourusername/claude-code-smart-fork/actions)
+
+## 🌟 Features
+
+- 🔍 **Semantic Search** - Find relevant sessions based on meaning, not just keywords
+- 🌐 **Cross-Project** - Search across all your projects, not just the current one
+- 🤖 **AI-Powered** - Uses embeddings to understand context and intent
+- ⚡ **Fast** - Local vector storage for instant results
+- 🔒 **Private** - All data stays on your machine by default
+- 🎯 **Easy Integration** - Works seamlessly with Claude Code as slash commands
+
+## 📦 Installation
+
+```bash
+# Install globally
+npm install -g claude-code-smart-fork
+
+# Or use npx (no installation needed)
+npx claude-code-smart-fork
+```
+
+## 🚀 Quick Start
+
+### 1. Index Your Current Session
+
+```bash
+smart-fork index --summary "Implementing user authentication"
+```
+
+### 2. Later, Find Relevant Sessions
+
+```bash
+smart-fork detect
+```
+
+### 3. Switch to a Session
+
+```bash
+smart-fork fork-to <session-id>
+```
+
+## 🛠️ Usage
+
+### CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `smart-fork index` | Index current session for future searching |
+| `smart-fork detect` | Find relevant historical sessions |
+| `smart-fork detect --all` | Search across all projects |
+| `smart-fork list` | List all indexed sessions |
+| `smart-fork status` | Show current status and suggestions |
+| `smart-fork export <id>` | Export a session to JSON |
+
+### Claude Code Integration
+
+After installation, these slash commands are available in Claude Code:
+
+```
+/index-session    - Index current session
+/fork-detect      - Find relevant sessions
+/fork-to <id>     - Switch to a session
+/list-sessions    - List all sessions
+/fork-status      - Show status and suggestions
+```
+
+## ⚙️ Configuration
+
+Create `~/.smart-fork/config.json`:
+
+```json
+{
+  "embedding": {
+    "provider": "local",
+    "model": "all-MiniLM-L6-v2",
+    "dimension": 384
+  },
+  "vectorStore": {
+    "provider": "local",
+    "collectionName": "smart-fork-sessions"
+  },
+  "storage": {
+    "sessionsDir": "~/.smart-fork/sessions",
+    "indexPath": "~/.smart-fork/index.json"
+  }
+}
+```
+
+### Embedding Providers
+
+#### Local (Default) - No API key needed
+```json
+{
+  "embedding": {
+    "provider": "local",
+    "model": "all-MiniLM-L6-v2"
+  }
+}
+```
+
+#### OpenAI
+```json
+{
+  "embedding": {
+    "provider": "openai",
+    "model": "text-embedding-3-small"
+  }
+}
+```
+Requires `OPENAI_API_KEY` environment variable.
+
+#### Ollama
+```json
+{
+  "embedding": {
+    "provider": "ollama",
+    "model": "nomic-embed-text"
+  }
+}
+```
+Requires a running Ollama server.
+
+## 💡 Usage Examples
+
+### Example 1: Index a Session with Conversation History
+
+```bash
+# Create a conversation history file
+cat > conversation.json << 'EOF'
+[
+  {
+    "id": "turn-1",
+    "timestamp": 1709400000000,
+    "userMessage": {
+      "content": "How do I implement user authentication?",
+      "metadata": { "files": ["auth.js"] }
+    },
+    "assistantMessage": {
+      "content": "I recommend using JWT + OAuth2. JWT is great for stateless auth, OAuth2 for third-party login.",
+      "toolCalls": [{"id": "1", "type": "search", "parameters": {"query": "JWT best practices"}}]
+    }
+  },
+  {
+    "id": "turn-2",
+    "timestamp": 1709400100000,
+    "userMessage": {
+      "content": "Show me code examples"
+    },
+    "assistantMessage": {
+      "content": "Here's a Node.js example using jsonwebtoken...",
+      "toolCalls": [
+        {"id": "2", "type": "read_file", "parameters": {"path": "examples/auth.js"}},
+        {"id": "3", "type": "edit_file", "parameters": {"path": "src/auth.js"}}
+      ]
+    }
+  }
+]
+EOF
+
+# Index the session
+smart-fork index --conversation conversation.json --summary "User authentication with JWT" --tags "auth,jwt,nodejs"
+
+# Output:
+# ✓ Session indexed successfully!
+# Session ID: 096549e9-13bd-45bd-9f6c-659d55c78b35
+# Conversation turns: 2
+# Total messages: 4
+```
+
+### Example 2: Find and Resume a Session
+
+```bash
+# Search for relevant sessions
+smart-fork detect --query "authentication JWT code examples"
+
+# Output:
+# ✓ Found 1 relevant session(s):
+#
+# 1. my-first-app
+#    Path: D:\\claudecode\\MyAICodes\\my-first-app
+#    Relevance: 85%
+#    Summary: User authentication with JWT
+#    Last updated: 2026/3/2
+
+# Fork to the session
+smart-fork fork-to 096549e9-13bd-45bd-9f6c-659d55c78b35
+
+# Output:
+# 💬 Conversation History:
+# ────────────────────────────────────────────────────────────
+# [1] 👤 User:
+# How do I implement user authentication?
+#     🤖 Assistant:
+# I recommend using JWT + OAuth2...
+#     🔧 Tool calls: search
+# ────────────────────────────────────────────────────────────
+# [2] 👤 User:
+# Show me code examples
+#     🤖 Assistant:
+# Here's a Node.js example...
+#     🔧 Tool calls: read_file, edit_file
+# ────────────────────────────────────────────────────────────
+# ✨ Total turns: 2
+# 💡 You can continue the conversation from here.
+```
+
+### Example 3: Cross-Project Search
+
+```bash
+# Index sessions in multiple projects
+# Project A: API Gateway
+cd ~/projects/api-gateway
+smart-fork index --summary "Implementing rate limiting middleware"
+
+# Project B: Frontend
+cd ~/projects/frontend
+smart-fork index --summary "Setting up React authentication context"
+
+# Search across all projects
+cd ~/projects/api-gateway
+smart-fork detect --all --query "authentication middleware"
+
+# Results will show relevant sessions from both projects!
+```
+
+### Example 4: Using with Claude Code Slash Commands
+
+```bash
+# In Claude Code, use slash commands:
+
+# Index current session
+/index-session Implementing user authentication --tags auth,jwt
+
+# Later, find relevant sessions
+/fork-detect
+
+# Fork to a specific session
+/fork-to 096549e9-13bd-45bd-9f6c-659d55c78b35
+
+# List all sessions
+/list-sessions
+```
+
+## 📁 Data Storage
+
+All data is stored locally in `~/.smart-fork/`:
+
+```
+~/.smart-fork/
+├── sessions/          # Full session data (JSON)
+├── index.json         # Session index with embeddings
+└── config.json        # User configuration
+```
+
+## 🔧 Development
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/claude-code-smart-fork.git
+cd claude-code-smart-fork
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run tests
+npm test
+
+# Watch mode for development
+npm run dev
+```
+
+## 📚 API Usage
+
+```typescript
+import { ForkDetector, SessionManager } from 'claude-code-smart-fork';
+
+const detector = new ForkDetector();
+await detector.initialize();
+
+// Find relevant sessions
+const results = await detector.findRelevantSessions({
+  text: "How to implement authentication?",
+  limit: 5
+});
+
+// Switch to a session
+const sessionManager = new SessionManager();
+await sessionManager.forkToSession(results[0].session.id);
+```
+
+## 🤝 Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- Inspired by the need for better session management in Claude Code
+- Thanks to the open-source community for the amazing tools
+
+## 📮 Support
+
+- 🐛 [Report a bug](https://github.com/yourusername/claude-code-smart-fork/issues)
+- 💡 [Request a feature](https://github.com/yourusername/claude-code-smart-fork/issues)
+- 📧 Contact: your-email@example.com

package/README.zh-CN.md

@@ -0,0 +1,45 @@
+# Claude Code Smart Fork 中文文档
+
+🔀 **Claude Code 智能会话分支** - 使用 AI 驱动的语义搜索，在所有项目中查找并恢复相关的历史会话。
+
+## 功能特性
+
+- 🔍 **语义搜索** - 基于含义而非关键词查找相关会话
+- 🌐 **跨项目** - 在所有项目中搜索，不限于当前项目
+- 🤖 **AI 驱动** - 使用嵌入向量理解上下文和意图
+- ⚡ **快速** - 本地向量存储，即时返回结果
+- 🔒 **隐私** - 默认所有数据保存在本地
+
+## 快速开始
+
+```bash
+# 安装
+npm install -g claude-code-smart-fork
+
+# 索引当前会话
+smart-fork index --summary "实现用户认证功能"
+
+# 查找相关会话
+smart-fork detect
+
+# 跨所有项目搜索
+smart-fork detect --all
+```
+
+## Claude Code 集成
+
+安装后，在 Claude Code 中可以使用以下命令：
+
+```
+/index-session    - 索引当前会话
+/fork-detect      - 查找相关会话
+/fork-to <id>     - 切换到指定会话
+/list-sessions    - 列出所有会话
+/fork-status      - 显示状态和建议
+```
+
+## 更多文档
+
+- [英文 README](./README.md)
+- [贡献指南](./CONTRIBUTING.md)
+- [更新日志](./CHANGELOG.md)

package/dist/cli/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * CLI Tool for Smart Forking
+ * Provides /fork-detect command and other utilities
+ */
+import { Command } from 'commander';
+declare const program: Command;
+export { program };
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOpC,QAAA,MAAM,OAAO,SAAgB,CAAC;AAmW9B,OAAO,EAAE,OAAO,EAAE,CAAC"}