Skip to content

Commit 45bdb31

Browse files
epilandeepilande
committed
🎉 Initial commit
0 parents  commit 45bdb31

44 files changed

Lines changed: 5385 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
.DS_Store
2+
3+
*.log
4+
bin/

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 Emmanuel Pilande
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 310 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,310 @@
1+
<div align="center">
2+
<h1>CodeGrab ✋</h1>
3+
</div>
4+
5+
<p align="center">
6+
<strong>An interactive CLI tool for selecting and bundling code into a single, LLM-ready output file.</strong>
7+
</p>
8+
9+
## ❓ Why?
10+
11+
When working with LLMs, sharing code context is essential for getting accurate responses. However,
12+
manually copying files or creating code snippets is tedious. CodeGrab streamlines this process by
13+
providing a clean Terminal UI (TUI), alongside a versatile command-line interface (CLI). This allows
14+
you to easily select files from your project, generate well-formatted output, and copy it directly
15+
to your clipboard, ready for LLM processing.
16+
17+
## ✨ Features
18+
19+
- 🎮 **Interactive Mode**: Navigate your project structure with vim-like keybindings in a
20+
TUI environment
21+
- 🧹 **Filtering Options**: Respect `.gitignore` rules, handle hidden files, and apply customizable glob
22+
patterns
23+
- 🔍 **Fuzzy Search**: Quickly find files across your project
24+
- ✅ **File Selection**: Toggle files or entire directories (with child items) for inclusion or exclusion
25+
- 📄 **Multiple Output Formats**: Generate Markdown, Plain Text, or XML output
26+
- ⏳ **Temp File**: Generate the output file in your system's temporary directory
27+
- 📋 **Clipboard Integration**: Copy content or output file directly to your clipboard
28+
- 🌲 **Directory Tree View**: Display a tree-style view of your project structure
29+
- 🧮 **Token Estimation**: Get estimated token count for LLM context windows
30+
31+
## 📦 Installation
32+
33+
```sh
34+
go install github.com/epilande/codegrab/cmd/grab@latest
35+
```
36+
37+
Or build from source:
38+
39+
```sh
40+
git clone https://github.com/epilande/codegrab
41+
cd codegrab
42+
go build ./cmd/grab
43+
```
44+
45+
Then move the binary to your `PATH`
46+
47+
## 🚀 Quick Start
48+
49+
1. Go to your project directory and run:
50+
51+
```sh
52+
grab
53+
```
54+
55+
2. Navigate with <kbd>h</kbd>/<kbd>j</kbd>/<kbd>k</kbd>/<kbd>l</kbd>
56+
3. Select files using the <kbd>Space</kbd> or <kbd>Tab</kbd> key
57+
4. Press <kbd>g</kbd> to generate output file or <kbd>y</kbd> to copy contents to clipboard
58+
59+
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.
60+
61+
## 🎮 Usage
62+
63+
```sh
64+
grab [options] [directory]
65+
```
66+
67+
### Arguments
68+
69+
| Argument | Description |
70+
| :---------- | :----------------------------------------------------------------- |
71+
| `directory` | Path to the project directory (default: current working directory) |
72+
73+
### Options
74+
75+
| Option | Description |
76+
| :---------------------- | :-------------------------------------------------------------------------------------- |
77+
| `-h, --help` | Display help information |
78+
| `-n, --non-interactive` | Run in non-interactive mode (grabs all files) |
79+
| `-o, --output file` | Output file path (default: `./codegrab-output.<format>`) |
80+
| `-t, --temp` | Use system temporary directory for output file |
81+
| `-g, --glob pattern` | Include/exclude files and directories (e.g., `--glob="*.{ts,tsx}" --glob="!*.spec.ts"`) |
82+
| `-f, --format format` | Output format (available: markdown, text, xml) |
83+
| `--theme` | Set the UI theme |
84+
85+
### 📖 Examples
86+
87+
1. Run in interactive mode (default):
88+
89+
```bash
90+
grab
91+
```
92+
93+
2. Grab all files in current directory (non-interactive):
94+
95+
```bash
96+
grab -n
97+
```
98+
99+
3. Grab a specific directory:
100+
101+
```bash
102+
grab /path/to/project
103+
```
104+
105+
4. Specify custom output file:
106+
107+
```bash
108+
grab -o output.md /path/to/project
109+
```
110+
111+
5. Generate XML output:
112+
113+
```bash
114+
grab -f xml -o output.xml /path/to/project
115+
```
116+
117+
6. Filter files using glob pattern:
118+
119+
```bash
120+
grab -g="*.go" /path/to/project
121+
```
122+
123+
7. Use multiple glob patterns for include/exclude:
124+
```bash
125+
grab -g="*.{ts,tsx}" -g="!*.spec.{ts,tsx}"
126+
```
127+
128+
## ⌨️ Keyboard Controls
129+
130+
### Navigation
131+
132+
| Action | Key | Description |
133+
| :------------------------- | :------------------------------ | :------------------------------------------------------ |
134+
| Move cursor down | <kbd>j</kbd> or <kbd>↓</kbd> | Move the cursor to the next item in the list |
135+
| Move cursor up | <kbd>k</kbd> or <kbd>↑</kbd> | Move the cursor to the previous item in the list |
136+
| Collapse directory | <kbd>h</kbd> or <kbd>←</kbd> | Collapse the currently selected directory |
137+
| Expand directory | <kbd>l</kbd> or <kbd>→</kbd> | Expand the currently selected directory |
138+
| Go to top | <kbd>H</kbd> or <kbd>home</kbd> | Jump to the first item in the list |
139+
| Go to bottom | <kbd>L</kbd> or <kbd>end</kbd> | Jump to the last item in the list |
140+
| Toggle expand/collapse all | <kbd>e</kbd> | Toggle between expanding and collapsing all directories |
141+
142+
### Search
143+
144+
| Action | Key | Description |
145+
| :--------------------- | :-------------------------------- | :----------------------------------------------------- |
146+
| Start search | <kbd>/</kbd> | Begin searching for files |
147+
| Next search result | <kbd>ctrl+n</kbd> or <kbd>↓</kbd> | Navigate to the next search result |
148+
| Previous search result | <kbd>ctrl+p</kbd> or <kbd>↑</kbd> | Navigate to the previous search result |
149+
| Select/deselect file | <kbd>tab</kbd> | Toggle selection of the current file in search results |
150+
| Exit search | <kbd>esc</kbd> | Exit search mode and return to normal navigation |
151+
152+
### Selection & Output
153+
154+
| Action | Key | Description |
155+
| :------------------- | :--------------------------------- | :----------------------------------------------------------- |
156+
| Select/deselect item | <kbd>tab</kbd> or <kbd>space</kbd> | Toggle selection of the current file or directory |
157+
| Copy to clipboard | <kbd>y</kbd> | Copy the generated output to clipboard |
158+
| Generate output file | <kbd>g</kbd> | Generate the output file with selected content |
159+
| Cycle output formats | <kbd>F</kbd> | Cycle through available output formats (markdown, text, xml) |
160+
161+
### View Options
162+
163+
| Action | Key | Description |
164+
| :------------------------- | :----------- | :------------------------------------------------ |
165+
| Toggle `.gitignore` filter | <kbd>i</kbd> | Toggle whether to respect `.gitignore` rules |
166+
| Toggle hidden files | <kbd>.</kbd> | Toggle visibility of hidden files and directories |
167+
| Toggle help screen | <kbd>?</kbd> | Show or hide the help screen |
168+
| Quit | <kbd>q</kbd> | Exit the application |
169+
170+
## 🎨 Themes
171+
172+
CodeGrab comes with several built-in themes:
173+
174+
- Catppuccin (Latte, Frappe, Macchiato, Mocha)
175+
- Dracula
176+
- Nord
177+
178+
Select a theme using the `--theme` flag:
179+
180+
```sh
181+
grab --theme=dracula
182+
```
183+
184+
## 📄 Output Formats
185+
186+
### Markdown (Default)
187+
188+
```sh
189+
grab --format markdown
190+
```
191+
192+
#### Example Output
193+
194+
````md
195+
# Project Structure
196+
197+
```
198+
./
199+
└── internal/
200+
├── filesystem/
201+
│ ├── filter.go
202+
│ ├── gitignore.go
203+
│ └── walker.go
204+
└── generator/
205+
└── formats/
206+
├── markdown.go
207+
└── registry.go
208+
```
209+
210+
# Project Files
211+
212+
## File: `internal/filesystem/filter.go`
213+
214+
```go
215+
package filesystem
216+
217+
import (
218+
"path/filepath"
219+
"strings"
220+
)
221+
222+
// ... rest of the file content
223+
```
224+
````
225+
226+
### Plain Text
227+
228+
```sh
229+
grab --format text
230+
```
231+
232+
#### Example Output
233+
234+
```
235+
=============================================================
236+
PROJECT STRUCTURE
237+
=============================================================
238+
239+
./
240+
└── internal/
241+
├── filesystem/
242+
│ ├── filter.go
243+
│ ├── gitignore.go
244+
│ └── walker.go
245+
└── generator/
246+
└── formats/
247+
├── markdown.go
248+
└── registry.go
249+
250+
251+
=============================================================
252+
PROJECT FILES
253+
=============================================================
254+
=============================================================
255+
FILE: internal/filesystem/filter.go
256+
=============================================================
257+
258+
package filesystem
259+
260+
import (
261+
"path/filepath"
262+
"strings"
263+
)
264+
265+
// ... rest of the file content
266+
```
267+
268+
### XML
269+
270+
```sh
271+
grab --format xml
272+
```
273+
274+
#### Example Output
275+
276+
```xml
277+
<?xml version="1.0" encoding="UTF-8"?>
278+
<project>
279+
<filesystem>
280+
<directory name=".">
281+
<directory name="internal">
282+
<directory name="filesystem">
283+
<file name="filter.go"/>
284+
<file name="gitignore.go"/>
285+
<file name="walker.go"/>
286+
</directory>
287+
<directory name="generator">
288+
<directory name="formats">
289+
<file name="markdown.go"/>
290+
<file name="registry.go"/>
291+
</directory>
292+
</directory>
293+
</directory>
294+
</directory>
295+
</filesystem>
296+
<files>
297+
<file path="internal/filesystem/filter.go" language="go"><![CDATA[
298+
package filesystem
299+
300+
import (
301+
"path/filepath"
302+
"strings"
303+
)
304+
305+
// ... rest of the file content
306+
]]></file>
307+
<!-- Additional files -->
308+
</files>
309+
</project>
310+
```

0 commit comments

Comments
 (0)