# Plush for Codex

Goal: send encrypted Plush notifications from Codex stop hooks, scripts, or agents with minimum context.

## Install
```sh
npm install -g easypush
# or use without install:
npx -y easypush --help
```

Set the API key outside tracked files:
```sh
export PLUSH_API_KEY="push_..."
export PLUSH_BASE_URL="https://api.easypush.app" # optional
plush login "$PLUSH_API_KEY"
```

## Stop Hook
Use the official hook from the `easypush` package. It reads Codex Stop-hook JSON from stdin, uses your saved `plush login`, sends with `app.name = "Codex"` and a Codex icon, uses the Codex thread title as the notification title, keeps the workspace name out of the visible body, deduplicates repeats, and fails quietly if credentials are missing. iOS communication-notification metadata is enabled by default so the Codex avatar can render; set `PLUSH_CODEX_COMMUNICATION=0` if you want plain APNs presentation with a normal subtitle instead. Hosted reply questions are enabled by default; set `PLUSH_CODEX_REPLY=0` to send one-way notifications only.

```sh
plush login "$PLUSH_API_KEY"
plush codex-hook < /tmp/codex-stop-payload.json
```

Recommended `~/.codex/hooks.json` command:
```json
{
  "type": "command",
  "command": "plush codex-hook",
  "statusMessage": "Sending Plush notification",
  "timeout": 10
}
```

Useful environment overrides: `PLUSH_CODEX_TARGET`, `PLUSH_CODEX_APP_NAME`, `PLUSH_CODEX_APP_ICON_URL`, `PLUSH_CODEX_MAX_BODY_CHARS`, `PLUSH_CODEX_COMMUNICATION=0`, and `PLUSH_CODEX_ENABLED=0`.

## Reply from iPhone
Patch Codex.app once on the Mac:

```sh
plush patch-codex-app
```

The hook creates a hosted Plush text question. When you reply from the notification, the local watcher polls the Plush question response and opens `codex://plush/followup?threadId=<id>&prompt=<text>`. The Codex.app patch handles that deep link, opens the thread, and submits the reply as a follow-up prompt or steer.

## MCP Server
Codex can expose Plush as an MCP tool server:

```toml
[mcp_servers.plush]
command = "npx"
args = ["-y", "easypush", "mcp"]
```

Run `plush login <api-token>` once on the machine before starting the MCP server. Prefer a local login or secret manager over committing the token. The MCP server exposes:
- `get_account`: current account/billing.
- `list_devices`: linked devices.
- `list_live_activities`: registered ActivityKit tokens.
- `send_push`: title/body/thread/target/interruption/open_url.
- `ask_question`, `wait_for_question_response`, `get_question`, `list_questions`: ask the user for text/select input and wait asynchronously.
- `send_widget`: create/update/delete a saved WidgetKit payload.
- `send_widget_from_file`, `delete_widget`: render JSX/JSON widget templates from .plush and manage persisted widgets.
- `send_live_activity`: start/update/end Live Activities.
- `send_live_activity_from_file`, `end_live_activity`: render JSX/JSON activity templates and end activities.

## CLI Examples
```sh
plush send "Build passed" --title "Deploy done" --thread deploy-main
plush send "Work is ready" --title "Codex finished" --thread codex --app-name Codex --app-icon-url https://chatgpt.com/favicon.ico
plush ask --title "Need input" --body "Ship this?" --option Ship --option Hold --wait
plush devices
plush widget update deploy-main --title "Deploy" --subtitle main --progress 0.68 --open-url https://status.example.com
plush widget update photo-backup --title "Photo Backup" --subtitle Archive --progress 0.57 --open-url https://status.example.com/backups/photo
plush widget --file .plush/deploy-widget.tsx --props-json '{"progress":0.68}'
plush live update --name deploy-main --title Deploy --status "Running checks" --progress 0.42
plush live --file .plush/deploy-live.tsx --props-json '{"progress":0.42}'
```

## Agent Reference
- API reference: https://easypush.app/doc.md
- Human docs: https://easypush.app/docs
- Playground: https://easypush.app/play

Security notes: do not log Plush API keys, callback secrets, notification bodies that contain private data, or raw APNs tokens. Widget and notification callbacks must use HTTPS. If `PLUSH_API_KEY` or a saved `plush login` is missing, fail quietly in hooks so Codex does not block shutdown.