Code Sync 🌊

A production-grade CLI tool that flattens your local codebase, directories, and live uncommitted Git changes into a single, token-optimized Markdown file. Built for developers who need to seamlessly pass high-fidelity context between different AI models (like Claude, ChatGPT, and Gemini) without breaking their development velocity.

Features

• Targeted Folder Extraction: Avoid context-window bloat by targeting specific folders (e.g., frontend components or backend routes) rather than the whole project.
• Token Estimation Heuristic: Instant, zero-dependency token count estimation (~4 characters per token) to prevent "Context Window Exceeded" errors before you copy-paste.
• Custom AI Rules (.codesyncprompt): Automatically inject your local project-specific coding standards, style guides, or architectural rules at the top of the context payload.
• Agentic Watch Mode (--watch): Actively monitors your workspace for file saves and background modifications, silently auto-updating your clipboard and markdown file in real-time.
• Smart Extension Filtering & .gitignore Parsing: Dynamically respects local .gitignore specifications and skips heavy binaries or media files.

Installation

Install globally via the npm registry:

npm install -g vibecode-sync

Usage

1. Standard Full Scan

Run the command in your project's root folder to compile the entire directory tree, code files, and uncommitted Git changes:

code-sync

2. Targeted Extraction

Pass a path to focus exclusively on a single subdirectory or module:

code-sync ./client/src/components

3. Agentic Watch Mode

Keep the CLI running to continuously watch for file updates. Every time you save a file, your clipboard and reference file refresh instantly:

code-sync --watch

Combined with targeting: code-sync ./server --watch

Advanced Setup

Custom AI System Instructions

To pin specific architectural rules to your AI handoffs, create a file named .codesyncprompt in your project's root directory:

# .codesyncprompt example
- You are an expert engineer working on a MERN stack application.
- Prioritize clean architecture, functional React components, and semantic HTML.
- Always use Tailwind CSS for layout configurations.
- Provide comprehensive error logging blocks for async operations.

When you execute code-sync, these instructions are automatically prioritized at the very top of the generated context layout.

Output Architecture

The tool generates a single compilation file named code-context.md in your execution directory and copies the exact text to your clipboard. The payload is organized into a clean markdown structure:

| Section | Content | Purpose | | --- | --- | --- | | System Instructions | Contents of .codesyncprompt | Forces model alignment with your stack | | Directory Structure | Filtered text tree visualizer | Gives the LLM mental tracking of folder locations | | Recent Uncommitted Changes | Combined git diff & git diff --cached | Alerts the AI to your exact active task state | | Codebase Contents | Combined files wrapped in XML tracking tags | Structured source data for parsing and code analysis |

License

MIT