convez.ai
AgenteAutomaçãoIntermediário
JunchenMeteor

AgentShot

JunchenMeteor/AgentShot

Screenshot bridge local-first para agentes de IA em terminal

Ver no GitHub
InicialPluginScore · de 0 a 100

Ponte 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/AgentShot

1 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

Estrelas
1
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
v0.1.6
Issues abertas
0
Contribuidores
2

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 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

CommandWhat it does
jcshot [capture]Capture/save a screenshot and copy a prompt.
jcshot clipboardSave the current clipboard image and copy a prompt.
jcshot watchWatch for new clipboard screenshots in the current terminal.
jcshot daemonRun the long-running clipboard watcher.
jcshot daemon installInstall the startup clipboard watcher.
jcshot daemon statusShow daemon install state, config, and log path.
jcshot daemon uninstallRemove the startup watcher.
jcshot sessionsList detected AI CLI processes.
jcshot lastReuse the latest saved screenshot.
jcshot dirPrint the screenshot directory.
jcshot --helpShow help.

Command modes at a glance:

ModeBest for
clipboardOne clipboard screenshot at a time.
watchTemporary watcher in the current terminal.
daemonLong-running watcher process.
daemon installStart watcher automatically on login.
lastReusing 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:

  • --paste copies the prompt first, then asks the OS to press paste in the active app.
  • macOS uses AppleScript to send Cmd+V through System Events.
  • Windows uses PowerShell to send Ctrl+V through 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

CapabilityWindowsmacOS
Save clipboard screenshotYesYes
Open screenshot tool from CLIYes, screen clipping fallbackYes, screencapture -i fallback
Clipboard watcherYesYes
Startup daemonYes, scheduled taskYes, LaunchAgent
Copy prompt to clipboardYesYes
Best-effort pasteYesYes
WSL path conversionYesNot applicable
AI session detectionYesYes
Global hotkey/menu bar helperPlannedPlanned
Remote SSH copyPlannedPlanned

Comparison

This is a high-level positioning table, not an exhaustive benchmark.

ToolWindows + macOSPure localTerminal-firstMulti-agentNo VS Code dependency
AgentShotYesYesYesYesYes
PaparazzimacOS focusedYesClaude Code focusedLimitedYes
Snap2LinkYesNo, creates share linksYesYesYes
VS Code image paste extensionsMixedYesVS Code terminal onlyMixedNo
Raycast terminal image pastemacOSYesUtility-drivenGenericRaycast 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

Ver o original no GitHub

Bom para

Relacionados