CodeGrab ✋

An interactive CLI tool for selecting and bundling code into a single, LLM-ready output file.

❓ Why?

When working with LLMs, sharing code context is essential for getting accurate responses. However, manually copying files or creating code snippets is tedious. CodeGrab streamlines this process by providing a clean TUI (Terminal UI), alongside a versatile CLI (Command-Line Interface). This allows you to easily select files from your project, generate well-formatted output, and copy it directly to your clipboard, ready for LLM processing.

✨ Features

• 🎮 Interactive Mode: Navigate your project structure with vim-like keybindings in a TUI environment
• 💻 CLI Mode: Run non-interactively (-n flag) to grab all valid files based on filters, ideal for scripting
• 🧹 Filtering Options: Respect .gitignore rules, handle hidden files, apply customizable glob patterns, and skip large files
• 🔍 Fuzzy Search: Quickly find files across your project
• ✅ File Selection: Toggle files or entire directories (with child items) for inclusion or exclusion
• 📄 Multiple Output Formats: Generate Markdown, Plain Text, or XML output
• ⏳ Temp File: Generate the output file in your system's temporary directory
• 📋 Clipboard Integration: Copy content or output file directly to your clipboard
• 🌲 Directory Tree View: Display a tree-style view of your project structure
• 🧮 Token Estimation: Get estimated token count for LLM context windows
• 🛡️ Secret Detection & Redaction: Uses gitleaks to identify potential secrets and prevent sharing sensitive information
• 🔗 Dependency Resolution: Automatically include dependencies for Go, JS/TS when using the --deps flag

📦 Installation

Homebrew

brew tap epilande/tap
brew install codegrab

Go Install

go install github.com/epilande/codegrab/cmd/grab@latest

Binary Download

Download the latest release for your platform.

Build from Source

git clone https://github.com/epilande/codegrab
cd codegrab
go build ./cmd/grab

Then move the binary to your PATH.

🚀 Quick Start

1. Go to your project directory and run:

   grab

2. Navigate with arrow keys or h/j/k/l.

3. Select files using the Space or Tab key.

4. Press g to generate output file or y to copy contents to clipboard.

CodeGrab will generate codegrab-output.md in your current working directory (on macOS this file is automatically copied to your clipboard), which you can immediately send to an AI assistant for better context-aware coding assistance.

codegrab-demo.mp4

🎮 Usage

grab [options] [directory]

Arguments

Argument	Description
directory	Optional path to the project directory (default: ".")

Options

Option	Description
-h, --help	Display help information.
-v, --version	Display version information.
-n, --non-interactive	Run in non-interactive mode (selects all valid files respecting filters).
-o, --output <file>	Output file path (default: ./codegrab-output.<format>).
-t, --temp	Use system temporary directory for output file.
-g, --glob <pattern>	Include/exclude files and directories using glob patterns. Can be used multiple times. Prefix with '!' to exclude (e.g., --glob="*.{ts,tsx}" --glob="\!*.spec.ts").
-f, --format <format>	Output format. Available: markdown, text, xml (default: "markdown").
-S, --skip-redaction	Skip automatic secret redaction via gitleaks (Default: false). WARNING: Disabling this may expose sensitive information!
--deps	Automatically include direct dependencies for selected files (Go, JS/TS).
--max-depth <depth>	Maximum depth for dependency resolution (-1 for unlimited, default: 1). Only effective with --deps.
--max-file-size <size>	Maximum file size to include (e.g., "100kb", "2MB"). No limit by default. Files exceeding the specified size will be skipped.
--theme <name>	Set the UI theme. Available: catppuccin-latte, catppuccin-frappe, catppuccin-macchiato, catppuccin-mocha, rose-pine, rose-pine-dawn, rose-pine-moon, dracula, nord. (default: "catppuccin-mocha").
--show-tokens	Show the number of tokens for each file in file tree.
--icons	Display Nerd Font icons.

📖 Examples

1. Run in interactive mode (default):

   grab

2. Grab all files in current directory (non-interactive), skipping files > 50kb:

   grab -n --max-file-size 50kb

3. Grab a specific directory interactively including dependencies:

   grab --deps /path/to/project

4. Grab a specific directory non-interactively including all dependencies (unlimited depth):

   grab -n --deps --max-depth -1 /path/to/project

5. Specify custom output file:

   grab -o output.md /path/to/project

6. Generate XML output:

   grab -f xml -o output.xml /path/to/project

7. Filter files using glob pattern:

   grab -g="*.go" /path/to/project

8. Use multiple glob patterns for include/exclude:

   grab -g="*.{ts,tsx}" -g="\!*.spec.{ts,tsx}"

⌨️ Keyboard Controls

Navigation

Action	Key	Description
Move cursor down	j or ↓	Move the cursor to the next item in the list
Move cursor up	k or ↑	Move the cursor to the previous item in the list
Collapse directory	h or ←	Collapse the currently selected directory
Expand directory	l or →	Expand the currently selected directory
Go to top	H or home	Jump to the first item in the list
Go to bottom	L or end	Jump to the last item in the list
Toggle expand/collapse all	e	Toggle between expanding and collapsing all directories

