clover's git

the-knife

1	# SnapShots
2
3	A SnapShot captures the window you are working in and attaches it to your current draft. The
4	attachment carries the app name and window title, and when available the app icon and the window's
5	accessibility data (its controls, text, and their positions in the image). Agents can use that data
6	to reason about the screenshot.
7
8	SnapShots are off by default and available in the desktop app on macOS, Windows, and Linux with
9	Wayland. X11 sessions are not supported.
10
11	## Turning it on
12
13	Open **Settings** > **SnapShots** and turn the feature on. Setup has two steps: allow capture, then
14	choose a shortcut. Each step shows only what your desktop needs. **Finish later** turns capture back
15	off but keeps anything you already installed, so you can resume where you left off.
16
17	- **macOS** asks for Screen Recording during setup. It asks for Accessibility only when **Include
18	app text** is on.
19	- **Windows** needs no setup or permission.
20	- **Linux** depends on your desktop. See [Linux desktops](#linux-desktops).
21
22	Turning capture off releases the shortcut. It does not uninstall a helper or extension you installed.
23
24	## Taking a capture
25
26	Switch to the window you want and press the shortcut. The default on macOS and Windows is both
27	Shift keys together. T3 Code attaches the image to your draft and brings itself forward. If no thread
28	is open it starts a draft in the current project.
29
30	Pressing the shortcut while T3 Code is in front captures T3 Code itself.
31
32	Pending captures are kept on disk until the attachment is saved to the draft, so a capture survives
33	closing the app mid-way and is attached on the next launch. Captures rejected because the image is
34	too large are discarded.
35
36	## Changing the shortcut
37
38	Select the shortcut in Settings, press the new keys, then **Save**. On macOS and Windows you can use
39	a modifier pair such as Command+Command or Ctrl+Ctrl, or a key chord. T3 Code refuses shortcuts
40	that collide with its own keybindings or that the operating system already reserves.
41
42	On Linux, choose a key chord; modifier pairs are not supported. On Niri and Hyprland the shortcut
43	lives in your compositor config, so **Change shortcut** reopens setup to review the change.
44
45	## Include app text
46
47	**Include app text** controls whether captures include the window's accessibility data. Turn it off
48	to attach screenshots only. On macOS this also drops the Accessibility permission requirement.
49
50	Availability depends on the app. Some apps expose only their window controls, not the document or
51	terminal contents. If an app is slow to answer, T3 Code attaches the screenshot without the data
52	rather than waiting.
53
54	On GNOME, browsers may need app accessibility enabled in the desktop's accessibility settings before
55	they expose text. Restart the browser after enabling it.
56
57	An icon beside the app name on an attachment shows whether accessibility data was included. Select
58	it to inspect what was captured.
59
60	## Sound, flash, and animation
61
62	Settings controls the capture sound, the brief flash on the captured window, and the animation that
63	flies the image into your draft. Each can be turned off independently. The operating system's
64	reduced-motion setting also disables the animation.
65
66	## Linux desktops
67
68	SnapShots work on Wayland sessions. Each desktop provides capture differently, and setup names your
69	current desktop and shows only what it needs. Preferences carry across desktops, but each desktop's
70	helper and shortcut approval are separate.
71
72	**GNOME.** Install the bundled **T3 Code SnapShots** extension during setup. It is installed
73	per-user, offline, and needs no administrator password. Sign out and back in after the first
74	install so GNOME discovers it, then enable it from setup or from GNOME's Extensions app. If GNOME
75	has disabled all user extensions, turn them on there first. Disable or remove the extension in
76	GNOME's Extensions app to revoke access.
77
78	**KDE Plasma 6.** Install the bundled capture helper during setup; no sign-out is needed. If the
79	shortcut does not fire, check T3 Code under **System Settings** > **Keyboard** > **Shortcuts**. If a
80	shortcut using Shift and a number does not work on your keyboard layout, use a letter chord instead.
81	Remove the helper from **Manage capture** > **Access** > **Advanced**.
82
83	**Hyprland and Omarchy.** Install the bundled helper during setup, then choose a shortcut and select
84	**Review changes**. T3 Code shows the exact change it will make to your Hyprland config. **Save
85	shortcut** writes only that change, keeps a backup, and reloads Hyprland. Approve the screen-sharing
86	prompt for the helper if one appears. On Omarchy, bind in your own config, not the shipped defaults.
87	Some Hyprland versions return an "access denied" image instead of an error when capture is blocked;
88	check the helper's screen-sharing permission.
89
90	**Niri.** Choose a shortcut and select **Review changes**. T3 Code shows the exact binding it will
91	add to your Niri config, validates the result, keeps a backup, and saves it when you approve. Niri
92	reloads the config on its own. The binding needs the `gdbus` command, normally part of your
93	distribution's GLib tools. Remove the line from your config to release the key.
94
95	**Other Wayland desktops.** T3 Code uses the desktop's screenshot portal when it can capture the
96	active window. Otherwise Settings shows **Manual capture only** and the shortcut opens the desktop's
97	window picker. Picker captures do not include accessibility data.
98
99	Apps running through XWayland inside a Wayland session can still be captured.