{"id":51204319,"url":"https://github.com/ma08/omnishot","last_synced_at":"2026-06-28T02:07:52.571Z","repository":{"id":356307236,"uuid":"1230365852","full_name":"ma08/omnishot","owner":"ma08","description":"Agent-native screenshots for local and remote workspaces","archived":false,"fork":false,"pushed_at":"2026-05-07T13:56:36.000Z","size":24795,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-07T14:42:09.595Z","etag":null,"topics":["agents","ai","macos","ocr","s3","screenshots"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ma08.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-05T23:40:27.000Z","updated_at":"2026-05-07T14:00:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ma08/omnishot","commit_stats":null,"previous_names":["ma08/omnishot"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ma08/omnishot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ma08%2Fomnishot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ma08%2Fomnishot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ma08%2Fomnishot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ma08%2Fomnishot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ma08","download_url":"https://codeload.github.com/ma08/omnishot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ma08%2Fomnishot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34874576,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai","macos","ocr","s3","screenshots"],"created_at":"2026-06-28T02:07:48.907Z","updated_at":"2026-06-28T02:07:52.565Z","avatar_url":"https://github.com/ma08.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Omnishot\n\nAuto-renames and organizes macOS screenshots with local Apple models, then makes\nthe latest capture easy to paste anywhere: raw image bytes, path refs for remote\nagents, signed S3 URLs, or public links, all behind simple keybindings.\n\nRead the launch article on X/Twitter: [Making Screenshots Agent-Native in Remote Workspaces](https://x.com/curious_queue/status/2051832335973364102?s=20).\n\nSee the demo clips in the walkthrough thread on X/Twitter: [Omnishot screenshot routing demos](https://x.com/curious_queue/status/2052106783590961660?s=20).\n\n[![Omnishot article cover: screenshots routed from a local Mac into path-ref, image paste, S3 URL, and public-link workflows](docs/assets/readme/omnishot-article-cover.png)](https://x.com/curious_queue/status/2051832335973364102?s=20)\n\nThis is a small macOS utility that turns a normal screenshot into a named,\nrouteable artifact:\n\n- semantic local filename from Apple Vision OCR + Apple Foundation Models\n- compact `screenshot-info` payload for remote agents over SSH\n- direct image paste for chat apps, docs, Finder, Cursor, and VS Code\n- S3/public links when a URL is the right transport\n\nIt is public as a reference implementation, not a polished product. The useful\nparts to copy are the workflow shape, paste-mode contract, machine alias\nconvention, and agent instructions.\n\n## Ask Your Agent To Adapt This Repo\n\nPaste this into your coding agent before deciding what to copy:\n\n```text\nRead through https://github.com/ma08/omnishot and help me adapt\nthe screenshot workflow to my own machine setup.\n\nFocus on reusable patterns, not copying the repo author's machine-specific config.\n\nAsk me targeted questions about:\n- where my screenshots land\n- whether I use local or remote coding agents\n- my SSH aliases between machines\n- whether I need S3/public links or only local SSH transfer\n- what apps I paste screenshots into most often\n\nThen recommend the smallest useful version I should implement.\n```\n\n## Workflow At A Glance\n\n```mermaid\nflowchart TD\n    A[\"macOS screenshot\u003cbr/\u003eCmd+Shift+3/4/5\"] --\u003e B[\"Detect + batch\u003cbr/\u003ewatcher.py\"]\n    B --\u003e C[\"Understand locally\u003cbr/\u003eVision OCR + Apple Foundation Models\"]\n    C --\u003e D[\"Semantic rename\u003cbr/\u003etimestamp + content slug\"]\n    D --\u003e E[\"Persist + upload\u003cbr/\u003eSQLite history + S3 link\"]\n    E --\u003e F[\"Ready to route\u003cbr/\u003eclipboard + menubar shortcuts\"]\n\n    F --\u003e G[\"Cmd+V / Cmd+Option+V\u003cbr/\u003epath-ref\"]\n    F --\u003e H[\"Cmd+Shift+Option+V\u003cbr/\u003eimage paste\"]\n    F --\u003e I[\"Cmd+Control+Option+V\u003cbr/\u003eS3 URL\"]\n    F --\u003e N[\"Cmd+Control+Shift+Option+V\u003cbr/\u003epublic link\"]\n\n    G --\u003e J[\"screenshot-info\u003cbr/\u003emachine + path\"]\n    J --\u003e K[\"Remote agents\u003cbr/\u003escp into task artifacts\"]\n    H --\u003e L[\"Local apps\u003cbr/\u003echat/docs/Finder/editor\"]\n    I --\u003e M[\"Web/social sharing\u003cbr/\u003eURLs when needed\"]\n    N --\u003e M\n```\n\nThe core abstraction is:\n\n```text\nscreenshot -\u003e named artifact -\u003e route to the current surface\n```\n\nS3 is one transport, not the whole point.\n\n## Visual Walkthrough\n\nThe menu bar keeps the latest screenshot actions inspectable even when keyboard\nshortcuts are faster.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/readme/menu-actions.png\" alt=\"Omnishot menu bar actions showing path reference, S3 URL, image paste, public link, recent screenshots, and folder actions\" width=\"760\"\u003e\n\u003c/p\u003e\n\nThe local naming and upload pipeline is observable, so failures are not hidden\ninside a background watcher.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/readme/langfuse-trace.png\" alt=\"Langfuse trace for an Omnishot screenshot processing run\" width=\"760\"\u003e\n\u003c/p\u003e\n\n## Why It Exists\n\nTaking screenshots is easy. Getting a screenshot into the right agent, on the\nright machine, with a useful filename and durable task context, is still awkward.\n\nBefore:\n\n```text\nScreenshot 2026-02-23 at 9.43.31 PM.png\n```\n\nAfter:\n\n```text\n2026-02-23_21h43m40s_PST_cursor-settings-heavy-memory.png\n```\n\nDefault agent payload:\n\n```text\nscreenshot-info:\n  machine: work-mac\n  path: /Users/alex/Pictures/Screenshots/2026-05-05_08h36m35s_PDT_dashboard-error-state.png\n```\n\nA remote agent can then copy the image into its task folder:\n\n```bash\nscp 'work-mac:/Users/alex/Pictures/Screenshots/example.png' user_inputs/input_artifacts/\n```\n\n## Quick Start\n\n```bash\ngit clone https://github.com/ma08/omnishot.git\ncd omnishot\nuv sync\n\n# Required for uploads and URL paste modes\nexport OMNISHOT_BUCKET=your-bucket-name\n\n# Optional, recommended on supported macOS versions\n./scripts/build-swift.sh\n\n# Recommended runtime\nuv run omnishot menubar\n```\n\n## Paste Modes\n\n| Shortcut | Payload |\n|----------|---------|\n| `Cmd+V` | configured default after capture, `path-ref` by default |\n| `Cmd+Option+V` | latest path reference (`screenshot-info`) |\n| `Cmd+Shift+Option+V` | latest image directly |\n| `Cmd+Control+Option+V` | latest S3 URL |\n| `Cmd+Control+Shift+Option+V` | latest public link |\n\nConfigure the machine token with:\n\n```bash\nexport BOT_MACHINE_SSH_ALIAS=work-mac\n```\n\nor pass `--ssh-host-hint work-mac`.\n\n## Agent Instructions\n\nThe compact payload works best when your global agent instructions teach agents\nwhat to do with it:\n\n- treat `machine` as an SSH alias\n- copy the referenced image into the active task's `user_inputs/input_artifacts/`\n- index the artifact before relying on it\n\nReference implementation: [botfiles PR #23](https://github.com/ma08/botfiles/pull/23)\nadds this behavior to global Codex/Claude instructions.\n\n## Demo Clips\n\nThe full walkthrough thread is on X: [Omnishot screenshot routing demos](https://x.com/curious_queue/status/2052106783590961660?s=20).\n\nGitHub strips inline MP4 players from README Markdown, so each card uses a\nshort animated preview and links to a browser-playable hosted clip.\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://sourya-screenshots.s3.amazonaws.com/omnishot/readme/clips/clip-capture-and-remote-retrieval.mp4\"\u003e\n        \u003cimg src=\"docs/assets/readme/clip-capture-and-remote-retrieval.gif\" alt=\"Animated preview of Omnishot capturing a Mac screenshot and a remote agent retrieving it\" width=\"720\"\u003e\n      \u003c/a\u003e\u003cbr\u003e\n      \u003cstrong\u003eCapture + remote retrieval\u003c/strong\u003e\u003cbr\u003e\n      \u003csub\u003eMac screenshot -\u003e path-ref paste -\u003e VM copies image into task artifacts.\u003c/sub\u003e\u003cbr\u003e\n      \u003ca href=\"https://sourya-screenshots.s3.amazonaws.com/omnishot/readme/clips/clip-capture-and-remote-retrieval.mp4\"\u003eWatch clip\u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://sourya-screenshots.s3.amazonaws.com/omnishot/readme/clips/clip-paste-routes-montage.mp4\"\u003e\n        \u003cimg src=\"docs/assets/readme/clip-paste-routes-montage.gif\" alt=\"Animated preview of Omnishot paste routes for path-ref, S3 links, public links, and picker access\" width=\"720\"\u003e\n      \u003c/a\u003e\u003cbr\u003e\n      \u003cstrong\u003ePaste routes montage\u003c/strong\u003e\u003cbr\u003e\n      \u003csub\u003ePath-ref, signed S3 URL, public URL, picker access, and link checks.\u003c/sub\u003e\u003cbr\u003e\n      \u003ca href=\"https://sourya-screenshots.s3.amazonaws.com/omnishot/readme/clips/clip-paste-routes-montage.mp4\"\u003eWatch clip\u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://sourya-screenshots.s3.amazonaws.com/omnishot/readme/clips/clip-menu-bar-controls.mp4\"\u003e\n        \u003cimg src=\"docs/assets/readme/clip-menu-bar-controls.gif\" alt=\"Animated preview of Omnishot menu bar controls for latest screenshot actions\" width=\"720\"\u003e\n      \u003c/a\u003e\u003cbr\u003e\n      \u003cstrong\u003eMenu bar controls\u003c/strong\u003e\u003cbr\u003e\n      \u003csub\u003eLatest image, path-ref, S3 URL, and public link actions.\u003c/sub\u003e\u003cbr\u003e\n      \u003ca href=\"https://sourya-screenshots.s3.amazonaws.com/omnishot/readme/clips/clip-menu-bar-controls.mp4\"\u003eWatch clip\u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003ca href=\"https://sourya-screenshots.s3.amazonaws.com/omnishot/readme/clips/clip-langfuse-trace.mp4\"\u003e\n        \u003cimg src=\"docs/assets/readme/clip-langfuse-trace.gif\" alt=\"Animated preview of a Langfuse trace for the Omnishot screenshot naming and upload pipeline\" width=\"720\"\u003e\n      \u003c/a\u003e\u003cbr\u003e\n      \u003cstrong\u003eLangfuse trace\u003c/strong\u003e\u003cbr\u003e\n      \u003csub\u003ePipeline observability for screenshot naming and upload.\u003c/sub\u003e\u003cbr\u003e\n      \u003ca href=\"https://sourya-screenshots.s3.amazonaws.com/omnishot/readme/clips/clip-langfuse-trace.mp4\"\u003eWatch clip\u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## Docs\n\n- [Usage](docs/usage.md) - setup, modes, shortcuts, launchd, CLI options\n- [Agent instructions](docs/agent-instructions.md) - reusable `screenshot-info`\n  handling for Codex/Claude-style agents\n- [Architecture](docs/architecture.md) - pipeline diagram and data flow\n- [Tech stack](docs/tech-stack.md) - exact implementation details and citations\n- [Troubleshooting](docs/troubleshooting.md) - permissions, S3, clipboard, prompt evals\n- [Contributing](CONTRIBUTING.md) - local checks and PR expectations\n\n## Architecture At A Glance\n\n```mermaid\nflowchart TD\n    A[\"macOS screenshot folder\u003cbr/\u003e~/Pictures/Screenshots\"] --\u003e B[\"watcher.py\u003cbr/\u003edetect new PNGs + batch monitors\"]\n    B --\u003e C[\"DescribeImage.swift\u003cbr/\u003eVision OCR + Apple Foundation Models\"]\n    C --\u003e D[\"enrich.py\u003cbr/\u003esemantic filename + fallback logic\"]\n    D --\u003e E[\"Renamed local PNG\"]\n\n    E --\u003e F[\"history.py\u003cbr/\u003eSQLite recent captures\"]\n    E --\u003e G[\"upload.py\u003cbr/\u003eS3 object + presigned/public links\"]\n\n    F --\u003e H[\"menubar.py\u003cbr/\u003ehistory UI + shortcuts\"]\n    G --\u003e H\n\n    H --\u003e I[\"paste.py\u003cbr/\u003epath-ref text\"]\n    H --\u003e J[\"AppKit pasteboard\u003cbr/\u003eimage/file paste\"]\n    H --\u003e K[\"S3 URL/public link\"]\n\n    I --\u003e L[\"Remote coding agents\u003cbr/\u003escp into task artifacts\"]\n    J --\u003e M[\"Local app surfaces\u003cbr/\u003echat/docs/Finder/editor\"]\n    K --\u003e N[\"Web/social surfaces\u003cbr/\u003eshareable URL\"]\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fma08%2Fomnishot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fma08%2Fomnishot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fma08%2Fomnishot/lists"}