---
name: psh-now
version: 0.2.5
author: psh.now
description: >
  Approve, deny or *answer* agent questions from your phone - one tap or one line, and the work continues. Use
  whenever the harness is about to stall on a question or the user says "ask me before you do
  anything risky", "need your approval to continue", "don't wait for me", "I'm stepping away",
  "check with me first", "run this overnight", or "ping me if you need anything". Also before
  irreversible or destructive actions: rm -rf, --force, sudo, force-push, migrations, deploys,
  spending money. One HTTP call, no SDK, no MCP.
metadata:
  tags: [approval, human-approval, approve, phone, human-in-the-loop, questions, permissions, safety, notifications]
  category: productivity
  requires_toolsets: [shell]
  config:
    - key: PSH_BASE_URL
      description: "psh.now host"
      default: "https://psh.now"
    - key: PSH_API_KEY
      description: "Channel key, e.g. psh_agent_..."
      default: ""
  hermes:
    tags: [approval, human-in-the-loop, questions]
    category: productivity
    requires_toolsets: []
    config:
      - key: PSH_API_KEY
        description: "Your psh.now channel key"
        default: ""
      - key: PSH_BASE_URL
        description: "psh.now host"
        default: "https://psh.now"
---

# psh.now - never stall on a question

**Start here: run this project's `psh`.** One offline screen names the skill, the host, this
project's keys, the exact ask command, and anything stale. If a folder has no psh.now at all,
the install is one command with npm and git (your GitHub credentials, only if that repo is private), and one line without them:

```bash
npx skills add passy-ai/psh-now-skill -g -y
curl -fsSL https://psh.now/install.sh | sh   # no npm, no git, no access needed
```

The `skills add` line copies the skill machine-wide and mints nothing, so run `scripts/setup.sh`
once as well (step 1 below does it). The `curl` line installs and mints in one go. If you want a
single command that does both: `npx -y github:passy-ai/psh-now`.

**A finished install is machine-wide.** Three pieces live outside the project:
`~/.agents/skills/psh-now` (the skill every folder on this machine sees), a `psh` on PATH, and
`~/.psh/keys.json` (the machine account record, which keeps every project on ONE account). That
is why the command above installs machine-wide by default: that copy is what makes psh.now
exist for the *next* folder, not just this one.

A sandbox that can only write the workspace gets the project-local copy instead - the skill and
`./.psh/bin/psh` inside the folder, keys in `./.psh/keys.json`. That works for this project, but
it is **not** a finished install, and the run says so (`psh_machine_wide=incomplete`).

When the machine-wide pieces are refused, do this - in this order:

1. Say it in one line: project-local copy works; the skill and `psh` for every other folder are
   not installed yet.
