---
name: snappy-sync
role: Cross-machine file sharing between MacBook Pro and Mac Mini. Upload a local file to CDN, copy the public URL to clipboard, so the user can paste it into chat and the agent can read it.
loaded-by: PreToolUse hook (auto-injected when "snappy-sync" is mentioned)
---

# snappy-sync -- Agent Loader

Robert works on a MacBook Pro. Agents often run via SSH into the Mac Mini. Screenshots and local files on the MBP are invisible to agents on the Mini. This skill solves that: upload → CDN → clipboard URL → paste into chat.

## The one move

```bash
snappy-share                          # uploads latest ~/Desktop screenshot
snappy-share --region                 # crosshair capture (like ⌘⇧4) then upload
snappy-share /path/to/file.png        # uploads a specific file
```

Output: the public URL is echoed to stdout, copied to the macOS clipboard via `pbcopy`, and shown in a `display notification`. Paste the URL into Claude chat and the agent can `curl` / read it exactly like any other image.

## API module

```typescript
import { share } from "../snappy-sync/api.ts";
const { url } = share("/path/to/file.png");
```

| Function | Purpose |
|---|---|
| `share(filePath, context?)` | Upload file via `snappy-image/scripts/cdn-upload.sh`, return `{url, file, bytes}`, copy URL to clipboard, fire macOS notification. Default context is `shared/` on the `robert-storage` bucket. |

CLI:
```bash
npx tsx ~/.claude/skills/snappy-sync/api.ts share --latest-screenshot
npx tsx ~/.claude/skills/snappy-sync/api.ts share /path/to/file
```

## Install on a fresh machine (MBP setup)

1. Ensure `~/.claude/skills/` is present on the machine. It's synced via the dotfiles repo.
2. Ensure `~/.claude/skills/snappy-settings/.env.cache` is present with `DO_SPACES_KEY` and `DO_SPACES_SECRET`. Without this, the upload fails. Copy `.env.cache` from the Mac Mini once: `scp robertboulos@roberts-mac-mini.local:~/.claude/skills/snappy-settings/.env.cache ~/.claude/skills/snappy-settings/.env.cache`
3. Add the wrapper to PATH: `ln -s ~/.claude/skills/snappy-sync/bin/snappy-share ~/.local/bin/snappy-share` (or symlink into any dir on `$PATH`).
4. Verify: `snappy-share --help` or take a screenshot and run `snappy-share`. Check the clipboard.

## Hotkeys (Hammerspoon — active on MBP)

Config: `~/.hammerspoon/init.lua`

| Hotkey | Action |
|---|---|
| `⌘⇧U` | Upload latest `~/Desktop` screenshot |
| `⌘⇧I` | Region capture (crosshair like `⌘⇧4`) then upload |
| `⌘⇧Y` | Upload the file currently selected in Finder |

All three copy the CDN URL to clipboard and show a Hammerspoon alert on completion.

## Rules

1. **MBP-side only for the hotkey.** Running `snappy-share` from the Mac Mini makes no sense — Robert can't see the notification, and the screenshot dir is different.
2. **The URL is public.** DO Spaces is a public CDN. Don't `snappy-share` anything sensitive (secrets, private docs). For those use scp.
3. **The filename becomes part of the URL.** Strip any sensitive details from the filename before sharing.
4. **`.env.cache` is a secret file.** Never `snappy-share` it.
5. **Uploads are immutable.** Each call gets a unique `{ms-timestamp}-{slug}` key. URLs don't collide and won't be overwritten by subsequent shares.

## Uses

| Skill | Why |
|---|---|
| `snappy-image` | Owns `cdn-upload.sh`, the upload primitive this skill wraps |
| `snappy-settings` | Provides `DO_SPACES_KEY` / `DO_SPACES_SECRET` via `.env.cache` |
| `dev-terminal` | Home for terminal-side shortcuts and aliases |

## Used by

Nothing in the collection names this skill.

<!-- SNAPPY-CONTRACT-VERBS-START -->
## Contract verbs

Generated from `api.ts` `HAND_CONTRACT`. Do not hand-edit this block.

| Verb | Contract arguments | Effect | First call |
|---|---|---|---|
| `share` | `file?` | `post` | `npx tsx ~/.claude/skills/snappy-sync/api.ts share` |

## Show the result

