AI agent workflow guide

Send macOS screenshots to AI coding agents.

Remote AI coding agents are powerful, but screenshots usually start life on your Mac. This guide shows the manual SSH path and the faster filefling loop for getting local images and files onto the remote machine where your agent can actually read them.

Download beta for macOS zip Read setup docs

Evergreen guide · macOS screenshots · SSH/SFTP · remote AI coding agents

Problem

Why screenshots are awkward for remote agents

Many AI coding tools run inside a terminal, tmux session, SSH shell, or remote devbox. The agent can inspect files on that remote machine, but it cannot automatically see a screenshot sitting in your local macOS Desktop or Screenshots folder.

That creates a tiny but repetitive handoff problem: capture the screenshot locally, upload it to the remote machine, copy the remote path, then paste that path into the AI coding agent with enough context to make it useful.

This workflow fits

  • Claude Code or other CLI coding agents
  • Remote shells and tmux sessions
  • Tailscale or VPS devboxes
  • SSH-first developer workflows
  • Design/debug screenshots
  • Any local file the agent needs to inspect

Manual option

The manual scp workflow

You do not need filefling to solve this. The standard Unix approach is to upload the screenshot with scp, rsync, or sftp, then paste the remote path into your agent.

01

Capture the screenshot

Use the built-in macOS screenshot shortcut and note where the image was saved.

⌘⇧4
02

Upload it to the remote machine

Use scp, rsync, or sftp to move the file to the machine where your AI coding agent is running.

scp ~/Desktop/Screenshot.png devbox:~/shared/
03

Paste the remote path into the agent

Use the path that exists on the remote machine, not the local macOS path.

Please inspect this screenshot: /home/brad/shared/Screenshot.png

This works well, but the friction adds up when you are iterating on UI bugs, visual changes, logs, generated images, or local files that need to be visible to a remote AI agent.

Faster loop

The filefling workflow

filefling turns the repeated screenshot handoff into a menubar action. It uploads over SSH/SFTP to your chosen destination and immediately copies the text you want to paste into your AI coding agent.

step

Configure an SSH destination once

Point filefling at the same server, devbox, or Tailscale machine where your CLI agent runs.

step

Preview and send from the menubar

Press the hotkey or click Send. filefling finds the latest screenshot, previews it, and uploads it over SFTP.

step

Paste the ready-to-use prompt

The clipboard can contain a raw path, Markdown image, or complete AI-agent prompt with the remote path filled in.

Please inspect this screenshot and tell me what UI issue you see:
{{remotePath}}

Prompts

Useful clipboard templates for AI agents

The best prompt depends on your agent and task. filefling templates let you keep a reusable instruction and fill in the uploaded file path each time.

Inspect screenshot Please inspect this screenshot: {{remotePath}}
UI bug report This screenshot shows the bug. Identify the likely frontend issue: {{remotePath}}
Markdown image ![{{filename}}]({{remotePath}})
Generic file handoff Please inspect this uploaded file: {{remotePath}}

Security

Keep the handoff explicit

filefling uploads to the SSH server you configure. It does not choose an AI provider, upload to filefling-owned storage, or make your screenshot public. For beta users, the current app build is unsigned, so macOS Gatekeeper may ask you to approve the first launch.

The app also performs trust-on-first-use host-key verification and warns if a trusted host key changes. For setup details, see the host-key trust docs.

FAQ

Questions about screenshots and AI coding agents

Does this work with Claude Code, Codex CLI, or other terminal agents?

Yes. filefling is tool-agnostic. If the agent can read a file path on the remote machine, filefling can upload screenshots and files there over SSH/SFTP.

Does filefling send my screenshots to an AI provider?

No. filefling uploads to the SSH destination you configure. What happens after that depends on the AI tool or workflow you paste the path into.

Can I send files that are not screenshots?

Yes. Screenshots are the fast path, but you can drag any file into filefling and upload it to the active destination.

Why not just use scp?

scp is great for one-off transfers. filefling is for the repeated loop: capture, upload, copy the correct remote path or prompt, and paste into the agent.