![\"Loopmark](\"assets/brand/loopmark-logo-readme.png\"){kind=logo}
\n\n \n
Loopmark helps AI agents ask humans at the right moment.
\n\nAgents can inspect code, run tests, read docs, and search the web on their own. Some questions still belong to a person: product tradeoffs, preferences, approvals, private context, ranked priorities, or secrets. Loopmark gives agents a structured cloud handoff without keeping a local process open.\n\n## Install The Skill\n\nInstall the Loopmark Agent Skill with Vercel's `skills` CLI:\n\n```bash\nnpx skills add andiedie/loopmark\n```\n\nThat is the only installation step most users need. You do not need to install Loopmark globally or add it to your project dependencies before using the skill.\n\n## How It Works\n\nWhen the agent needs human input, it creates a compact JSON question session and runs Loopmark once:\n\n```bash\nnpx --yes @andie/loopmark < questions.json\n```\n\nThe CLI encrypts the session, posts it to the Loopmark Worker, writes a local receipt file, prints a public fill URL, and exits. The human opens the URL, answers in the browser, clicks Copy answers, and pastes the copied Answer Text back to the agent.\n\nNon-secret answers and notes live directly in the pasted Answer Text so the conversation stays traceable. If the Answer Text says secrets were omitted, the agent downloads only the encrypted secret bundle:\n\n```bash\nnpx --yes @andie/loopmark secrets s_xxx\n```\n\nUse a self-hosted deployment with:\n\n```bash\nnpx --yes @andie/loopmark --base-url https://your-loopmark.example < questions.json\n```\n\nor set `LOOPMARK_BASE_URL`.\n\n## What Agents Should Ask\n\nLoopmark is for human decisions, not agent shortcuts. Use it for:\n\n- product direction and scope boundaries;\n- preferences between several reasonable options;\n- approvals before irreversible or risky actions;\n- private context unavailable in the repository;\n- ranked priorities;\n- sensitive values that should not appear in chat.\n\nIf the answer can be found through code, logs, tests, documentation, APIs, or web research, the agent should investigate first and should not ask through Loopmark.\n\n## Privacy And Secrets\n\nLoopmark uses end-to-end encryption for question sessions and secrets:\n\n- The public fill link contains only a `sessionCode` in the URL hash.\n- The Worker and R2 store encrypted question-session envelopes and encrypted secret bundles only.\n- Browser answers are copied as Answer Text. Non-secret answers and notes are visible in Answer Text; secret values are omitted.\n- The local receipt file contains the secret decryption key and should not be shared.\n- Secret answers are encrypted in the browser, uploaded as ciphertext, downloaded with `npx --yes @andie/loopmark secrets`, and written to a local `.env` file.\n\nThe agent receives a file path for secret answers, not the secret value, and should read it only when the task truly requires it.\n\n## Self-Hosting On Cloudflare\n\nThe default service is `https://loopmark.ssoo.fun`. Forks can deploy their own Worker and use `--base-url` or `LOOPMARK_BASE_URL`.\n\nCloudflare self-hosting uses a Worker plus a private R2 bucket, normally `loopmark-sessions`. The included GitHub Actions deploy workflow expects:\n\n- `CLOUDFLARE_ACCOUNT_ID`\n- `CLOUDFLARE_API_TOKEN`\n- optional `LOOPMARK_BASE_URL` GitHub Actions variable for the production environment URL\n\nFor bucket lifecycle, API token scope, custom domain setup, dry-run checks, and deployment verification, read the [Cloudflare operations guide](https://github.com/Andiedie/loopmark/blob/main/docs/operations/cloudflare.md).\n\n## For Agent Authors\n\nThe operational protocol lives in the repository-installed skill: [`skills/loopmark/SKILL.md`](https://github.com/Andiedie/loopmark/blob/main/skills/loopmark/SKILL.md) and [`skills/loopmark/references/protocol.md`](https://github.com/Andiedie/loopmark/blob/main/skills/loopmark/references/protocol.md). Humans normally do not need to write Loopmark JSON by hand; the installed skill teaches the agent to generate the session, run the CLI, wait for pasted Answer Text, and download omitted secrets only when needed.\n","readmeFilename":"README.md"}