Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.
Appshots
An appshot shows the assistant the window you are working in — or exactly the part of the screen you select. It captures once — picture and on-screen text — and hands it to the conversation as context. Settings live under Settings > Appshots.
Ways to take one
| Trigger | What happens |
|---|---|
| Window shortcut — both Alt keys at once by default (both Option keys on a Mac) | The front window is captured and delivered per Appshot destination. |
| Area shortcut — both Shift keys at once by default | Every screen dims with the marking toolbar already at the top. Drag a rectangle (or click a window) and letting go captures exactly that part at once, with whatever you marked on the screen before, and delivers it the same way. Esc or a right-click cancels and sends nothing. |
| Voice or chat — "take an appshot", "mach einen Appshot", "haz un appshot" | The turn that asked captures the front window and answers with it. Only an explicit request for the whole screen ("an appshot of my full screen") captures the monitor the cursor is on instead — the live model's take_appshot passes scope: "screen" for it. |
| Try it buttons on the Appshots page | "Take appshot in 3 s" waits three seconds so you can switch windows; "Select area" opens the area picker at once. Both then behave like the shortcuts. |
"Front window" means the app window you work in. Dodaios's own floating overlays (the mascot, the bar) take the focus when you click them, so the capture looks past them to the app window underneath (BUG-228); with no app window there, it takes the whole screen instead.
Paste it anywhere
Every appshot taken with a shortcut or a Try it button also goes on the
system clipboard, so Ctrl+V (Cmd+V on a Mac) pastes it straight into a chat,
a mail, a document or an image editor. It is the finished picture, markings
included, at full resolution (the lossless copy, not the smaller picture the
assistant gets). Looks the assistant takes on its own, or a spoken "what do
you see?", never replace what is on the clipboard. Copy to clipboard on
the Appshots page ([appshot].copy_to_clipboard) turns it off.
The clipboard holds the same picture in several formats at once, because
every app asks for a different one (dodaios/platform/clipboard_image.py):
| OS | Formats | Who reads what |
|---|---|---|
| Windows | PNG (registered format, offered first) + CF_DIB; Windows adds CF_BITMAP and CF_DIBV5 itself |
Browsers, Electron chat apps and Office take the lossless PNG with its transparency; classic Win32 apps (Paint and older tools) take the bitmap, where transparent parts are laid on white instead of turning black |
| macOS | public.png + public.tiff on the general pasteboard, set through the built-in JavaScript for Automation bridge (osascript -l JavaScript); AppleScript sets the PNG alone if that bridge fails |
Modern apps read PNG; TIFF is the pasteboard's native image type that older Cocoa apps read |
| Linux | image/png through wl-copy (Wayland) or xclip (X11) |
Every X11 and Wayland toolkit reads image/png. Without either tool nothing is copied and the log names the package to install |
| Headless | — | No clipboard; nothing is attempted |
Dodaios X screenshots ([jarvisx].copy_to_clipboard) use the same code.
Selecting an area
The area picker uses a prepared PySide6 process (python -m dodaios.appshot.picker --resident). The main instance prepares it after the
wake-ready gate when Appshots are enabled. Standby creates no selection
windows and captures no pixels. Each shortcut samples the current screens
and window layout; completing or cancelling releases the frozen images,
blur previews, markings and windows while keeping Qt loaded. The picker provides:
- every screen is frozen under a light dim the moment the picker opens, so nothing moves under the selection (where a frozen frame cannot be grabbed, a dim layer over the live desktop is used instead);
- the appshot is that same instant: every screen is grabbed at the shortcut press, before the picker opens, and the finished area is cut out of that frame (at full depth on an HDR monitor), so a video that plays on while the area is selected does not change the picture;
- the pointer is a thin crosshair with a small ring, and two small numbers beside it show the position — while dragging, the width and height in real pixels. No lens, no boxed labels, no banner;
- hovering lifts the window under the pointer out of the dim, and a click without a drag takes exactly that window. On Windows it offers the parts inside the window too (a sidebar, a file list, the page, a panel, a picture): the smallest part under the pointer lights up as soon as the window has been read (typically 10-200 ms), the mouse wheel steps out to the larger parts around it and the whole window (and back in), and a click takes what is lit;
- a drag clears the dim and tints the selected area a translucent grey with one thin border.
Marking up, before or after choosing the area
The marking toolbar is up the moment the screens dim, centred at the top of the screen under the pointer (it follows the pointer to another screen until something is marked there). The area tool is in hand: drag a rectangle, or click a window, and letting go takes the appshot at once. There is no second step to confirm it.
To point at something, pick a drawing tool first (its button, its letter, Tab or the middle mouse button), draw anywhere on the frozen screen, then go back to the area tool (K, Tab or the middle button) and drag the area: the appshot carries every marking inside it. Space takes the whole screen with its markings. With the area tool, a press on a marking moves that marking; hold Ctrl to start the area right on top of it.
Adjust before taking (the frame button next to Copy) switches to the
older flow and is remembered ([appshot].region_keep_area): a released area
stays on screen with eight resize handles (they are the crop) and its size
in pixels above its corner; drag inside it with the area tool to move it,
mark it up, then Enter, a double-click in it or the check button takes it.
The toolbar moves under the area when the area would sit under it.
Everything drawn is what the assistant sees, so it can be pointed at directly. The tools, keys and looks are the same as in the full editor below:
| Key | Tool | |
|---|---|---|
| K | Area (default) | Drag or click a window; letting go takes the appshot (the editor's crop key) |
| V | Select and move | Click a marking to pick it, drag to move it, Delete removes it, arrow keys nudge it |
| R | Rectangle | Shift = square |
| F | Filled rectangle | Shift = square |
| E | Ellipse | Shift = circle |
| L | Line | Shift snaps to 45 degrees |
| A | Arrow | Tapered, classic or two heads; Shift snaps to 45 degrees. The first tool Tab goes to |
| T | Text | Click, type; Enter finishes, Shift+Enter is a new line, Ctrl+V pastes; plain, label or outline look |
| P | Pixelate / blur | Hides what is under the box |
| H | Spotlight | Dims everything outside the box |
| C | Numbered step | Each click places the next number |
| D | Draw | Free stroke |
| M | Highlighter | Wide translucent stroke |
| B | Background | Puts the area on a gradient or solid frame |
Tools with looks (arrow, text, pixelate/blur, background) show them right after the tools, in the same row. Colours: eight presets. Size: keys 1-5, the size button or the mouse wheel (new text and step markers follow it). Ctrl+Z / Ctrl+Y undo and redo. Every marking shows its points right after it is drawn (the previous one loses them), and any drawing tool takes a drawn marking under the pointer again (pen and highlighter only its points; V also takes pixelate and spotlight boxes): lines and arrows have one at each end and one in the middle that bends them into a curve, boxes and strokes one at each corner, a step marker one on its rim, and text one at each corner — dragging that scales the text, font size and all, from the opposite corner. A colour, size or look chosen then changes that marking. Double-clicking a text (with V or T) edits it. A right-click on a marking removes it. With a kept area, its handles resize it at any time, and a right-click on nothing drops it so a new one can be drawn.
Finishing:
| Key / button | Result |
|---|---|
| Letting go of the area drag, or clicking a window | Take that area with the markings and deliver it |
| Space | Take the whole screen with the markings |
| Enter / check button | Take the kept area (or the whole screen, when none is kept) with the markings |
| Double-click in a kept area | The same as Enter |
| Ctrl+C / Copy | The same, and the finished picture goes to the clipboard |
| Ctrl+S / Save | The same, and a PNG goes to ~/Downloads |
| Ctrl+E / Editor | The same, and the full appshot editor opens on it |
| Esc / cross / right-click on nothing | Cancel; nothing is captured |
The capture itself is unchanged: after the overlay closes, Screen Context
grabs the area (denylist, redaction and all), and only that finished picture
gets the markings (dodaios/appshot/markup.py) — blur and pixelate on the
capture's own pixels first, then the drawn markings as a transparent layer
stretched to the capture's size, then the background frame if one was
chosen. The markings never show anything the
privacy filter removed. A marked appshot carries the same note as an editor
edit (the markings are the user's), and the corner card's thumbnail shows
them too. Once something is marked the global Esc stops cancelling, so Esc
can end a text box without throwing the markings away. On Windows the picker
takes the keyboard when it opens, so Space, Tab and the tool letters work
before the first click.
The picker reports the rectangle as fractions of the screen it was drawn on;
the app maps that back to capture pixels (dodaios/appshot/region.py), so
mixed-DPI setups capture exactly what was outlined. A selection stays on one
screen. The window list for snapping is read before the overlay appears and
skips minimized and (on Windows) cloaked windows; where no list is available
(Wayland) only dragging works. The parts of a window come from UI Automation
(dodaios/appshot/picker/elements.py): one cached query per window on a
worker thread, the window under the pointer first, each window read once per
pick. Only containers and pictures count (panes, groups, documents, lists,
trees, tables, toolbars, tabs, text areas, images); single buttons, rows,
items, links and web components are left out, and so is any part under
40 px a side, under 1.5 % of the window, or mostly hidden under another
window. Nested parts that are nearly the same box count as one wheel step. Off
Windows, and for windows that expose no parts, hovering snaps to whole
windows as before. The picker gives up after fifteen minutes
without a result.
A selected area is about pixels, not about the window in front: unlike a window appshot it is not voided when focus moves while the picker closes. Its privacy guard is the denylist check on every visible window that overlaps the rectangle (see below).
A spoken "what do you see?" is the same look (Screen Context); it also plays the shutter and shows up as the last appshot.
The card in the corner, and the editor
After the shutter the picture flies into the bottom-right corner of its
screen and rests there as a quick-access card. Its lifetime is set by
[appshot].card_seconds (Settings → Appshots → Corner card: 3, 6,
10 or 30 seconds, or until you close it); the pointer on it keeps it.
Several appshots stack: the newest always lands at the bottom and the
cards already there glide up to make room; when a card goes,
the ones above it glide down. Up to five cards stay (the oldest leaves first,
or earlier when the screen has no room). Every card belongs to its own
appshot, so Copy, Save, Copy text, Edit and a drag on an older card reach
that card's picture (AppshotStore keeps the last five, each for
[screen_context].deck_preview_s).
- Hover frosts the picture and shows Copy and Save stacked in
the middle, plus four round chips in the corners: Pin (top left),
Close (top right), Edit (bottom left) and Copy text (bottom
right). The chip under the pointer names itself along the bottom edge.
Copy puts the picture on the clipboard, Save writes it to Downloads and
Copy text copies the on-screen text the appshot read (where the screen had
any) — all done by the main process (
dodaios/appshot/card_actions.py), so the clipboard survives the overlay quitting on Linux; the card shows the result for a moment. Pin keeps the card until you close it, whatever Corner card says; a pinned card shows the pin even without the pointer. - Click (or Edit) opens the appshot editor in a window of its own in front of you; the app behind keeps its size and what it shows. Without a desktop shell (a browser, a headless host) the editor opens over the app's page instead. See The editor.
- Save or Done in the editor flies the edited picture from the editor back to the bottom of the stack (the shutter's flight, without the flash or a sound); Close slides the unchanged picture in from the edge. Either way it stays at hand.
- Drag the card into any app that accepts files or images (chat, mail, Explorer/Finder) to drop the picture there. A smaller rounded copy lifts off and stays where you grabbed it, and a green "+" beside the pointer shows that the text field or window under it takes the picture (macOS shows its own green badge). Dropped nowhere, or cancelled with Esc, the card stays; after a drop it slides away.
- Right-click dismisses it.
Only the finished, privacy-filtered appshot can leave by drag — the card's
own thumbnail is cut from the raw frame and never does. A drag is the one
moment an appshot touches disk: the picture is written to
<temp>/jarvis-appshots/ just then, and files older than an hour are removed
on the next drag. With [screen_context].deck_preview_s = 0 (keep nothing)
the card only opens the editor and shares nothing.
The editor
The editor provides annotation tools, one-letter shortcuts and a compact
window for editing a capture. It opens from the corner card or from Edit
on the last appshot (Settings → Appshots) — in
its own desktop window (?view=appshot-editor, views/AppshotEditorWindow.tsx),
or, without a desktop shell, as a floating rounded window over the dimmed
app. Nothing navigates away.
- Top bar: close, crop and background, the tools as pills, the colour menu (presets + any colour) and the size slider, then Save and Done.
- Options capsule: under the top bar, only for tools that have options (text style, pixelate or blur, crop ratio with size, Reset and Crop, background) or a hint. Add picture opens a side panel instead.
- Bottom bar: zoom (Fit, 50 %, 100 %, 200 %), undo and redo; a Drag me handle in the middle; delete (with a selection), save and copy on the right.
| Key | Tool | What it does |
|---|---|---|
| V | Select and move | Click an annotation to select it; drag moves it, arrow keys nudge it (Shift = 10 px), Delete removes it. Double-click a text to change it. The only tool that also picks spotlights and redactions. |
| A / L | Arrow / Line | Shift snaps to 45°. |
| R / F / E | Rectangle / Filled rectangle / Ellipse | Shift makes a square or circle. |
| D | Draw | Freehand, smoothed. |
| M | Highlighter | Translucent marker that keeps text underneath readable. |
| T | Text | Plain, label (filled box) or outline style; Enter commits, Shift+Enter breaks the line. |
| C | Counter | Numbered badges; each click adds the next number. |
| H | Spotlight | Dims everything outside the dragged areas. |
| P | Pixelate or blur | Hides a region; the options bar switches between pixelate and blur. |
| K | Crop | A frame over the whole document with corner grips (and edge grips for a free crop), a thirds grid and its size in pixels. Drag a grip or the frame itself, or drag outside it for a new one; Free, 1:1, 4:3 or 16:9 (a ratio reshapes the frame at once). Enter or Crop finishes, Reset shows everything again, undo brings the rest back. |
| B | Background | Frames the picture on a backdrop (eight presets, padding, corner radius, shadow); applied on copy, save and use. |
| I | Add picture | Puts another picture into the document: an earlier appshot from the gallery, a file, a pasted picture (Ctrl+V) or one dropped onto the editor. It goes beside (same height), below (same width) or on top (small, in the middle) of what is visible; the choice is remembered. |
Several pictures in one. An added picture is a layer of the document, painted under every annotation, so an arrow or a highlight can run from one picture into the next. The select tool (V) moves it and its corner grips resize it without distorting it; Delete removes it. The document grows with its pictures, a crop that is in place grows to take a new picture in, and Copy, Save, Drag me and Done hand on the combined picture. Pixelate and blur hide whatever picture lies under them.
Taking hold of annotations: the select tool picks up any annotation — the pointer turns into a move cursor over it, a drag moves it, a click selects it. A shape tool (arrow, line, boxes, text, spotlight, redact) selects the shape it just drew and can reshape or move only that one; a press anywhere else, also on an older annotation, draws a new shape. Draw, Highlighter and Counter never take hold of anything: their strokes and badges are not selected, so writing over earlier ink or placing the next number right beside the last one always draws. A selected annotation shows round grips — at both ends of an arrow or line (drag the tip somewhere else), at the corners of a box, a stroke or a redaction (resize from the opposite corner), at a text's corner (its size) and on a counter's rim (the badge's size). Every move and reshape is one undo step.
Colours: eight presets plus any colour from the system picker; the last one is remembered. Sizes: the slider or keys 1–5. History: Ctrl+Z, Ctrl+Shift+Z or Ctrl+Y (⌘ on macOS).
Results: Copy (Ctrl+C) puts the PNG on the clipboard — natively through
POST /api/appshot/clipboard on the desktop, the browser clipboard
elsewhere. Save (Ctrl+S) writes it to Downloads through the backend
(the desktop WebView drops browser downloads) and the toast offers "Show in
folder". Done (Ctrl+Enter) replaces the held appshot so the next
message carries the edit (a picture already sent into a voice call stays
as it was). Drag me writes the finished picture to
<temp>/jarvis-appshots/ the moment it is pressed and hands it to the native
drag bridge while the button is held, so it drops into any app as a real
file (Windows and macOS; Linux has no drag bridge yet, the handle is hidden
there and Save + "Show in folder" stand in). Escape closes a menu, cancels a
stroke, clears a selection, then closes; with unsaved edits it asks first.
Feature coverage
Status here: done = in the editor; elsewhere = Dodaios covers it outside the editor; not done = not built, with the reason.
| Feature | Status |
|---|---|
| Arrow, line, rectangle, filled rectangle, ellipse, pencil, highlighter, text, counter, spotlight, pixelate, blur, crop with aspect ratio | Done |
| Background tool (presets, padding, aspect/position) | Done: presets, padding, corners, shadow. Custom uploads, saved presets, auto-balance and aspect ratio of the frame are not done. |
| Colour picker with saved palette | Done: presets + any colour, last one remembered (not a palette of several) |
| Arrow styles (4 curved) | Not done: one straight arrow |
| Text styles (7) | Partly: 3 styles |
| Move/select annotations | Done |
| Rotate, flip, resize image | Not done |
| Combine images | Done: add pictures beside, below or on top (gallery, file, paste, drop) |
| Editable project file | Not done |
| Capture area / window / fullscreen, freeze, crosshair with coordinates | Elsewhere: the area picker and the window shortcut (Selecting an area); no fullscreen mode |
| Corner card (copy / save / annotate / drag after capture) | Elsewhere: the corner card (click = editor, drag = file) |
| Editor window: drag handle, zoom, Save / Done | Done: "Drag me" (Windows, macOS), zoom Fit/50/100/200 %, Save to Downloads, Done = use in the next message |
| Scrolling capture, self-timer | Not done (the page's "in 3 s" button is the only timer) |
| Screen recording and video editor | Local MP4 recordings with quality controls and optional system audio |
| GIF export | Not done |
| Cloud upload and sharing | Not done — appshots stay on this machine by design |
| Text recognition (OCR), QR codes | Not done in the editor; the model reads the picture itself when it gets it |
| Pin to screen (floating screenshot) | Not done: needs an always-on-top native window per OS |
| Capture history | Not done: only the last appshot is kept, in memory |
Every editor feature is web code in the app's own WebView, so it behaves the
same on Windows, macOS and Linux. The two native paths are the clipboard
(Windows CF_DIB + PNG, macOS osascript, Linux wl-copy or xclip —
without either, Copy falls back to the browser clipboard and says so if that
fails too) and Save (~/Downloads on every OS).
What the assistant gets after an edit
An appshot is two things at once: a screenshot the user keeps, and context
for the assistant. Done decides the second: the edited picture becomes
the appshot (PUT /api/appshot/latest/image), and deliver_edit in
dodaios/appshot/service.py hands it over with a note that the markings are
the user's — arrows, boxes, numbers and text point at what they mean, hidden
parts were hidden on purpose:
| Situation | Where the edit goes |
|---|---|
A voice call runs and target is auto or voice |
Into the call at once — even when the call already saw the original. A waiting original is withdrawn, so it does not follow later. |
No call (or target = message) |
Onto the next message — even when the original was sent already. |
target = voice and no call |
Nowhere; the edit is kept as the last appshot. |
The editor says which one happened. Copy, Save and Drag never send anything to the assistant; they are the screenshot-tool half.
The gallery
Below the settings, Your captures shows every appshot taken with the
shortcuts, the page's buttons or the assistant's take_appshot tool, and every
edit saved in the editor, newest first. An edit sits right before its original
and wears an Edited badge; the Edited filter shows only those. A look
a conversation turn took on its own is never kept. Finished screen recordings
appear in the same grid, with a video badge and duration. The Recordings
filter shows only videos. Existing recordings appear automatically, including
ones created before this gallery supported video.
- Click a picture to open it in the editor again. Saving there keeps the new edit beside the original and hands it to the assistant like any edit.
- Click a video to play it with playback and seeking controls. The player also offers an MP4 download. Closing it returns to the same gallery.
- Drag a picture into a chat composer or a terminal pane to attach it.
The drag carries the picture's real path the way a row from the workspace
explorer does, so both drop targets take it unchanged. In a browser the
drag also carries a
DownloadURL, so it can be dropped onto the desktop. Inside the desktop shell the grip on a tile starts a native file drag that reaches any other app (mail, Explorer/Finder, a browser upload). - Delete on an edited tile removes only that edit; on an original it removes the appshot and its edit. On a video it removes that recording. Delete all confirms that both pictures and videos will be removed; a recording still in progress is never included.
The pictures live in <data dir>/appshots/<id>/ (original.<ext>,
edited.png, meta.json, small thumbnails made on first view). Only the
finished, privacy-filtered appshot is written — never the raw frame or the
on-screen text. The library keeps the newest 500 appshots and removes the
oldest first. Keep appshot history ([appshot].library) turns it off;
what is already kept stays until it is deleted.
Screen recordings are finalized as MP4 files under the app's user-data
directory (appshot-recordings/) and remain there across navigation and app
restarts, independently of the screenshot-history switch. The gallery indexes
these existing files rather than duplicating them. It loads only small video
posters for tiles and streams the full file when playback is opened. The image
editor's Add Picture panel continues to offer images only.
Recording quality and system audio
The recording panel saves preferences for both button and shortcut starts. Defaults are 1080p, 60 FPS, 12 Mbps, with system audio off. Available resolutions are 720p, 1080p, 1440p, 2160p and native (including displays above 4K). Presets are bounding boxes: the source keeps its aspect ratio, portrait sources use the corresponding portrait bounds, and smaller areas are never enlarged. Encoders may add a single padding pixel for even H.264 dimensions.
Frame-rate choices are 30, 60 and 120 FPS. The monitor on which the user selects an area determines the limit; another monitor's faster refresh rate does not raise it. Selection remains confined to one monitor per recording. If the capture portal cannot expose its refresh rate, the conservative cap is 60 FPS. Actual output dimensions and FPS are shown while recording. Capture and encoding can skip frames under load; the completion state reports skipped frames.
The video target bitrate accepts whole values from 1 to 100 Mbps. It is an encoding target, not a promised file size: simple scenes can need fewer bits. MP4 prefers an available hardware H.264 encoder, falls back to software H.264, and finally MPEG-4. A codec must open successfully at the selected dimensions; the presence of a GPU or codec name alone is not treated as support. Streaming Qt Multimedia capture replaces repeated screenshots. High-resolution timestamps preserve real frames despite desktop timer jitter. The video editor retains the source timing and includes audio when trimming or changing playback speed.
Include system audio captures the default playback device using SoundCard output loopback, at 48 kHz stereo, encoded as AAC. This includes applications on other monitors using that output. It never falls back to a microphone. Device selection is fixed for the recording; switch outputs before starting a new recording. An audio failure reports an error instead of silently producing a successful video without sound. Windows output loopback was verified locally with an audible test signal. Linux uses a PulseAudio/PipeWire monitor source and still requires live device verification. macOS system audio is currently unavailable and is disabled in the UI; silent screen recording remains available. Optional desktop packages are lazy imports and are not needed for base/headless startup.
Where a shortcut appshot goes
| Destination | Running voice call | No voice call |
|---|---|---|
| Automatic (default) | Into the call | Onto your next message |
| Next message | Onto your next message | Onto your next message |
| Voice call only | Into the call | Not sent |
- Into the call is silent: GPT-Live puts the picture into its thinking backend's context, native live models (Gemini, local servers with image input) receive it as a video frame. Your next words are the question.
- Onto your next message: the next spoken turn uses it, or — while the
front-page chat is open — it appears in the composer as an attachment you
can remove. It is single use and expires after
[screen_context].ttl_s. - Scheduled tasks, workflows and background agents never take a parked appshot; it waits for a person.
Privacy
Appshots capture through the Screen Context engine
(screen-context.md), so everything there applies
unchanged: the app denylist and redaction of password fields and sensitive
patterns. The capture itself writes nothing to disk; the one deliberate copy
is the gallery's history (see The gallery), which can be
switched off and deleted. For an area, a denylisted window
that overlaps the rectangle refuses the capture; one elsewhere on the screen
does not. The one difference: an appshot
shows no gold border before the shutter — the flash over the captured window
is the visible signal (maintainer directive 2026-09-29). Allow appshots on the Appshots page is [screen_context].enabled
— one switch for every screen look.
The shutter effect's thumbnail is cut from the frame in memory and piped only
to the local overlay process, which is excluded from screen capture on
Windows and hidden before any capture elsewhere. The last appshot shown on the
Appshots page is kept in memory for [screen_context].deck_preview_s seconds
and served with Cache-Control: no-store.
Settings
[appshot] in jarvis.toml, written only through the app or
dodaios api appshot put-settings:
| Key | Default | Meaning |
|---|---|---|
hotkey |
"alt+alt" |
Window appshot. alt+alt / shift+shift / ctrl+ctrl = both keys of that pair; any other combo in the shared hotkey syntax; "" = off |
region_hotkey |
"shift+shift" |
Area appshot, same syntax. Must differ from hotkey (the app refuses one key for both) |
region_keep_area |
false |
false: letting go of the area drag takes the appshot at once. true: the area stays to be adjusted and marked; Enter or a double-click takes it. The picker's "Adjust before taking" button flips it |
Both shortcuts are changed on the Appshots page: Change records the next
key gesture (hold the keys, then let go; Esc cancels), the X turns the
shortcut off. Pressing the same modifier on both sides records the matching
two-sided gesture. For Shift and Ctrl, which are held all the time while
typing, the second key has to follow the first within half a second, so a
capital letter typed with one Shift never fires it; both-Alt keeps its
original any-order behaviour.
| target | "auto" | auto · message · voice (table above) |
| sound | true | Shutter sound; also needs [ui].sound_effects |
| effect | true | Flash and corner thumbnail |
| card_seconds | 6 | How long the corner card rests, 0–600 seconds; 0 = until closed |
| library | true | Keep every appshot and saved edit in the gallery (<data dir>/appshots/, newest 500) |
| copy_to_clipboard | true | Put shortcut and button appshots on the clipboard (see Paste it anywhere) |
Operating systems
| Windows | macOS | Linux/X11 | Wayland / headless | |
|---|---|---|---|---|
| Both-Alt shortcut | GetAsyncKeyState (AltGr counts as right Alt) |
CGEventSourceKeyState, needs the Input Monitoring grant; a silent check (never a prompt) reports the shortcut unavailable and names the grant when it is missing |
XQueryKeymap via python-xlib |
Unavailable, reason shown on the page; voice and the button still work where capture works |
| Other shortcuts (incl. the area shortcut) | Shared hotkey backends (dodaios/trigger/backends) |
same | same | same as above |
| Area picker and its marking toolbar | PySide6 overlay; it takes the keyboard when it opens, and a global Esc also cancels until something is marked, in case Windows still keeps the keyboard from it | PySide6 overlay | PySide6 overlay | Unavailable, reason shown on the page; the window appshot still works |
| Burning the markings into the appshot | Pillow, in the main process (dodaios/appshot/markup.py) |
same | same | same (no display needed) |
| Flash + thumbnail | PySide6 overlay, excluded from capture | PySide6 overlay | PySide6 overlay | No overlay; the appshot is still taken where capture works |
| Capture | Screen Context engine | Needs Screen Recording; macOS asks for it at the first appshot you take | X11 | Honest refusal |
Only the instance that owns ambient duties (the default app, not the dev instance) arms the shortcuts.
Capture startup latency
Previously every area shortcut started Python, imported Qt and initialized the GUI before freezing the screens. The shutter effect also started its own process when the previous card had closed. Both startup costs sat on the interaction path and could show the operating system's busy cursor.
The area picker now reuses its prepared runtime. The shutter runtime stays ready while Appshots and their effect are enabled. Neither preparation takes a screenshot or opens an overlay. Disabling Appshots releases the picker and the idle shutter runtime; active Computer-Use borders and open cards keep their existing ownership. Application shutdown reaps both helpers. Timeouts and interrupted requests discard the picker before a later request can use it, and a dead idle process is recreated on the next request.
Windows verification on Python 3.11 measured about 399 ms from cold picker spawn to its visible-ready acknowledgement, versus 94–133 ms per selection in a prepared process. A separate native drag/toolbar/Enter check measured 141–168 ms and verified no remaining selection windows after either pick. These are local renderer measurements, not a universal shortcut latency guarantee; configuration, privacy checks, display capture and image processing still take time. macOS and X11 share the lifecycle but were not tested live; Wayland, headless hosts and installations without PySide6 remain unavailable.
Code
dodaios/appshot/ — service.py (take and deliver), store.py (pending and
last appshot, memory only), library.py (the gallery's history on disk), gesture.py (both-Alt watcher), hotkey.py
(both shortcuts' lifecycle), region.py (area selection and its coordinate
mapping), picker_host.py (prepared-process lifecycle), picker/ (the area
picker sidecar), effect.py (shutter hook),
delivery.py (voice calls). The corner card lives in the indicator sidecar
(dodaios/cu/indicator/renderer.py, _CardWindow); the editor is
frontend/src/views/AppshotEditor.tsx, hosted by
components/appshot/AppshotEditorHost.tsx (opened through
store/appshotEditor.ts), with its document model in
lib/appshotEditorModel.ts, the copy path in lib/appshotClipboard.ts and
the native clipboard in dodaios/platform/clipboard_image.py.
The live model's take_appshot tool is dodaios/plugins/tool/appshot.py; the
REST surface is dodaios/ui/web/appshot_routes.py; the page is
frontend/src/views/AppshotsView.tsx, its gallery
frontend/src/views/AppshotLibrary.tsx.