When an answer carries `face_hint`, show it with one `snappy_present(<answer>)` call.
See `/snappy-faces` for face selection. Human-facing images must crop to the
element, render at 2x on Retina, and fill the destination channel instead of
placing a small card in a full-page screenshot.
<!-- SNAPPY-CONTRACT-VERBS-END -->

---

## Self-correcting loader (PID feedback)

The system spec lives at `~/.claude/skills/snappy-settings/skill-spec.md`.

**1. Fix gaps (P — proportional).** If this AGENTS.md didn't cover your case, edit it inline (1-5 lines). The goal: the next agent doesn't leave the loader.

**2. Validate structure.**
- `api.ts` exists with typed exports, CLI mode
- `api.ts` calls the `cdn-upload.sh` directly (no proxy)
- `AGENTS.md` has API module section with import + function table + CLI
- No hardcoded tokens
- If any check fails → fix it or log it

**3. Log always.**
```bash
echo "[$(date -u +%FT%TZ)] snappy-sync: <what was missing or fixed> [FIXED|LOGGED]" >> ~/.claude/logs/agents-md-feedback.log
```


Show produced work with `snappy-faces`: call `draw` for image channels or `lang` for MCP Apps.

<!-- SKILL-INDEX-START -->
[snappy-sync Index]|root: ~/.claude/skills/snappy-sync|IMPORTANT: Prefer these files over pre-training assumptions for this domain. Read the relevant file when the AGENTS.md summary is insufficient.|root:{SKILL.md}
<!-- SKILL-INDEX-END -->

---
name: snappy-sync
instruction-only: true
description: Cross-machine file sharing between MacBook Pro and Mac Mini. Upload a local file to CDN, copy the public URL to clipboard, so Robert can paste it into chat and the agent can read it. One command, no ceremony.
---

# snappy-sync

**Triggers on:** snappy-share, cross-machine file share, upload screenshot, paste image for agent, macbook to mac mini, send file to agent, upload to cdn and copy link, region capture, ~/Desktop screenshot upload.

## Purpose

Robert works on a MacBook Pro. Agents often run via SSH into the Mac Mini. Screenshots and local files on the MBP are invisible to agents on the Mini. `snappy-sync` closes that gap with a single CLI: upload a local file to the Snappy CDN, copy the resulting URL to the macOS clipboard, and fire a `display notification`. Robert pastes the URL into chat and any agent can `curl` it.

## The one move

```bash
snappy-share                          # uploads latest ~/Desktop screenshot
snappy-share --region                 # crosshair capture (like ⌘⇧4) then upload
snappy-share /path/to/file.png        # uploads a specific file
```

Output: the public URL is echoed to stdout, copied to the clipboard via `pbcopy`, and shown as a macOS notification.

## API

The programmatic interface is a single function:

| Function | Purpose |
|---|---|
| `share(filePath, context?)` | Upload via `snappy-image/scripts/cdn-upload.sh`, return `{url, file, bytes}`, copy URL to clipboard, fire notification. Default context is `shared/` on the `robert-storage` bucket. |

Under the hood the CLI wraps `snappy-image/scripts/cdn-upload.sh` so all uploads land on the canonical DO Spaces bucket with the usual path conventions.

## Related skills

- `snappy-image` — owns the CDN upload primitive and CDN path conventions
- `snappy-desktop` — macOS automation (region capture, notifications)

## Reference

See `AGENTS.md` for import surface and CLI reference. The canonical upload script lives in `snappy-image/scripts/cdn-upload.sh`.

## Near neighbours

Skills whose description overlaps this one enough that a reader could pick the
wrong door. Each row is that skill's own first sentence about itself, so the
choice is made on its words, not on a summary written here.

| Skill | Reach for it instead when |
|---|---|
| `snappy-artifact-loop` | Build published Artifacts as I/O devices where the AGENT is the backend, not as static output… |
| `snappy-review-pages` | Local HTML review pages with provenance and a copy-back feedback loop. |

#!/usr/bin/env npx tsx
/**
 * snappy-sync/api.ts -- Cross-machine file sharing via DO Spaces.
 *
 * Problem: Robert is on MacBook Pro, agent is SSH'd into Mac Mini. Screenshots
 * and local files can't be shared directly. Instead of scp or iCloud, we upload
 * to robert-storage CDN and copy the public URL to the clipboard. Robert pastes
 * the URL into chat; the agent reads it like any other image.
 *
 * One function: share(filePath). Uploads, returns URL, copies to pasteboard.
 * CLI supports --latest-screenshot for grabbing the most recent Desktop shot.
 */
