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 on macOS/Windows and across SSH/WSL2 boundaries. Graphical Linux hosts provide read-only PNG clipboard capture for the SSH bridge.

---

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 fix commands or guidance where available. 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 / unsupported-host decides which checks apply
status	worst of all checks: ok, warn, fail
checks[].status	ok / warn / fail
checks[].fix	a remediation command or guidance, or null when no single command applies
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.

Consumers of the JSON output must accept unsupported-host for platforms without a backend. Do not apply it to Linux as a whole: Linux host diagnostics must distinguish missing tools, missing session access, and missing compositor data-control from consumer helper or bridge failures.