Search

Action	Key	Description
Start search	/	Begin fuzzy searching for files
Next search result	ctrl+n or ↓	Navigate to the next search result
Previous search result	ctrl+p or ↑	Navigate to the previous search result
Select/deselect item	tab / enter	Toggle selection of the item under cursor in search results
Exit search	esc	Exit search mode and return to normal navigation

Selection & Output

Action	Key	Description
Select/deselect item	tab or space	Toggle selection of the current file or directory
Copy to clipboard	y	Copy the generated output to clipboard
Generate output file	g	Generate the output file with selected content
Toggle Dependency Resolution	D	Enable/disable automatic dependency resolution for Go & JS/TS (Default: Off)
Cycle output formats	F	Cycle through available output formats (markdown, text, xml)
Toggle Secret Redaction	S	Enable/disable automatic secret redaction (Default: On)

View Options

Action	Key	Description
Toggle .gitignore filter	i	Toggle whether to respect .gitignore rules
Toggle hidden files	.	Toggle visibility of hidden files
Refresh files & folders	r	Reload directory tree and reset selections
Toggle help screen	?	Show or hide the help screen
Quit	q / ctrl+c	Exit the application

🔗 Automatic Dependency Resolution

CodeGrab can automatically include dependencies for selected files, making it easier to share complete code snippets with LLMs.

• How it works: When enabled, CodeGrab utilizes tree-sitter to parse selected source files, identifying language-specific dependency declarations (like import or require). It then attempts to resolve these dependencies within your project and automatically includes the necessary files (respecting .gitignore, hidden, size, and glob filters).
• Supported Languages:
  • Go: Resolves relative imports and project-local module imports (if go.mod is present).
  • JavaScript/TypeScript: Resolves relative imports/requires for .js, .jsx, .ts, and .tsx files, including directory index files.
• Enabling:
  • Interactive Mode: Press D to toggle dependency resolution on/off. A 🔗 Deps indicator will appear in the footer when active. Files added as dependencies will be marked with [dep].
  • Non-Interactive Mode: Use the --deps flag.
• Controlling Depth: The --max-depth flag controls how many levels of dependencies are included:
  • 1 (Default): Only includes files directly imported by your initially selected files.
  • N: Includes dependencies up to N levels deep.
  • -1: Includes all dependencies recursively (unlimited depth).

🛡️ Secret Detection & Redaction

CodeGrab automatically scans the content of selected files for potential secrets using gitleaks with its default rules. This helps prevent accidental exposure of sensitive credentials like API keys, private tokens, and passwords.

• Enabled by Default: Secret scanning and redaction are active unless explicitly disabled.
• Redaction Format: Detected secrets are replaced with [REDACTED_RuleID], where RuleID indicates the type of secret found (e.g., [REDACTED_generic-api-key]).
• Skipping Redaction: You can disable this feature using the -S / --skip-redaction flag when running the command, or by pressing S in the interactive TUI. Use this option with caution, as it may expose sensitive information in the output.

🎨 Themes

CodeGrab comes with several built-in themes:

• Catppuccin (Latte, Frappe, Macchiato, Mocha)
• Dracula
• Nord
• Rosé Pine (Main, Moon, Dawn)

Select a theme using the --theme flag:

grab --theme dracula

📄 Output Formats

Markdown (Default)

grab --format markdown

Example Output

# Project Structure

```
./
└── internal/
    ├── filesystem/
    │   ├── filter.go
    │   ├── gitignore.go
    │   └── walker.go
    └── generator/
        └── formats/
            ├── markdown.go
            └── registry.go
```

# Project Files

## File: `internal/filesystem/filter.go`

```go
package filesystem

import (
    "path/filepath"
    "strings"
)

// ... rest of the file content
```

Plain Text

grab --format text

Example Output

=============================================================
PROJECT STRUCTURE
=============================================================

./
└── internal/
    ├── filesystem/
    │   ├── filter.go
    │   ├── gitignore.go
    │   └── walker.go
    └── generator/
        └── formats/
            ├── markdown.go
            └── registry.go


=============================================================
PROJECT FILES
=============================================================
=============================================================
FILE: internal/filesystem/filter.go
=============================================================

package filesystem

import (
    "path/filepath"
    "strings"
)

// ... rest of the file content

XML

grab --format xml

Example Output

<?xml version="1.0" encoding="UTF-8"?>
<project>
  <filesystem>
    <directory name=".">
      <directory name="internal">
        <directory name="filesystem">
          <file name="filter.go"/>
          <file name="gitignore.go"/>
          <file name="walker.go"/>
        </directory>
        <directory name="generator">
          <directory name="formats">
            <file name="markdown.go"/>
            <file name="registry.go"/>
          </directory>
        </directory>
      </directory>
    </directory>
  </filesystem>
  <files>
    <file path="internal/filesystem/filter.go" language="go"><![CDATA[
package filesystem

import (
    "path/filepath"
    "strings"
)

// ... rest of the file content
]]></file>
    <!-- Additional files -->
  </files>
</project>