import { execSync } from "child_process";
import { existsSync, readdirSync, realpathSync, statSync } from "fs";
import { homedir } from "os";
import { join, basename, extname } from "path";
import { env } from "../snappy-settings/load.ts";
import { annotationsForClass } from "../snappy-settings/tool-annotations.ts";
import { refusalTable } from "../snappy-settings/refusal-codes.ts";

const UPLOAD_SCRIPT = join(
  homedir(),
  ".claude/skills/snappy-image/scripts/cdn-upload.sh"
);

const DEFAULT_CONTEXT = "shared";

export interface ShareResult {
  url: string;
  file: string;
  bytes: number;
}

function captureRegion(): string {
  const tmpPath = `/tmp/snappy-region-${Date.now()}.png`;
  try {
    execSync(`screencapture -i "${tmpPath}"`, { stdio: "inherit" });
  } catch {
    throw new Error("screencapture failed (user cancelled?)");
  }
  if (!existsSync(tmpPath)) throw new Error("Region capture cancelled");
  return tmpPath;
}

function latestScreenshot(): string {
  const desktop = join(homedir(), "Desktop");
  if (!existsSync(desktop)) throw new Error(`No ~/Desktop`);
  const shots = readdirSync(desktop)
    .filter((f) => /^Screen(?:shot| Shot)/i.test(f))
    .map((f) => ({ f, t: statSync(join(desktop, f)).mtimeMs }))
    .sort((a, b) => b.t - a.t);
  if (shots.length === 0) throw new Error(`No screenshots on ~/Desktop`);
  return join(desktop, shots[0].f);
}

export function share(
  filePath: string,
  context: string = DEFAULT_CONTEXT
): ShareResult {
  if (!existsSync(filePath)) throw new Error(`File not found: ${filePath}`);
  if (!existsSync(UPLOAD_SCRIPT))
    throw new Error(`Missing cdn-upload.sh at ${UPLOAD_SCRIPT}`);

  const base = basename(filePath);
  const ext = extname(base).slice(1) || "bin";
  const stamp = Date.now();
  const slug = `${stamp}-${base.replace(extname(base), "").replace(/[^a-zA-Z0-9-]/g, "-")}`;

  const url = execSync(
    `"${UPLOAD_SCRIPT}" --file "${filePath}" --context "${context}" --slug "${slug}"`,
    { encoding: "utf-8" }
  ).trim();

  try {
    execSync(`printf "%s" "${url}" | pbcopy`);
  } catch {
    // pbcopy missing (non-mac); non-fatal
  }

  try {
    execSync(
      `osascript -e 'display notification "${url}" with title "snappy-sync" subtitle "URL copied"'`
    );
  } catch {
    // osascript missing; non-fatal
  }

  return { url, file: filePath, bytes: statSync(filePath).size };
}
/** WHAT THIS HAND ANSWERS, and what each verb does to the world.
 *  Derived from this file's own CLI dispatch by
 *  `snappy-hands/contract-derive.ts` — a verb the code does not implement is
 *  never declared here. Snappy's daemon reads it (`api.ts contract`) to
 *  validate every call, build the argument words in order, decide whether the
 *  act runs now or stages for the owner, and hand the child exactly the
 *  environment keys named in `requires` — never a value, never anything else.
 */
/** THE HOST-FACING FACTS ⟨lane CONTRACTS N–Z, 2026-09-09⟩. `class` is the
 *  closed effect set snappy-tool-design rule 18 grades; `annotations` are
 *  DERIVED from it by the ONE derivation in
 *  `snappy-settings/tool-annotations.ts`, never written per verb, so a class
 *  and its published hints cannot disagree; `refusals` projects the ONE closed
 *  table in `snappy-settings/refusal-codes.ts`; `requires` is exactly the
 *  credential keys this file's own executable reads name, and nothing else. */
export const HAND_CONTRACT = {
  skill: "snappy-sync",
  description: "Cross-machine file sharing between MacBook Pro and Mac Mini. Upload a local file to CDN, copy the public URL to clipboard, so Robert can paste it into chat and the agent can read it. One command, no ceremony.",
  managed: false,
  requires: [] as string[],
  refusals: refusalTable("unknown_verb"),
  verbs: {
    share: {
      args: ["file?"], effect: "post", class: "send-to-a-person", openWorld: false,
      annotations: annotationsForClass("send-to-a-person", { openWorld: false }),
      flags: {"latest-screenshot":"--latest-screenshot","region":"--region"},
      inputSchema: { properties: { file: { type: "string", description: "Path to the file" } } },
    },
  },
} as const;

