eckSnapshot

A lightweight, platform-independent CLI for creating focused, AI-ready project snapshots.

eckSnapshot is a powerful command-line tool designed to solve a critical problem in AI-assisted development: providing clear, complete, and focused context to Large Language Models (LLMs). It allows you to package an entire project codebase—or just specific parts of it—into a single, clean text file.

This tool is built for a modern workflow where you act as the architect, guiding the overall strategy, while AI agents handle the detailed implementation.

The Core Workflow

eckSnapshot is designed to support a two-part AI workflow for maximum efficiency and quality:

1. The Architect LLM (Gemini, GPT-4, Grok): A model with a large context window. You provide it with a snapshot of your project, and it analyzes the codebase to create a high-level plan for new features or refactoring.
2. The Coder LLM (Claude Code, OpenAI Codex): A model specialized in writing and modifying code. It takes the detailed instructions generated by the Architect and performs the hands-on coding tasks.

Requirements

1. Node.js (v18.x or higher).
2. An AI Assistant CLI (at least one):
   • Claude: An active Claude Pro subscription and the claude-code CLI installed.
   • OpenAI: An active ChatGPT Plus/Pro subscription and the @openai/codex CLI installed (npm install -g @openai/codex).

Installation

Install eckSnapshot globally on your system using npm:

npm install -g @xelth/eck-snapshot

Once installed, you can run the tool using the eck-snapshot command from any directory.

A Step-by-Step Guide to Using eckSnapshot

Here’s the most common workflow, from creating a full snapshot to focusing on specific features.

Step 1: Create a Full Project Snapshot

This is your primary command. It scans your project and packs all relevant code into a single file.

Usage:

dimi@xelth:/mnt/c/Users/xelth/myProject$ eck-snapshot

• What it does: Creates a file like myProject_snapshot_... .md in the .eck/snapshots/ directory. This file contains your project's directory structure and the complete code. You can now pass this file to your Architect LLM for analysis.

Step 2: Handle Large Projects with Auto-Profiling

If your project is too large for an LLM's context window, profile-detect can automatically slice it into logical parts (profiles) using AI.

Usage:

dimi@xelth:/mnt/c/Users/xelth/myProject$ eck-snapshot profile-detect

• Output Example:

  ✨ Detected Profiles:
  ---------------------------
    - cli
    - services
    - core
    - templates
    - docs
    - config

• What it does: Analyzes your project and saves these logical groupings into a .eck/profiles.json file, which you can use in the next step.

Step 3: Use Profiles to Create Focused Snapshots

The --profile option gives you powerful control over what goes into a snapshot. You can combine profiles, exclude files, and even use ad-hoc patterns.

Example 1: Combine and Exclude Profiles

Create a snapshot of the core logic, services, and CLI, but exclude all documentation and configuration files.

eck-snapshot --profile "core,services,cli,-docs,-config"

Example 2: Use Ad-Hoc Glob Patterns

Include all .js files in the src directory but exclude all test files, without using a pre-defined profile.

eck-snapshot --profile "src/**/*.js,-**/*.test.js"

Note: Quotes are required when using complex patterns with wildcards (*) or commas.

Step 4: Intelligently Prune a Snapshot

If a snapshot is still too large, prune uses AI to shrink it to a target size, keeping only the most important files for understanding the code.

Usage:

eck-snapshot prune myProject_snapshot.md --target-size 500KB

Step 5 (Alternative): Truncate Files by Line Count

A faster, non-AI method to reduce snapshot size. This command keeps only the top N lines of each file, which is useful for a high-level architectural overview.

Usage:

eck-snapshot --max-lines-per-file 200

Auxiliary Commands

• restore <snapshot_file>: Recreates a project's file structure from a snapshot.
• generate-profile-guide: Creates a guide for manual profile creation. Use this if profile-detect fails on very large projects, as it allows you to use an LLM with a larger context window (e.g., a web UI).
• detect: Shows how eckSnapshot has identified your project type and what default file filters are being applied.
• ask-gpt / ask-claude: Directly delegate a task to your configured AI coder agents from the command line.
• setup-gemini: A utility to automatically configure integration with the gemini-cli.

For a full list of commands and options, run eck-snapshot --help.

License

This project is licensed under the MIT License.