shotctx

Minimal macOS CLI that returns the path of the latest screenshot on your Desktop.

Designed for AI coding workflows (Claude Code / Codex): stop manually dragging, saving, or pasting screenshots — just say "look at the latest screenshot" and let the AI call shotctx.

Why

When working with AI coding assistants, you often want them to "see" something on your screen. The current flow is tedious:

1. Take a screenshot (⌘ + Shift + 4)
2. Find the file on Desktop
3. Drag / paste it into the chat

With shotctx, the AI can just run one command and get the absolute path of the most recent screenshot. No manual steps.

Install

pnpm install
pnpm build
pnpm link --global

Verify:

shotctx --version

Usage

Print the absolute path of the latest image on your Desktop:

shotctx
# or explicitly:
shotctx latest

Example output:

/Users/you/Desktop/Screenshot 2026-05-07 at 11.30.21.png

Structured JSON (for AI agents):

shotctx latest --json

Example output:

{
  "path": "/Users/you/Desktop/Screenshot 2026-05-07 at 11.30.21.png",
  "modifiedAt": "2026-05-07T11:30:21.000Z",
  "sizeBytes": 123456,
  "extension": "png"
}

Supported formats

png, jpg, jpeg, heic, webp (case-insensitive).

Exit codes

| Code | Meaning | | ---- | ----------------------------------------- | | 0 | Success | | 1 | No image found, or Desktop not accessible |

Errors go to stderr, results go to stdout.

Claude Code / Codex Usage

Add this to your AGENTS.md or CLAUDE.md:

When the user says "看截图", "看最新截图", "look at screenshot", "check screenshot", or similar:

1. Run: shotctx latest --json
2. Use the returned path as the latest screenshot context.
3. Do not ask the user to manually drag, save, or paste screenshots unless the command fails.
4. If no image is found, ask the user to take a screenshot first, then run the command again.

Development

pnpm install
pnpm dev        # watch mode
pnpm typecheck
pnpm build
node dist/index.js latest --json