peckish

# Peckish 🍜

**Feeling peckish? Just ask.** An AI ordering agent for DoorDash — it searches,
compares real totals (fees included), builds the cart, and *you* approve every
order. Built on [Claude](https://platform.claude.com) and DoorDash's official
[`dd-cli`](https://github.com/doordash-oss/doordash-cli).

One tool layer, three surfaces:

| Surface | Start | Best for |
|---|---|---|
| **Terminal chat** | `peckish` | Living in the terminal |
| **Local web app** | `peckish-web` → http://localhost:4747 | Consumer-friendly UI: store cards, live quote, Stop button, order modal |
| **MCP server** | `claude mcp add peckish -- npx -y peckish-mcp`, or the double-click [`.mcpb`](https://github.com/CydVilla/peckish/releases/latest) | Claude Desktop / Claude Code users — **no API key needed**; your Claude subscription powers the model |

**Which one is for me?**

- **Comfortable with a terminal?** → Terminal chat. Fastest, most informative.
- **Want something that feels like an app?** → Local web app. Cards, live
  quote, a proper Place-order button.
- **Already use Claude Desktop or Claude Code?** → MCP server. No API key,
  no separate chat window — Claude itself becomes your ordering agent, and
  order confirmation appears as a native dialog.

<p align="center">
  <img src="docs/demo.gif" alt="Peckish finding a dinner under $25: tool calls run, a recommendation streams in with the fee-included total, and an order-confirmation dialog asks for approval before anything is placed." width="820">
  <br>
  <em><sub>Scripted demo of the web app — store, prices and card are fictional;
  the interface and the approval gate are the real ones.</sub></em>
</p>

**[peckish on the web →](https://cydvilla.github.io/peckish/)**

Install in one line — no git clone:

```sh
npm install -g peckish
```

**Prefer an app?** Download the
[Mac app (.dmg)](https://github.com/CydVilla/peckish/releases/latest) —
guided setup, no terminal at any step. See [Mac app](#mac-app) below.
Everything runs on your own Mac either way, because DoorDash sign-in lives
in your keychain.

```
you › Find me a high-protein dinner under $25 that can arrive within 45
      minutes. Avoid mushrooms and excessive fees.

⚙ search_restaurants {"query":"grilled chicken bowls","limit":8}  ✓ 2.1s
⚙ get_menu {"store_id":"35406455","filter":"chicken"}             ✓ 1.8s
⚙ list_carts {"store_id":"35406455"}                              ✓ 1.2s
⚙ add_items_to_cart {…}                                           ✓ 2.4s
⚙ preview_order {"cart_uuid":"…"}                                 ✓ 3.9s

Best fit: Sharon Korean Kitchen (4.8★, ~24 min) — Grilled Chicken Bulgogi
Bowl, $16.95. No mushrooms listed. Total with fees: $21.40 on your Visa
ending 1234. Suggested Dasher tip is $3.50 — that, another amount, or none?
~$0.04 turn · $0.04 session
```

---

## Get started (user guide)

### 1. Prerequisites

- **A Mac with Apple Silicon** (M1–M4). Peckish is local-first: your Mac is the
  backend on every surface, because dd-cli authenticates against your keychain.
- **Node.js 20+** — `node --version` to check; install from nodejs.org or brew.
- **DoorDash CLI access** (currently waitlist-gated by DoorDash). Download the
  release from [doordash-oss/doordash-cli](https://github.com/doordash-oss/doordash-cli/releases),
  **verify the SHA256 checksum against the published value**, then:
  ```sh
  tar -xzf dd-cli-v*-darwin-arm64.tar.gz && cd dd-cli-v*-darwin-arm64
  bash install.sh          # installs to ~/.local/bin/dd-cli
  dd-cli login             # sign in to DoorDash in your browser (stored in keychain)
  ```
- **An Anthropic API key** for the terminal/web surfaces
  ([console.anthropic.com](https://console.anthropic.com)) — *or skip the key
  entirely and use the MCP surface with your Claude subscription (step 4).*

### 2. Install Peckish

```sh
npm install -g peckish
```

That's it — you now have three commands: `peckish` (terminal chat),
`peckish-web` (web app), and `peckish-mcp` (MCP server).

<details>
<summary>Or install from source (contributors)</summary>

```sh
git clone https://github.com/CydVilla/peckish.git
cd peckish
npm install
npm test          # optional: 13 unit tests, no network needed
npm run dev       # terminal chat (or: npm run web / npm run mcp)
```

</details>

### 3. Run it — terminal or web

```sh
export ANTHROPIC_API_KEY=sk-ant-…   # from console.anthropic.com

peckish         # terminal chat
peckish-web     # web app → open http://localhost:4747
```

On boot Peckish verifies your DoorDash sign-in, shows your default delivery
address, and flags any open carts you forgot about. If sign-in expired, run
`dd-cli login` again and restart.

### 4. Or run it inside Claude — no API key

Claude itself becomes the ordering agent, and your Claude subscription pays for
the model. Pick whichever fits your client:

**Claude Code** — one line:

```sh
claude mcp add peckish -- npx -y peckish-mcp
```

**Claude Desktop** — download `peckish-0.2.2.mcpb` from
[Releases](https://github.com/CydVilla/peckish/releases/latest) and
double-click it. Claude Desktop installs it like a browser extension: no
terminal, no Node install, no JSON editing.

<details>
<summary>Or configure Claude Desktop by hand</summary>

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "peckish": {
      "command": "npx",
      "args": ["-y", "peckish-mcp"]
    }
  }
}
```

If dd-cli isn't at `~/.local/bin/dd-cli`, add
`"env": { "DD_CLI_PATH": "/your/path/to/dd-cli" }` — desktop apps don't
inherit your shell `PATH`.

</details>

Peckish is also listed in the [MCP Registry](https://registry.modelcontextprotocol.io)
as `io.github.CydVilla/peckish`, so clients that browse the registry can find
it directly.

Restart Claude Desktop and ask it to find you dinner. Order confirmation
appears as a native dialog; clients that can't render dialogs can browse and
build carts but **cannot place orders** (fail closed).

### 5. Everyday use

Things to say:

- *"Find me a high-protein dinner under $25 that can arrive within 45 minutes. Avoid mushrooms and excessive fees."*
- *"Compare the real totals at the top two — fees included."*
- *"Reorder my usual from Sharon Korean."*
- *"What did I spend on delivery last month?"*
- *"Is this place actually good?"* (checks web reviews)
- *"Never mushrooms, ever."* → saved permanently; applied automatically next time
- *"Get me milk, eggs, and a pound of ground beef from Whole Foods."*

**Placing an order** always ends with an explicit confirmation *you* perform —
typing `yes` in the terminal, clicking **Place order** in the web modal, or
approving the dialog in Claude Desktop. Before that, Peckish must show you the
itemized quote, confirm the tip, and name the card being charged. Decline
anything and it backs off.

**Controls & housekeeping**

| Where | What |
|---|---|
| Terminal | `/prefs` saved preferences · `/cost` session spend · `/reset` new conversation · `/quit` · **Ctrl+C stops a running turn** |
| Web | **Stop** button cancels a turn · **New chat** resets · header chip shows session cost · click the **address chip** to switch your delivery address (editing an address's text happens on doordash.com — Peckish picks it up automatically) |
| Both | Preferences live in `~/.peckish/preferences.json`; a full audit log of every tool call and confirmation is written to `~/.peckish/logs/*.jsonl` |

**Cost:** defaults are tuned for low spend at decent quality — `claude-sonnet-5`
at medium effort, prompt caching on the system prefix and conversation tail,
and server-side context editing that prunes stale menu payloads in long
sessions. The cost meter shows the approximate spend per turn and per session.
Max quality: `DD_AGENT_MODEL=claude-opus-4-8 DD_AGENT_EFFORT=high`. (On MCP,
the client chooses and pays for the model.)

**Troubleshooting**

| Symptom | Fix |
|---|---|
| `DoorDash sign-in is missing or expired` | Run `dd-cli login` in a terminal, restart Peckish |
| `Anthropic authentication failed` | `export ANTHROPIC_API_KEY=…` in the same shell, restart |
| `dd-cli binary not found` | Install dd-cli (step 1) or set `DD_CLI_PATH=/path/to/dd-cli` |
| Web app port in use | `PECKISH_PORT=5757 peckish-web` |
| A turn ran away | Ctrl+C (terminal) / Stop (web) — history rolls back cleanly |

Env vars: `DD_AGENT_MODEL` (default `claude-sonnet-5`), `DD_AGENT_EFFORT`
(`low`–`max`, default `medium`), `DD_CLI_PATH`, `PECKISH_PORT` (default `4747`).

---

## Mac app

A double-clickable app for people who never want to see a terminal:
download `Peckish-x.y.z-arm64.dmg` from
[Releases](https://github.com/CydVilla/peckish/releases/latest), drag
**Peckish** to Applications, and open it.

**First launch (Gatekeeper):** the app is ad-hoc signed but not notarized (no
paid Apple Developer ID), so macOS won't open it on a plain double-click the
first time. **Right-click the app → "Open" → "Open"** (or approve it under
System Settings → Privacy & Security). Only needed once.

> If macOS instead says **"Peckish is damaged and can't be opened"**, you have
> a build from before this was fixed, or the download quarantine got confused.
> Clear it once and it opens normally:
> ```sh
> xattr -cr /Applications/Peckish.app
> ```

First-run setup happens in the app — three buttons, no terminal:

1. **DoorDash CLI** — one-click guided install (downloads the official
   release, verifies its SHA256 checksum before running anything). If you
   don't have dd-cli access yet, there's a waitlist link.
2. **Sign in to DoorDash** — opens your browser; the app detects when
   you're done. Your sign-in lives in the macOS keychain.
3. **Anthropic API key** — paste it once; it's stored encrypted with
   Electron `safeStorage` (keychain-backed), never in plain text.

Then **Open Peckish** — same web app, same order-confirmation modal, same
safety gates; the app is just a shell that runs the local server for you on
a random localhost-only port. Requires Apple Silicon; Node.j