clipaste: Instructions file for Codex

AGENTS.md

Instructions for coding agents working with clipaste — both installing it for a user and contributing to this repository.

clipaste is a clipboard daemon that makes screenshot paste work in terminal AI tools (Claude Code, Codex CLI, Cursor CLI), locally and across SSH/WSL2 boundaries.

---

Part 1 — Installing clipaste for a user

The one command that tells you what to do

clipaste doctor --json

This is the entry point. It classifies the machine, runs the checks that are meaningful for that machine, and returns a fix command for anything broken. Do not guess at the state of a clipaste install — ask doctor.

{
  "version": "2.4.1",
  "os": "macos",
  "role": "clipboard-host",
  "status": "warn",
  "checks": [
    {
      "name": "daemon",
      "status": "ok",
      "detail": "daemon responding on 127.0.0.1:18340",
      "fix": null
    },
    {
      "name": "clipboard",
      "status": "warn",
      "detail": "no image staged yet — take a screenshot, then re-run doctor",
      "fix": null
    }
  ]
}

Field	Contract
role	clipboard-host / ssh-remote / wsl2 — decides which checks apply
status	worst of all checks: ok, warn, fail
checks[].status	ok / warn / fail
checks[].fix	a literal command to run, or null
exit code	0 usable (ok or warn), 1 broken, 2 bad arguments

A warn is not a failure. "No screenshot on the clipboard yet" is the normal state of a freshly installed machine — do not report it to the user as a problem, and do not try to fix it.

Decide where you are before installing anything

clipaste has two sides and they install differently. Getting this wrong is the single most common mistake.

        the machine holding the clipboard          the machine running the agent
        (where you press Cmd+Shift+4)              (where Claude Code runs)
        ─────────────────────────────              ─────────────────────────────
              macOS / Windows            ──HTTP──►      same machine
                                                        SSH remote
              runs the daemon                            WSL2 distro
              install: brew / install.ps1                install: run setup FROM the
                                                         clipboard host, not here