# Nudge

An open source inbox so AI agents can ask you for decisions, on the chat apps you already use.

The name is literal. Your agent nudges you when it needs a decision: gentle, not urgent, easy to ignore safely. That matches the second principle below: success is fewer interruptions, not more engagement. The npm package is `nudgeoss` (the plain word `nudge` was already taken by someone else), but the command you type is the short `nudge`.

> **Status: v0.3.** All seven channels are in: terminal, Telegram, Discord, Slack, email, Matrix (unencrypted rooms), and webhooks, each with a setup wizard (`nudge channel add telegram`), plus fallback chains and a daily digest. WhatsApp and Signal are reached through Matrix bridges you run yourself; see the guides. Install: `npm install -g nudgeoss` gives you the `nudge` command.

## The problem

There is no open infrastructure that lets an agent ask its human for a decision and reliably act on the answer, including when the human never replies. So agents today bolt onto human chat apps that have no concept of approvals, deadlines, or authority.

Nudge is the missing layer. It owns the request, the deadline, the default, and the record. Chat apps are only delivery, the way GitHub uses email as one of its screens.

## Quickstart

Works today, with the terminal as the first channel. Full steps in [docs/quickstart.md](docs/quickstart.md).

```sh
nudge init
```

Creates your first grant and prints the exact MCP snippet for Claude Code or any MCP client.

```sh
nudge serve
```

Runs the daemon: the timeout scheduler, your terminal inbox, and the MCP endpoint. Every channel connects outward, so you need no public URL, no open ports, and no certificates.

Then connect your agent with the printed snippet. It gets one tool that matters:

```js
ask_human({
  type: "approval",
  title: "Flight LIS to BRS, 84 pounds, Monday",
  urgency: "today",
  timeout: "18:00",
  default: "reject",
});
```

Your phone shows plain text that works on any channel:

```text
[shopping-agent, for Chris] Approval needed
Flight LIS to BRS, 84 pounds, Monday.
Reply 1 to approve, 2 to reject.
No reply by 18:00 means auto reject.  #a1b2c3
```

You reply `1` (in v0.1: `nudge answer <id> 1`) and the agent acts on it. If you never reply, the default fires at 18:00 and the agent moves on safely. Every request and outcome lands in an append-only, hash-chained log. `nudge log verify` checks the whole chain.

More reading: [the ideas behind it](docs/concepts.md) and [the reference](docs/reference.md).

## The eight principles

1. **Silence is an answer.** Every request carries a deadline and a default action, so the agent can move on safely when the human never replies.
2. **Success is fewer interruptions, not more engagement.** The metric is decisions per interruption, not messages delivered.
3. **The pipes stay dumb.** The agent declares what each message means in structured fields. The layer never uses AI to guess.
4. **Humans never migrate.** All new software lands on the agent's side. You keep the apps you already have.
5. **Design for the worst channel.** Every request works as plain text with a simple reply. Rich buttons are a bonus, never a requirement.
6. **An agent is a credential, not a user.** An agent's identity is a revocable permission slip: acting for whom, allowed what, until when. The kill switch matters more than the login.
7. **The transcript is the product.** The record of who asked, who approved, and when. Append-only, complete, permanent.
8. **Ship the tool, extract the protocol.** No formal spec until real usage shows what it should say.

## Channels

| #   | Channel  | How it connects                 | Status                                  |
| --- | -------- | ------------------------------- | --------------------------------------- |
| 0   | Terminal | local                           | shipped in v0.1                         |
| 1   | Telegram | Bot API long polling            | shipped in v0.2                         |
| 2   | Discord  | gateway websocket               | shipped in v0.2                         |
| 3   | Slack    | Socket Mode                     | shipped in v0.2                         |
| 4   | Email    | SMTP out, IMAP polling in       | shipped in v0.2                         |
| 5   | Matrix   | client sync loop                | shipped in v0.3, unencrypted rooms only |
| 6   | Webhook  | outbound POST, optional inbound | shipped in v0.3                         |

Matrix encrypted rooms are not supported yet. Nudge detects an encrypted room and refuses it with a clear message, at setup and at start, because a half-working encrypted bot loses messages silently and silent is the one thing this tool must never be. Encrypted rooms with device verification are on the roadmap.

WhatsApp and Signal are reached through [mautrix bridges](https://docs.mau.fi/bridges/) that you run yourself, using our one Matrix adapter. We ship tested guides for both, labelled best effort. We do not write or maintain bridge code.

Writing a new adapter should take a good developer about 100 lines and one afternoon. The adapter kit and its shared test suite arrive in v0.2.

## Non goals

- No direct WhatsApp, Teams, WeChat, or iMessage adapters. Gatekept platforms are not self-hosting territory.
- No web UI. Your existing chat apps are the UI.
- No hosted service in the MVP.
- No formal protocol spec until two things we did not build talk to it anyway.
- No agent-to-agent messaging.
- No AI anywhere in the delivery layer, ever.

## Licence

Apache-2.0