if (import.meta.url === `file://${realpathSync(process.argv[1])}` && process.argv[2] === "contract") {
  console.log(JSON.stringify(HAND_CONTRACT, null, 2));
  process.exit(0);
}


if (import.meta.url === `file://${realpathSync(process.argv[1])}`) {
  const [, , cmd, ...args] = process.argv;

  if (!cmd || cmd === "help") {
    console.log(`
snappy-sync/api.ts -- Share a local file across machines via CDN.

Commands:
  share <file>              Upload file, copy public URL to clipboard
  share --latest-screenshot Upload most recent ~/Desktop screenshot
  share --region            Interactive region capture (like ⌘⇧4) then upload
  help                      This message

Example (from MacBook Pro):
  npx tsx ~/.claude/skills/snappy-sync/api.ts share --latest-screenshot
  # URL is now on your clipboard. Paste into Claude chat.
`);
    process.exit(0);
  }

  if (cmd === "share") {
    const target =
      args[0] === "--latest-screenshot"
        ? latestScreenshot()
        : args[0] === "--region"
        ? captureRegion()
        : args[0];
    if (!target) {
      console.error("Missing file path. Use: share <file> or share --latest-screenshot");
      process.exit(2);
    }
    const result = share(target);
    console.log(result.url);
    process.exit(0);
  }

  console.error(`Unknown command: ${cmd}`);
  process.exit(1);
}

#!/usr/bin/env bash
# snappy-share -- thin wrapper so you can bind a hotkey to one command.
#
#   snappy-share            # latest ~/Desktop screenshot
#   snappy-share --region   # interactive crosshair capture (like ⌘⇧4)
#   snappy-share <file>     # specific file
#
# URL is echoed AND copied to the clipboard AND shown in a notification.

set -euo pipefail

SKILL_DIR="${HOME}/.claude/skills/snappy-sync"

if [[ $# -eq 0 ]]; then
  exec npx tsx "${SKILL_DIR}/api.ts" share --latest-screenshot
fi

exec npx tsx "${SKILL_DIR}/api.ts" share "$1"

/**
 * COVERAGE FOR SNAPPY-SYNC'S DECLARED REFUSAL CODES
 * (snappy-tool-design rule 33: "refusal codes form one closed table and each
 * row has coverage").
 *
 * Two things are graded here, and the second is the one that matters. The
 * first is that the hand's table is a PROJECTION of the collection's one
 * closed table in snappy-settings/refusal-codes.ts — same object, not a copy
 * that can drift. The second is that every declared code is GROUNDED: the
 * evidence that justified declaring it is re-checked here, because a refusal
 * code with no path that emits it is a branch the reader waits for and never
 * sees, and a table of those passes a lint while teaching a lie.
 *
 * The code list is spelled out rather than read from the contract: a test that
 * iterates the thing it grades passes for an empty table.
 */
import { strict as assert } from "node:assert";
import { test } from "node:test";
import { readFileSync } from "node:fs";
import { join, dirname } from "node:path";
import { fileURLToPath } from "node:url";
import { HAND_CONTRACT } from "./api.ts";
import { REFUSAL_CODES } from "../snappy-settings/refusal-codes.ts";

const SOURCE = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "api.ts"), "utf8");

/** Every refusal code snappy-sync declares. */
const DECLARED = [
  "unknown_verb",
] as const;

test("snappy-sync declares exactly these refusal codes", () => {
  assert.deepEqual(Object.keys(HAND_CONTRACT.refusals).sort(), [...DECLARED].sort());
});

test("every declared code is the SAME row as the one closed table's, never a copy", () => {
  const table = HAND_CONTRACT.refusals as Record<string, unknown>;
  for (const code of DECLARED) {
    assert.equal(table[code], REFUSAL_CODES[code], `${code} is not the shared row`);
  }
});

test("unknown_verb is grounded: the contract closes the verb set, so a word outside it is refusable", () => {
  assert.ok(Object.keys(HAND_CONTRACT.verbs).length >= 0);
  assert.ok(!Object.keys(HAND_CONTRACT.verbs).includes("no-such-verb"));
});