AgentShot
JunchenMeteor/AgentShot
Screenshot bridge local-first para agentes de IA em terminal
Ver no GitHubPonte de captura de tela local-first para agentes de IA em terminal como Claude Code, Aider e Gemini CLI. Captura screenshots da área de transferência, converte em prompts prontos para IA e envia para o agente ativo sem upload em nuvem.
Instalação
npx convez-ai JunchenMeteor/AgentShot1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Analisar bugs de UI com agentes de IA via terminal
- Integrar screenshots em workflows de Aider, Claude Code e Gemini CLI
- Capturar e processar imagens localmente sem exposição em nuvem
Veredito

Ferramenta muito prática para desenvolvedores que usam agentes de IA em terminal. Resolve um atrito real (captura manual de screenshots) com abordagem local-first e suporte a múltiplos agentes. Código bem mantido, npm package ativo.
README
A tradução para o português deste README ainda está na fila.
AgentShot
Local-first screenshot bridge for Claude Code, Codex CLI, Aider, Gemini CLI, OpenCode, and terminal AI agents.
clipboard screenshot -> local file -> AI-ready prompt -> clipboard or active terminal
AgentShot is for developers who use AI coding agents from the terminal and need to show screenshots without manually saving, renaming, moving, uploading, or copying image paths.
Table of Contents
- Quick Start
- Install
- Why AgentShot
- Common Workflows
- Commands
- Supported AI Tools
- Storage and Privacy
- Daemon
- Platform Coverage
- Comparison
- Quality
- Status
Quick Start
Install globally:
npm install -g jcagentshot
Use one screenshot from the clipboard:
# macOS: Cmd+Shift+Ctrl+4, select a region, then:
jcshot clipboard --ask "Analyze this UI bug"
Keep a watcher running for repeated screenshots:
jcshot daemon install --ask "Analyze this screenshot"
jcshot daemon status
After that, take a clipboard screenshot and paste the generated prompt into Claude Code, Codex, Aider, Gemini CLI, OpenCode, or another terminal agent.
Example generated prompt:
Analyze this screenshot: /Users/you/.agentshot/shots/shot-20260608-224138.png
Naming note: the product is AgentShot, the npm package is jcagentshot, the CLI command is jcshot, and local data remains under ~/.agentshot.
Install
npm is the primary distribution channel:
npm install -g jcagentshot
The global install does not start a background service automatically. Enable background clipboard watching explicitly:
jcshot daemon install --ask "Analyze this screenshot"
Run without a global install:
npx jcagentshot
Install from GitHub for preview builds:
npm install -g github:JunchenMeteor/AgentShot
Install from source:
git clone https://github.com/JunchenMeteor/AgentShot.git
cd AgentShot
npm install
npm link
Skip postinstall guidance:
AGENTSHOT_SKIP_POSTINSTALL=1 npm install -g jcagentshot
If global install fails with a permission error, prefer a user-writable npm prefix:
npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"
npm install -g jcagentshot
Windows user-writable prefix:
npm config set prefix "$env:USERPROFILE\.npm-global"
Then add %USERPROFILE%\.npm-global to your user PATH.
Automated fallback installers:
# Windows
irm https://raw.githubusercontent.com/JunchenMeteor/AgentShot/main/install.ps1 | iex
# macOS/Linux
curl -fsSL https://raw.githubusercontent.com/JunchenMeteor/AgentShot/main/install.sh | bash
These scripts check Node.js, switch npm global installs to a user-writable prefix when needed, update PATH, install AgentShot, and then ask you to explicitly enable the daemon.
If you prefer to inspect the Windows script before running it:
irm https://raw.githubusercontent.com/JunchenMeteor/AgentShot/main/install.ps1 -OutFile install.ps1
notepad .\install.ps1
powershell -ExecutionPolicy Bypass -File .\install.ps1
As a temporary fallback on macOS/Linux, you can use sudo, but a user-writable npm prefix is preferred:
sudo npm install -g jcagentshot
Why AgentShot
Terminal AI tools can often inspect local image files, but terminals usually cannot pass clipboard images directly into CLI apps. The normal workflow becomes:
take screenshot -> save/export -> rename -> move -> copy path -> write prompt
AgentShot makes the workflow clipboard-first:
take screenshot to clipboard -> AgentShot saves it -> AgentShot copies an AI-ready prompt
Use AgentShot when:
- You use Claude Code, Codex CLI, Aider, Gemini CLI, OpenCode, or similar tools in a terminal.
- You frequently need to show UI bugs, layout issues, logs, dashboards, or app screenshots.
- You want screenshots to stay local instead of being uploaded to an image host.
- You want one workflow that works across multiple terminal agents.
Do not use AgentShot if your AI tool already supports direct image paste in the place where you work.
Common Workflows
macOS clipboard-first:
# Cmd+Shift+Ctrl+4, select an area, then:
jcshot clipboard --ask "Analyze this UI bug"
Windows clipboard-first:
# Win+Shift+S, select an area, then:
jcshot clipboard --ask "Analyze this UI bug"
Run a watcher in the current terminal:
jcshot watch --ask "Analyze this screenshot"
Install the watcher as a startup daemon:
jcshot daemon install --ask "Analyze this screenshot"
jcshot daemon status
Use Codex from WSL:
jcshot clipboard --tool codex --wsl --ask "Find the visual bug"
Reuse the latest screenshot:
jcshot last --tool aider --ask "Review this screenshot"
Use an existing image file:
jcshot --path ./error.png --tool opencode --ask "Explain this error"
Copy and try to paste into the active terminal:
jcshot clipboard --tool claude --ask "Inspect this page" --paste
Interactive fallback:
jcshot --ask "What is wrong with this layout?"
On macOS this runs screencapture -i. On Windows it opens screen clipping if the clipboard does not already contain an image.
Commands
| Command | What it does |
|---|---|
jcshot [capture] | Capture/save a screenshot and copy a prompt. |
jcshot clipboard | Save the current clipboard image and copy a prompt. |
jcshot watch | Watch for new clipboard screenshots in the current terminal. |
jcshot daemon | Run the long-running clipboard watcher. |
jcshot daemon install | Install the startup clipboard watcher. |
jcshot daemon status | Show daemon install state, config, and log path. |
jcshot daemon uninstall | Remove the startup watcher. |
jcshot sessions | List detected AI CLI processes. |
jcshot last | Reuse the latest saved screenshot. |
jcshot dir | Print the screenshot directory. |
jcshot --help | Show help. |
Command modes at a glance:
| Mode | Best for |
|---|---|
clipboard | One clipboard screenshot at a time. |
watch | Temporary watcher in the current terminal. |
daemon | Long-running watcher process. |
daemon install | Start watcher automatically on login. |
last | Reusing the most recent screenshot. |
Supported AI Tools
AgentShot uses prompt templates instead of provider APIs. That keeps it compatible with any CLI agent that can access local files.
--tool is optional. If you omit it, AgentShot uses the generic prompt template. Add --tool codex, --tool claude, or another template only when you want wording tailored to a specific agent.
First-class templates:
- Claude Code
- Codex CLI
- Aider
- Gemini CLI
- OpenCode
- Generic terminal agents
Storage and Privacy
AgentShot never uploads screenshots. It has no telemetry, image host, or cloud account.
Files are saved under:
macOS/Linux: ~/.agentshot/shots
Windows: %USERPROFILE%\.agentshot\shots
If the home directory is not writable, AgentShot falls back to Pictures/agent-shots, then the system temp directory. Set AGENTSHOT_DIR to force a specific location:
AGENTSHOT_DIR=/path/to/shots jcshot
Native terminal paste notes:
--pastecopies the prompt first, then asks the OS to press paste in the active app.- macOS uses AppleScript to send
Cmd+Vthrough System Events. - Windows uses PowerShell to send
Ctrl+Vthrough Windows Forms. - Paste is best-effort because terminal apps and OS security models differ.
Recommended daily workflow:
1. Install AgentShot globally, or run daemon install.
2. Take a clipboard screenshot with the OS shortcut.
3. Return to Claude Code/Codex and paste.
This avoids unsafe automatic paste into the wrong window while still removing manual file naming and path copying.
Daemon
AgentShot's daemon is a resident clipboard watcher. It does not upload screenshots and does not inject text into terminal windows by default.
jcshot daemon install --ask "Analyze this screenshot"
jcshot daemon status
jcshot daemon doctor
jcshot daemon uninstall
daemon install is explicit. npm install does not register or start background services. Before installation, AgentShot prints the daemon scope: it watches clipboard image changes only, does not read text clipboard content, does not upload files, and does not inject text into terminal windows.
Startup integration:
- macOS: LaunchAgent at
~/Library/LaunchAgents/com.junchenmeteor.agentshot.plist. - Windows: user logon scheduled task named
AgentShot. The watcher uses one hidden clipboard helper process instead of repeatedly spawning PowerShell for each poll.
Logs and config:
~/.agentshot/daemon.log
~/.agentshot/daemon.json
jcshot daemon doctor prints the installed task/agent state, config path, log path, screenshot directory, and safety-scope checks.
Platform Coverage
| Capability | Windows | macOS |
|---|---|---|
| Save clipboard screenshot | Yes | Yes |
| Open screenshot tool from CLI | Yes, screen clipping fallback | Yes, screencapture -i fallback |
| Clipboard watcher | Yes | Yes |
| Startup daemon | Yes, scheduled task | Yes, LaunchAgent |
| Copy prompt to clipboard | Yes | Yes |
| Best-effort paste | Yes | Yes |
| WSL path conversion | Yes | Not applicable |
| AI session detection | Yes | Yes |
| Global hotkey/menu bar helper | Planned | Planned |
| Remote SSH copy | Planned | Planned |
Comparison
This is a high-level positioning table, not an exhaustive benchmark.
| Tool | Windows + macOS | Pure local | Terminal-first | Multi-agent | No VS Code dependency |
|---|---|---|---|---|---|
| AgentShot | Yes | Yes | Yes | Yes | Yes |
| Paparazzi | macOS focused | Yes | Claude Code focused | Limited | Yes |
| Snap2Link | Yes | No, creates share links | Yes | Yes | Yes |
| VS Code image paste extensions | Mixed | Yes | VS Code terminal only | Mixed | No |
| Raycast terminal image paste | macOS | Yes | Utility-driven | Generic | Raycast required |
Session Detection
jcshot sessions lists likely terminal AI CLI processes. This is read-only and exists to support future explicit injection workflows without making direct injection the default behavior.
Quality
Run the full local validation suite:
npm run validate
This checks syntax, unit tests, help output, and npm package contents. CI runs the same validation on Windows, macOS, and Linux across Node 18, 20, and 22.
Status
AgentShot is currently an MVP. The stable baseline is:
clipboard image -> save file -> render prompt -> copy prompt
Automatic paste is best-effort. Clipboard watch is implemented as a CLI watcher; global hotkey and menu bar helpers are planned.
License
MIT