The screenshot is a pointer, not the context.
Draw a box around the files visible in your editor. snap-extract uses those names to find the real directories on disk, reads their authoritative contents, and puts a clean, labelled context bundle on your clipboard—ready to paste into any AI chat.
Super+Shift+E → choose a project → draw around the file tree → paste.
No opening files one by one. No copying fragments. No trusting OCR to reproduce your code. Everything runs locally: no cloud calls and no API keys.
Try it directly from the shell:
snap-extract.sh --screenshot --root ~/projects/my-app --ext ".ts,.md"Or copy a folder without taking a screenshot:
OCR on a file sidebar is unreliable — names get truncated with ellipses, narrow fonts get mangled, files scroll out of view. So snap-extract doesn't trust it.
It only needs one filename to be read correctly. The moment a name resolves
to a real file under --root, the script discards the OCR list entirely and
re-reads that file's directory from disk, which is authoritative.
That inverts the problem. The screenshot stops being a file list and becomes a pointer to a folder. Truncated names, misread characters and off-screen files all stop mattering.
Every recognised name votes, so a screenshot spanning several directories yields the union of them — not whichever one happened to sort first.
git clone https://github.com/ghostON3/snap-extract
cd snap-extract && chmod +x snap-extract.shDependencies:
| Need | Wayland | X11 |
|---|---|---|
| screenshot | grim + slurp |
scrot |
| clipboard | wl-clipboard (wl-copy) |
xclip |
| OCR | tesseract + a language pack |
|
| preprocessing | imagemagick — strongly recommended, see Backends |
|
| runtime | bash >= 4, python3 (vision backend only) |
Arch: pacman -S grim slurp wl-clipboard tesseract tesseract-data-eng imagemagick
Keep each command on one line. Some terminals mangle a pasted multi-line command with backslash continuations — the continuation arrives as a literal character and the script sees it as an unknown argument.
snap-extract.sh --help prints the full option list.
The flagship flow. Point at what's on screen instead of typing globs.
snap-extract.sh --screenshot --root ~/projects/my-app --ext ".ts,.tsx"The cursor becomes a crosshair. Drag a rectangle over your editor's file
tree, or click once on a window to select the whole thing. Escape cancels.
OCR reads the visible names; the moment one resolves on disk, that entire
directory is read instead. Then paste with Ctrl+V.
Add --debug 2>/tmp/snap.log when it misbehaves — the log shows exactly what
OCR read and which directories it promoted to.
No screenshot involved. This is the flow you want for "give the model my repo".
snap-extract.sh --folder ~/projects/my-app/packages -r --ext ".ts,.json"Without -r you get only the immediate children of that directory — which for
a packages/ folder containing nothing but subdirectories means no files at all.
For a folder of notes or chapters, where recursion would pull in noise.
snap-extract.sh --folder ~/notes --ext .mdWhen you already know what you want. Names resolve under --root, so you don't
have to type full paths.
snap-extract.sh --paths "index.ts,config.ts" --root ~/projects/my-appNothing touches the clipboard with --output stdout. Useful for checking the
size before pasting 400 KB into a chat box.
snap-extract.sh --folder ~/projects/my-app -r --ext .ts --output stdout | head -40--output also takes a path, for building a context file you reuse.
snap-extract.sh --folder ~/notes -r --output /tmp/context.mdSkips the capture step. Handy for iterating on --ext or --exclude without
re-dragging, and for debugging OCR on a saved screenshot.
snap-extract.sh --image /tmp/shot.png --root ~/projects/my-app --ext .tsAn alternative to OCR when you need a model to interpret the screenshot rather than transcribe it. Requires a local Ollama; slow on CPU.
snap-extract.sh --image /tmp/shot.png --root ~/proj --backend vision--exclude "*.test.ts,*.snap" # drop matches (glob; path or basename)
--include "*.ts" # keep only matches
--prune "node_modules,dist" # directories to skip while recursing
--max-depth 3 # how deep -r goesExtension matching is case-insensitive, so .md also includes files such as
README.MD. For safety, add sensitive formats such as .env only when you
explicitly intend to place their contents on the clipboard.
| Flag | Default | Meaning |
|---|---|---|
--screenshot / --image F / --folder D / --paths "a,b" |
— | input mode (pick one) |
--root DIR |
$PWD |
where filenames are resolved |
--ext ".ts,.md" |
.md |
extensions to include |
-r, --recursive |
off | walk the whole tree, not just immediate children |
--max-depth N |
8 |
depth limit when recursing |
--prune "a,b" |
see below | directory names to skip when recursing |
--exclude "*.test.ts" |
— | glob filter; matches full path or basename |
--include "*.ts" |
— | keep only matches |
--output |
clipboard |
clipboard, stdout, or a file path |
--backend |
tesseract |
tesseract (fast) or vision (Ollama) |
--debug |
off | log identification and promotion decisions to stderr |
Pruned by default when recursing: .git, node_modules, dist, build,
out, .next, .turbo, .svelte-kit, coverage, __pycache__, .venv,
venv, target, vendor.
-
tesseract(default) — pure CPU OCR, ~1–4 s. Pulls tokens matching your--extlist out of the OCR'd text. Misses plenty; auto-promotion covers it.The image is normalised first, which matters more than it sounds. Tesseract expects large dark-on-light text; an editor sidebar on a dark theme is ~13px light-on-dark, and fed raw it drops the dot before the extension (
contract.ts→contractts) so the extension filter rejects everything. snap-extract converts to grayscale, inverts when the background is dark, upscales 4× and sharpens before running OCR in single-block mode. Install ImageMagick — without it accuracy on real sidebars collapses. -
vision—qwen3-vl:8bvia a local Ollama. 2–4 s on GPU, 60–300 s on CPU. Only worth it for semantic instructions. Prompt inprompts/identify.txt.
A leader key opens a project menu; one more key picks the project. Register the projects you actually work in and each gets a two-key chord.
mkdir -p ~/.config/snap-extract
cp contrib/hypr/projects.conf.example ~/.config/snap-extract/projects.conf
$EDITOR ~/.config/snap-extract/projects.conf
contrib/hypr/snapx-keybinds.shThe registry is one line per project:
# key | label | path | extensions [| extra flags]
s | strojx | ~/projects/strojx | .ts,.tsx,.json,.md | --exclude "*.test.ts"
e | elo v2 | ~/projects/elo-evolution-v2 | .ts,.tsx,.md
n | notes | ~/notes | .md
The generator writes ~/.config/hypr/conf.d/snap-extract.conf. Add
source = ~/.config/hypr/conf.d/snap-extract.conf to hyprland.conf once,
then hyprctl reload. Re-run the generator after editing the registry — the
output is overwritten every time, so edit the registry, never the output.
Then:
| Press | Result |
|---|---|
Super+Shift+E |
menu opens; a notification lists your projects |
s |
screenshot a file tree inside strojx |
Shift+s |
copy the whole strojx tree — no screenshot |
Escape or q |
cancel |
Each generated binding carries --notify, so you get a desktop notification
with the file count, size and a rough token estimate — without it a keybind
launch is silent and you cannot tell success from failure.
Everything is overridable by environment variable: SNAPX_REGISTRY,
SNAPX_OUTPUT, SNAPX_LEADER (default SUPER SHIFT, E), SNAPX_SCRIPT.
The leader is a single exec binding that shows the menu and enters the submap.
Hyprland runs only the first bind registered for a key combination, so a
separate submap bind plus a notify-send bind would enter the modal state and
never show the menu — looking exactly like the keybind doing nothing.
Run ~/.config/snap-extract/snapx-menu.sh directly to test the menu without
touching the keyboard.
The generator refuses duplicate keys, rejects multi-character keys, and warns about paths that do not exist rather than silently producing dead bindings.
Hyprland:
bind = SUPER SHIFT, E, exec, ~/snap-extract/snap-extract.sh --screenshot --root ~/projects/my-app --debug 2>/tmp/snap-extract.log
Press → drag over the file tree → paste with Ctrl+V.
Keep --root scoped to one project. Pointing it at $HOME makes every name
resolution a depth-8 find across your entire home directory: slow, and prone
to matching some unrelated index.ts in an archive folder.
| Symptom | Cause | Fix |
|---|---|---|
unknown argument: E (or similar) |
a pasted multi-line command lost its \ continuation |
retype on one line |
nothing identified after --folder |
the directory holds only subdirectories | add -r |
nothing identified after --screenshot |
OCR read no name matching --ext |
--debug, check the log; enlarge the region or the editor font |
names read, but no auto-promote line |
--root doesn't contain those files |
point --root at the right project |
| wrong directory promoted | a same-named file elsewhere resolved first | narrow --root |
| garbage OCR on a dark theme | ImageMagick missing, so preprocessing was skipped | install imagemagick |
Not implemented yet — listed so the gap is explicit rather than discovered.
--dry-run— list the files and total size without reading contents, to check scope before filling the clipboard.- Token estimate in the summary line, since the output usually goes into a model's context window.
.gitignoreawareness — currently the prune list is a static default.- Directory-name recognition. OCR sees folder names too, but only file names participate in resolution today.
- Instruction layer — post-capture text like "skip the tests" applied to the
file set, which is the one thing the
visionbackend is genuinely better at. - macOS support (
screencapture+pbcopy) and a verified X11 path; the X11 branch exists but is lightly tested. - Packaging — an AUR package and a
snap-extractbinary onPATHinstead of a cloned script.
- Name collisions resolve to the first match.
resolve_in_root_any_depthtakes whicheverfindhit comes back first, so with eight packages each holding anindex.ts, a narrow--rootmatters. --pruneonly applies when recursing. Flat mode has nothing to prune.- No
.gitignoreawareness. The prune list is a static default. - Wayland-first. The X11 path (
scrot+xclip) is written but lightly tested. macOS is not wired up.
If you want a mature repo-to-prompt packer with token counting and .gitignore
support, use repomix or
gitingest. snap-extract exists for the
screenshot path — pointing at what's on screen instead of typing globs.
MIT