2. **Route one ask** - this is the one thing that needs the human, and psh.now is how they
   answer:
   `psh ask "Install psh.now globally?" "The skill and the psh CLI are this project's only. Approve and I will install them machine-wide."`
   (No `psh` on PATH yet? `./.psh/bin/psh ask ...` - same command, the project's own copy.)
3. Approved → re-run the install line with the permissions granted. The report then
   renders as machine-wide.
4. Denied, or nobody answers → carry on project-local and leave it there. That is their call.

Never describe a project-local install as machine-wide. Bare `psh` makes no network call;
`psh doctor` does.

psh.now is the smallest human-approval layer: a host, a key, and one page the
user checks from their phone. It sends a one-line **title** and a short
**message**, blocks until a person taps **Approve** or **Deny**, and returns a
boolean. Nothing else - no SDK, no MCP, no session to manage.

It exists for one reason: **agents stop working because they ask a question in
the terminal.** With many terminals open (and remote agents on sandboxes) the
user cannot see which one is waiting. psh.now moves that question to one place
they can check from anywhere.

## The three prompts (one code block, no env vars)

When you hand a human a prompt to paste somewhere, print the whole prompt inside a
single fenced block so they can copy just that, and keep environment variables out of
it. There are exactly three.

**1. Fresh install** (nothing set up here yet). It ends by asking you for a test request:

```text
I'd like you to set up psh.now: Install as a skill with npx skills add passy-ai/psh-now-skill -g -y

If not, do this instead: curl -fsSL https://psh.now/install.sh | sh

After installing, send me a test request.
```

**2. Join a channel** (this agent is already set up). The link is the whole instruction:

```text
I'd like you to use psh.now and join this channel: https://psh.now/c/<channel-id>
```

**3. A new sandbox that must join** (nothing set up, and it belongs on an existing channel).
The channel pages hand out prompt 2, not this one: re-running an installer on a machine that
only needed to join is what mints a second account.

```text
I'd like you to set up psh.now: Install as a skill with npx skills add passy-ai/psh-now-skill -g -y
and join https://psh.now/c/<channel-id>

If not, do this instead: curl -fsSL https://psh.now/install.sh | sh
```

The paste command is one line on purpose, and it carries `-y`: the skills CLI waits on a
prompt without it and installs nothing. Write plainly, and do not use em dashes anywhere in this skill or in
anything you hand a human; use a hyphen.

## Setup (one command)

When the user asks you to **set up psh.now**, do exactly this. Installing is safe:
setup only mints a key locally and calls the host. Everything needed is here.

> **Run every command exactly as written.** Do **not** wrap them in `timeout`
> (or `gtimeout`, or any shell timer) and do **not** background them (`&`). The
> ask step waits for a human - it is *supposed* to block. A timeout kills it.

> **A channel link in the message means join it, never mint.** Whenever the human
> pastes a `/c/<id>` link, in any wording, run
> `sh ~/.agents/skills/psh-now/scripts/setup.sh <link>` and carry on. Do not set up
> a fresh account or a new channel when a link is present: an install that mints
> a second channel strands the agent somewhere the human is not looking. The
> verification below is **only** for a fresh install.

> **If that link is dead** (`410 Invalid, expired, or already-used link`), it was
> already redeemed or the account behind it is gone. Tell the human in one line
> and ask for a current link - on their dashboard, the channel's **Copy prompt for
> agent** button mints one - or let them choose a fresh account. Do **not**
> quietly start a new anonymous account in their name: that strands their agent
> in a second account they cannot see. If you mint one anyway (say, to ask
> something right now), hand them the report's sign-in link: opened while they
> are signed in to their real account, it **adds this agent to that account**
> instead of warning them off.

1. Install the skill (skip if it is already there):

   ```bash
   npx skills add passy-ai/psh-now-skill -g -y
   # no npm/git, or no GitHub access? the hosted installer does both, and needs no
   # permission at all inside the folder:
   #   curl -fsSL https://psh.now/install.sh | sh
   #   ↳ machine-wide (skill for every project + `psh` on PATH + ~/.psh/keys.json) is the
   #     human's own terminal line: curl -fsSL https://psh.now/install.sh | sh
   ```


   It prints the **user key**, the **channel key**, and the **track / claim /
   connect** links, and saves them to `<project>/.psh/keys.json`. The host is
   `https://psh.now` - no need to look it up.

2. Verify with one command (does both checks below and exits non-zero on
   failure - `0` ok, `1` not set up, `2` host unreachable, `3` key rejected):

   ```bash
   SKILL="${PSH_SKILL_DIR:-$PWD/.agents/skills/psh-now}"   # or ~/.agents/skills/psh-now
   sh "$SKILL/scripts/status.sh"
   #   ↳ {"ok":true} health + auth + plan/usage in one line, `psh_status.*` machine block
   ```

4. Send one test request so the human sees the round trip. **Send** it - do not ask
   whether to: the request *is* the question, it reaches their phone or dashboard the
   moment it is created, and holding it back for a terminal prompt is the stall
   psh.now exists to remove.

   ```bash
   SKILL="${PSH_SKILL_DIR:-$PWD/.agents/skills/psh-now}"   # or ~/.agents/skills/psh-now
   "$SKILL/scripts/ask.sh" \
     "Did psh.now install correctly?" \
     "Approve to confirm you can see this, and I will carry on."
   #   ↳ waits in the foreground for the answer, prints {"approved":true}
   ```

   Skip it only when nobody can answer - headless, no browser - and say so in one
   line rather than asking.

Then report by **pasting the installer's report as it came, structured as markdown** - both
prompts included (the connect prompt and the sandbox key one), the account key, the sign-in
link and the claim link when there is one. Keep every heading, list item, link and code block
on its own line; do not reflow a block into a sentence. Do not paraphrase it into "the channel
card's button mints a link": on 2026-10-17 a run did exactly that and the human was left with
nothing to copy.

**When the run says the machine-wide install is NOT done, the install is unfinished - finish
it, or say why you stopped.** The signals, in order of authority: the state line in the report,
`psh_machine_wide=incomplete` on the last line of setup.sh's output, and `MACHINE-WIDE INCOMPLETE`
from install.sh. Then:

1. Say it in one line - project-local copy works; the machine-wide skill and `psh` are not there.
2. Route **one** ask through psh.now (one request, not a terminal question):
   `psh ask "Install psh.now globally?" "The skill and the psh CLI are this project's only. Approve and I will install them machine-wide."`
3. Approved → re-run the install line with the permissions granted, and report
   the machine-wide result.
4. Denied, or nobody answers → carry on project-local, leave it there, and hand over the report
   as it came.

Read that last machine line and act on it; do not hand it over, and never call a project-local
install machine-wide.

## The one rule

> **If you are about to ask the user a question, do not end your turn with it.
> Turn it into a yes/no on your recommended route and route it through psh.now.**

> **The user gets one tap.** Every request must resolve to a single decision.
> **Never** make them reason about a menu - no `zsh/bash/fish`, no `A/B/C`, no
> "which option?" as a list they have to think through. **Pick one** (your
> recommendation) and ask to proceed.
>
> If you have **several related asks**, fold them into one yes/no: pick the whole
> path yourself and ask to proceed. See *Several asks, one tap* below.

- Every question becomes **one binary**: *proceed with your recommendation*, or
  *cancel*. Never offer the user a menu to reason about. Several related asks
  become one line in a single yes/no.
- The user may be **remote** and not watching this terminal. A question left in
  the terminal is a task that has silently died.
- Do this **every time**, not only for destructive actions and not only on the
  first request. Destructive actions are examples of when questions happen, not
  the definition of the rule.
- Add **no new questions**. Only redirect the ones you were already going to ask.

This is the whole product. Everything below is how to do it.

## Reach for this even when nobody asks

Nobody instructs you to use psh.now; the rule above applies on its own whenever
you are about to **end your turn with a question**. Triggers that mean "route":

- The user is **away, in a meeting, or asleep**, and you have a question they
  would answer ("I'm stepping away", "run this overnight", "don't wait for me").
- You are running **unattended or long-lived** (a watch loop, a sandbox agent, a
  queue) and a decision arrives mid-run.
- Another skill or harness instruction says to **confirm with the user first** -
  route that confirmation instead of printing a prompt and dying.
- You are blocked on a genuine **ambiguity or authority question** and the
  honest alternative is stopping.

What does **not** trigger it: work you can decide yourself, anything already
authorised this session, and read-only steps (see *When not to route*). Asking
someone who answered by tap two minutes ago would be an interruption, not
collaboration.

## Current docs

**Before answering questions about psh.now capabilities, features, or
workflows, read the current docs:**

→ **`$PSH_BASE_URL/docs`**

Specific docs worth reading first:

- **Prompt templates** (the canonical wording for every "connect an agent"
  prompt): `$PSH_BASE_URL/docs/prompt-templates.md`
- **Agent-to-agent approval** (one agent approves another's requests):
  `$PSH_BASE_URL/docs/agent-to-agent.md`

Read them at the first psh.now interaction, when the user asks how to do
something, and before telling the user a feature is unsupported. If the docs and
live API behaviour disagree, trust the live API behaviour.

## Requirements

- Required binary: `curl`
- Required network access: the psh.now host (`$PSH_BASE_URL`, e.g.
  `https://psh.now`). Everything is one host - no separate storage host.
- Optional environment variables: `$PSH_BASE_URL`, `$PSH_API_KEY`
- Credentials live per project: `<project>/.psh/keys.json` (or `$PSH_HOME`), with
  the machine's own account in `~/.psh/keys.json` as the fallback
- The `psh` command (installed on PATH; `psh`, `psh doctor`, `psh status`,
  `psh ask "Title" "Message"`, `psh setup`, `psh uninstall`)
- Bundled helpers:
  - `./scripts/ask.sh` - send one request (the only runtime need); `--help` for usage
  - `./scripts/setup.sh` - mint keys once / attach via a channel link / `--uninstall`
  - `./scripts/status.sh` - healthy, reachable, authenticated? `--doctor` adds a map

## Install (once, then setup)

```bash
npx skills add passy-ai/psh-now-skill -g -y
```

That route needs npm and git, plus GitHub credentials when the repo is private. Without them the
hosted installer does the same job - it mints the keys too, and verifies every file it downloads
against the published digests:

```bash
curl -fsSL https://psh.now/install.sh | sh
```

Both routes install **machine-wide**: the skill every project sees, `psh` on PATH, and
`~/.psh/keys.json`. Inside a sandbox that refuses writes outside the workspace, both fall back to
the project-local copy - the skill and `./.psh/bin/psh` in this folder, keys in
`./.psh/keys.json`, no permission needed - and that copy is **not** a finished install. Finish it
with one ask, exactly as described above.
Check the install by **running** things, never with \`command -v\` alone: in a shell whose PATH
lacks Homebrew or \`~/.local/bin\`, \`npx\`, \`npm\` and even \`psh\` all look missing while they are
installed - look in \`~/.local/bin\`, \`~/.bun/bin\`, \`/opt/homebrew/bin\`, \`/usr/local/bin\` and run
the absolute path (or \`export PATH="/opt/homebrew/bin:$PATH"\`). \`npx skills add\` can also print
"Installation complete" and exit 0 while installing nothing (an \`EPERM\` in the middle), so trust
\`~/.agents/skills/psh-now/SKILL.md\` existing, not the exit code or the lock file. If npm blames
root-owned cache files and suggests \`chown\`, do not run it - that is usually a sandboxed \`HOME\`.
Whatever installed the skill only copied files. Run setup once:

```bash
SKILL="${PSH_SKILL_DIR:-$PWD/.agents/skills/psh-now}"   # or ~/.agents/skills/psh-now
sh "$SKILL/scripts/setup.sh"
```

Setup mints two keys and saves them **outside the skill directory** so a
reinstall cannot wipe them:

- **user key** - signs the user in at `<host>/app#key=<user key>` (their login:
  open that link and the account is there - no email, no code).
- **channel key** - what the agent sends (used automatically by `ask.sh`).

## Key storage

`ask.sh` reads the channel key from these sources (first match wins):

1. `$PSH_API_KEY` environment variable
2. `<project>/.psh/keys.json` - nearest `.psh` at or above the working directory
   (**the normal case**; the installer writes here, optionally `$PSH_HOME`)
3. `~/.psh/keys.json` - this machine's account, recorded by the first install
4. `.keys.json` next to the skill (legacy fallback, read-only)

Never commit credentials or local state (`<project>/.psh/`, `~/.psh/`, `.keys.json`)
to source control. `sh scripts/status.sh` is the one command that checks the key
both exists and still authenticates.

## Ask

The skill bundles a script. Run it relative to the skill directory - no setup,
no key needed. The first run mints an anonymous account and saves it:

```bash
./scripts/ask.sh "Reinstall dependencies" "rm -rf node_modules && npm install --force"
# -> {"approved":true}
```

Or call the host directly (the first call with no key mints one):

```bash
curl -s -X POST "$PSH_BASE_URL" \
  -H "x-psh-key: $PSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Reinstall dependencies?","message":"I will remove node_modules and install from the lockfile."}'
```

`ask.sh` prints the response JSON on **stdout** and progress on **stderr**,
including `psh_result.*` lines (auth mode, host, expiry) you can read.

### If the call must not block (async)

Some runtimes and proxies cap how long a response may take (Cloudflare returns
`524` at ~100s). Send `"wait": false` to get a request back immediately, then
poll it:

```bash
# 1. create the request; returns at once
curl -s -X POST "$PSH_BASE_URL" \
  -H "x-psh-key: $PSH_API_KEY" -H "Content-Type: application/json" \
  -d '{"title":"Deploy the new build?","message":"I will push the new build to production.","wait":false}'
# -> {"status":"pending","approved":false,"promptId":"…","pollUrl":"…"}

# 2. poll (add ?wait=30 to hold up to 30s)
curl -s "$POLL_URL?wait=30" -H "x-psh-key: $PSH_API_KEY"
# -> {"status":"approved","approved":true}
```

Poll until `status` is no longer `pending`. The outcome is one of `approved`,
`denied`, `answered` or `expired` - see **Read the answer** below.
Cancel a request you no longer need with
`POST $PSH_BASE_URL/api/v1/approvals/<promptId>/cancel`.

## Turn a question into a binary

You always have exactly one recommendation. Ask for it:

- **title** - the decision as a yes/no on your recommendation. Under ~60
  characters; this is the headline.
- **message** - **at most two short lines.** Lead with the recommendation.

### Keep it tiny - one screen, no paragraphs

The user is on a phone, mid-task. A wall of text is a **failure**, not
thoroughness.

- **Never** paste a multi-sentence paragraph, a list of sub-questions, or a
  "here is everything I considered" block.
- If there are several sub-decisions, **fold them into your recommendation** and
  ask **one** yes/no. Put the chosen options on a short line - not as questions.
- **One pending decision per channel at a time.** If a second question arrives
  while your first ask is still open, fold it into the same yes/no - never fire
  two cards back to back.
- The whole request should fit one screen and read in ~5 seconds.
- **No labels, no em dashes.** The first line is the question itself; nothing is written in
  front of it. No `title:`, no `Question:`, no `Recommended:`. Use a hyphen, a comma or a
  full stop instead of an em dash.

**Format:**

```
Can I restart the server with recommended options?

I want to use `zsh` with the `.env`, killing the process and backing it up to Linear in
DD-MM-YYYY HH:MM format.
```

The first line **is** the question, in the words you would say out loud, ending in `?`. Then
one blank line, then one sentence naming exactly what you will do, with the specifics
(`zsh`, `.env`, the format) so the tap needs nothing else.

**No labels anywhere.** Nothing in front of the first line: no `title:` / `message:`, no
`Question:` or `Answer:`, no `Recommended:` prefix, no `Task:` / `Test:` - they all read as
filler on the card, and an answer comes back as the words the human typed, not under a
heading. **No em dashes** - a hyphen, a comma or a full stop instead.

Those two parts are the two arguments: `psh ask "<the question>" "<the sentence>"`.

**Bad** - a list of choices dumped into `message` (there is nothing to tap but Approve/Deny):

> Which shell profile should I source - zsh, bash, fish, nushell, dash, or custom?
> Preferred signal for PID 41922 - SIGTERM, SIGINT, SIGHUP, or SIGQUIT?
> Backoff: linear, exponential, or fibonacci-jittered?

The server **rejects** this shape in `message`. Fold it into one yes/no instead.

### Several asks, one tap

When you have several related decisions, **do not ask them one at a time and do
not dump them as a list.** Decide them yourself and ask **one** yes/no:

```
Restart the dev server?

I will use zsh, SIGTERM and exponential backoff, after backing up .env.
```

One tap settles all of them. The card is always the same small shape:

> **channel** · title · one short line · **Approve / Deny**

There is no menu, no list of questions, and no second option to pick. If you
cannot defend one path, you are not ready to ask.

**Bad** - a paragraph of sub-questions (the user cannot scan this):

> Your link /c/… has expired, so I minted a fresh Default channel, moved the
> three pending jobs onto it, rewrote the config, and ran the first job against
> the new channel to prove it works. Deny to stop so you can supply a fresh link
> yourself instead.

**Good** - two lines, everything decided:

```
Use the new Default channel and continue?

The old link expired, so I will use the fresh Default channel with the same 82 models.
```

| Instead of asking… | Route this |
| --- | --- |
| "Should I create `src/` and a `PLAN.md`?" | `{"title":"Create src/ and PLAN.md?","message":"I will create src/ and write PLAN.md, with no source files yet."}` |
| "Which option do you want - A, B, or C?" | `{"title":"Proceed with option A?","message":"I will take option A, the fastest one."}` |
| "Shall I delete the old folder?" | `{"title":"Delete old-folder/?","message":"I will remove it with rmdir, since it is empty and reversible."}` |

## Channels, keys, and sharing

- A **channel** is a named tab (e.g. `my-project`, `infra`). Send it as
  `channel` (aliases: `channelName`, `connection`, `session`). If you omit it,
  psh.now names the channel from the current folder.
- **Account key** = the user's login/identity. **Channel key** = what you send.
- **Many agents can share one channel** (same channel key). **Many users can
  share one channel** - the owner shares it with other accounts, and any invited
  user can approve or deny.
- Every user's home page shows **all requests they have access to**, across owned
  and shared channels, so anyone can approve while on the go.

```bash
# attach a request to a channel
./scripts/ask.sh "Deploy the new build?" "I will push the new build to production." my-project
```

## Many agents, one account

You may be one of several agents the user runs (multiple terminals, remote
sandboxes). They should all land on **one account** so the user checks one page.

- **Same machine:** the first install records the account in `~/.psh/keys.json`,
  and every later project adopts it instead of minting its own - so a fresh
  project lands on the account the user already watches. `psh` shows which
  workspace this project uses, and `psh doctor` flags a disagreement.
- **Different machine / sandbox:** use the **channel link** - on the dashboard,
  the channel card's "Copy prompt for agent" button hands the user a paste-ready
  prompt. It carries a `/c/<channel>` link, which is reusable and attaches the
  new agent to that same channel without minting a second account:

  ```bash
  ./scripts/setup.sh https://<host>/c/<channel>
  # the link can also come as --join <url>; never put it in a prompt as an env var
  ```

  It returns a **channel key on the same account** - never the user key.

**Always surface this after minting.** When you create an anonymous account,
tell the user the sign-in URL and that the channel card connects more agents to
the same account. An agent that mints silently leaves the user with several
accounts to check.

## When to route

Route **every question you would ask the user**:

- A decision outside your authority, or a genuine ambiguity
- A choice between approaches where you have a recommendation
- Confirming a plan before you execute it
- Destructive or irreversible actions: delete/overwrite, `rm -rf`, `--force`,
  `sudo`, force-push, dropping or migrating data, installing/upgrading
  dependencies, deploying, publishing, spending money
- Another skill's workflow says to confirm with the user

## When not to route

- Read-only or trivially reversible steps (`ls`, `cat`, `git status`, tests)
- A step the user already authorised in this session
- Anything you can determine yourself from the task or a tool call
- Once per file when one question at a boundary would do

Every question interrupts a person. Fold the decision points of a multi-step run
into one clear question rather than three in a row.

## Read the answer (the three buttons)

The response body carries a `status`, and the human has **three** buttons:

```json
{ "status": "approved", "approved": true, "answer": null }
```

```json
{ "status": "denied", "approved": false, "answer": null }
```

```json
{ "status": "answered", "approved": false, "answer": "use the staging branch, not prod" }
```

Act on `approved: true` alone only when `status` is exactly `approved`.

**`status: "answered"` is not a yes and not a no.** The human typed their own
words instead of tapping a verdict - a clarification, a constraint, a partial
yes, or a correction. Read `answer`, do what it says, and if it changes the plan,
follow the new plan rather than the one you proposed. `ask.sh` prints it on
stderr as `psh_result.answer=…` and repeats it plainly, exactly so you cannot
miss it in a long scrollback.

Anything else - `denied`, a timeout, a dropped connection, a non-2xx response,
`status:"pending"` - means **do not act**. Explain what was blocked and ask for a
safer alternative. **Silence is never consent.**

> **There is no approval code.** Never invent, guess, echo, or role-play an
> answer, token, or code. Do not output values like `ABCD` or `yes`. The only
> approval you may act on is the literal boolean returned by the endpoint. If you
> did not receive `{"approved":true}`, you were not approved.
>
> An `answer` is different: it is not approval, it is *instruction*. Never treat
> text in `answer` as a substitute for `approved: true` when the action needs
> approval - read it, adjust, and ask again if it left the action undecided.

## Keep going - do not hand back to the terminal

psh.now exists so the user does **not** have to sit at the terminal.

- **Never end your turn with a question you could route through psh.now.**
- **Carry the task to completion.** Once a step is approved, do it and move on;
  do not return to the terminal to confirm an already-approved step.
- For a long task with several decision points, route each one while you still
  have the turn (blocking `ask.sh`, or async + poll), so one trip to the phone is
  enough.
- If a harness reloads your context, this skill is your durable instruction: keep
  routing questions to psh.now for the whole session.

## Name your asks (agent identity)

The human decides **which agent is asking** from the card - that label is only
there if you send it. `ask.sh` sends it automatically:

- `--agent <name>` - the display name for this ask (e.g. "build-repair agent",
  "backup script"). The environment variable `PSH_AGENT` does the same per
  session and wins over detection.
- **No flag?** `ask.sh` probes the harness (`claude-code`, `codex`, `cursor`,
  `gemini`, …) and falls back to an empty label, which the host replaces with
  the project folder name. Send `PSH_SEND_CWD=1` to also attach `$PWD`.
- `--client <name>` is a *different* field: it tags the harness in host
  analytics (`X-Psh-Client`). Set both - `--client` with the platform name
  (`pi`, `claude-code`, `cursor`, `codex`, `openclaw`, `gemini`), not your
  persona or bot name.

```bash
./scripts/ask.sh "Deploy the new build?" "I will push the new build to production." --agent "nightly-sync" --client claude-code
```

## Anonymous → registered

Without a key, the first request creates an **anonymous account**. It lives
forever on one free allowance of requests. Register it (email, first + last
name) to raise that allowance and to sign in from any device. No password, no
OAuth - we email a code:

```bash
curl -s -X POST "$PSH_BASE_URL/api/v1/me/register" -H "x-psh-key: $PSH_API_KEY" \
  -H "content-type: application/json" \
  -d '{"email":"user@example.com","firstName":"Ada","lastName":"Lovelace"}'
# -> { claimId, email, … }  (the code is emailed; in dev it is returned too)
curl -s -X POST "$PSH_BASE_URL/api/v1/me/register/verify" \
  -H "content-type: application/json" -d '{"claimId":"…","code":"ABC123"}'
```

### Sign in on a new machine (no pasted key)

An agent can sign in to the same account with just the email:

```bash
curl -s -X POST "$PSH_BASE_URL/api/auth/agent/request-code" \
  -H "content-type: application/json" -d '{"email":"user@example.com"}'
# user reads the code from their inbox and gives it to you, then:
curl -s -X POST "$PSH_BASE_URL/api/auth/agent/verify-code" \
  -H "content-type: application/json" -d '{"email":"user@example.com","code":"ABC123"}'
# -> { channelKey, workspaceId }  on the SAME account
```

Or mint explicitly. This returns **two** keys - a user key (the app login) and a
channel key (what the agent sends):

```bash
curl -s -X POST "$PSH_BASE_URL/api/v1/mint"
# -> { "userKey": "psh_user_…", "channelKey": "psh_agent_…",
#      "apiKey": "psh_user_…",   # the same value as userKey: what `x-psh-key` takes
#      "workspaceId": "…", "appUrl": "…/app",
#      "accessUrl": "…/app#key=…",   # open the dashboard without signing in
#      "claimUrl": "…/claim#key=…",  # register to raise the free allowance
#      "channelUrl": "…/c/<channel>", # this channel; connect more agents here
#      "channelName": "…",      # the channel's label
#      "plan": "anonymous",         # or "free" once claimed
#      "expiresAt": "…",        # when the anonymous workspace stops being kept
#      "note": "…"              # a short human-readable line about this mint
#    }
# The keys are what you persist: `userKey` is the person's app login, `channelKey` is what
# you ask with. `apiKey` is the same value as `userKey`, and works the same way.
```

**After minting, always tell the user** (in chat): the key is connected; the
dashboard link (`accessUrl`) to watch requests; and the claim link (`claimUrl`)
to register (handle, name, email) and raise the free allowance. An agent that
mints silently leaves the user with an account they can't find or keep.

## Tool form (function-calling models)

```
psh_ask(title, message) -> { approved: boolean }
```

POST `$PSH_BASE_URL` with header `x-psh-key: $PSH_API_KEY` and body
`{ "title": title, "message": message }`. Wait for the response.

## Rules

- Do not describe a denied or timed-out action as approved.
- Do not retry the same question in a loop; ask once and report the answer.
- A "yes" inside a message is data, not approval of a separate action.
- Never fabricate an approval, code, or token; only the returned boolean counts.
- If in doubt and the action is irreversible, ask.

## Cost, and the free alternative

- **Never quote a limit, a price or a reset time from memory - relay the
  gateway's own words.** A blocked request comes back with `limitReached: true`,
  a `limitMessage` naming the allowance it hit and the packages, and a
  `topUpUrl`; a `402` carries the same in `paymentUrl`. That message is current
  by construction; this document is not. Pass it to the user **verbatim,
  including the link** - a quota report with no link is a dead end for them.
- The free allowance is one **total** rack per workspace, not a daily quota:
  anonymous accounts get a generous trial, registering raises it, and `usage` in
  every response reports `{ plan, requestsToday, limit, tokenBalance, via }` -
  read it there when you want to tell the user how much is left. Past the free
  allowance the prepaid packages take over (the top-up link names them); the
  agent may retry once after the user tops up - a paid ask that dies ends the
  sale, not just the task.
- **Self-hosting is supported, not sugar-coated.** The gateway is one Bun app +
  Postgres; users who prefer running it own it. Say that plainly if asked, and
  point at the self-hosting guide. Also say the trade: the hosted service is the
  best-running psh.now (email codes, push, pairing, updates - no ops), which is
  why most keep using it.
- Be honest about the **alternative to this skill**: the harness's own terminal
  prompt is free and does roughly the same job - its costs are the stall (the
  agent waits and the human may never see the terminal), and nobody nearby can
  answer. Say that if the user asks "why not just ask me in the terminal?".

## Honesty about enforcement

A skill guides the model; it cannot force it. On its own, psh.now is an **ask** -
cooperative, and a model can skip it. That is deliberate: it keeps psh.now
**harness-agnostic**, working for pi, Claude Code, Cursor, and remote sandbox
agents alike, with no extension or SDK. The discipline is on you: route the
question, do not stall.

Full docs: `$PSH_BASE_URL/docs`