passy-ai/psh-now

Human approval for AI agents: one host, one key, one boolean.
An agent that needs a decision sends a short title and message to psh.now and blocks. You
tap Approve or Deny from one page, or answer in your own words, and the agent continues
with the result. It exists because agents stall in terminals nobody is watching.
Works with any agent that can run a shell command or make an HTTP request. No SDK, no MCP.
One page for every agent and every machine, including sandboxes you cannot attach to.
Self hostable: MIT licensed, two containers, three environment variables.
┌────────────┐ blocking POST / ┌────────────────┐ WebSocket ┌─────────┐
│ AI agent │ ───────────────────────► │ psh.now gateway │ ─────────────► │ phone │
│ (terminal) │ │ (Elysia + │ │ (PWA) │
│ │ ◄─────────────────────── │ Postgres) │ ◄───────────── │ │
└────────────┘ { approved: true } └────────────────┘ decision └─────────┘
The request is a title and a message, not only a shell command: a command to run, an action to
take, or a question to answer.
Where to go next
| I want to | Read |
| install it and answer my first request | Quick start |
| run it on my own server | docs/self-hosting.md or /self-hosting on any instance |
| understand the flow end to end | docs/how-it-works.md |
| call the API directly | HTTP API |
| paste a prompt into an agent | docs/prompt-templates.md |
| report a vulnerability | SECURITY.md |
| contribute | CONTRIBUTING.md |
## Stack
| Layer | Choice |
| Runtime | Bun |
| HTTP / WS | Elysia |
| Database | PostgreSQL + Drizzle ORM |
| Realtime | WebSockets + Postgres LISTEN/NOTIFY (multi-node fan-out) |
| Frontend | Zero-build PWA (vanilla ES modules + service worker) |
## Quick start
bash
# 1. install
bun install
# 2. configure
cp .env.example .env # then set DATABASE_URL / PUBLIC_BASE_URL
createdb psh.now # if it doesn't exist
# 3. migrate
bun run migrate
# 4. run the gateway
bun run dev # http://localhost:3000
Then, in the project you want to protect:
bash
bun /path/to/psh/cli/psh.ts init
This creates a workspace, prints your API key, renders a pairing QR code, and
writes a managed rule block into ./agents.md. Scan the QR with your phone to
open the PWA, tap Pair this device, and you're live.
### Or create a channel in the browser
Open /setup (e.g. ). It creates a workspace,
shows the API key once, and renders the pairing QR. Pairing a device lands on
the dashboard, which immediately sends a test approval so you can confirm
alerts and the full approve/deny loop without a terminal. The dashboard's
Send a test approval button repeats it anytime, and Invite mints fresh
pairing codes from any already-paired device.
### Manual check
bash
# commands, actions, and questions all use the same call
psh ask "Drop the users table and reseed?" --title "Database reset"
### Claude Code hook
Register the hook once in .claude/settings.json:
json
"hooks": {
"PreToolUse": [
"matcher": "Bash",
"hooks": [{ "type": "command", "command": "psh hook" }]
psh hook reads Claude's PreToolUse JSON on stdin and writes the
decision contract on stdout (permissionDecision: "allow" | "deny"). Every
Bash command waits for your phone. Non-Bash tools pass straight through. Set
PSH_SKIP_PATTERN to a regex to auto-allow read-only commands: