Clawlet

An agentic crypto wallet that buys real-world goods on your behalf. Chat-first desktop app; agent owns a Solana wallet and pays in USDC via Bitrefill's eCommerce MCP.

See CLAUDE.md for the full design brief and current implementation status.

Prerequisites

• Bun ≥ 1.1
• An Anthropic API key
• (Live mode only) A Bitrefill API key from https://www.bitrefill.com/account/developers
• (Auto-redeem only) Python ≥ 3.11 + uv — see Auto-redemption setup

First-time setup

Commands below work on both macOS/Linux (bash/zsh) and Windows (PowerShell) — PowerShell aliases cp, cd, ls to their POSIX equivalents. Where the two diverge, I show both.

# 1. Install dependencies. --ignore-scripts works around a Windows
#    postinstall issue with `unrs-resolver`.
bun install --ignore-scripts

# 2. Create env files (templates only ship with .env.example).
#    macOS/Linux:
cp agent/.env.example    agent/.env
cp backend/.env.example  backend/.env
cp frontend/.env.example frontend/.env.local
#    Windows PowerShell — same commands work (cp aliases Copy-Item):
#    or use: Copy-Item agent/.env.example agent/.env

# 3. Edit agent/.env and set:
#      ANTHROPIC_API_KEY=sk-ant-...
#    Defaults for everything else are fine.

# 4. Apply database migrations.
bun --cwd backend db:migrate deploy

Run

bun run dev

This starts:

• Frontend on http://localhost:3000 (Next.js)
• Agent on http://127.0.0.1:4000 (Bun.serve)

Open http://localhost:3000. On first launch the agent grinds a vanity Solana address starting/ending with CLaW (~1–7 min on a 4-core machine). Then chat is live.

Modes

The agent ships with stub mode as the default — Bitrefill calls are simulated locally, no real money moves, redemption codes are synthetic. Useful for trying the flow end-to-end without a Bitrefill account.

To enable real purchases, add to agent/.env:

BITREFILL_API_KEY=<your key>
CLAWLET_BITREFILL_MODE=live
CLAWLET_LIVE_ACK=1

Restart the agent. Fund the wallet (small SOL for transaction fees, USDC for purchases) by sending to the address shown on the Wallet page. Boot will fail fast if any of the three live-mode variables is missing.

Auto-redemption setup

After a purchase succeeds, the agent can autonomously apply the gift-card code to your merchant account via a Python sidecar (browser-sidecar/) running browser-use on Playwright/Chromium. Optional — if the sidecar isn't running, the agent just delivers the code and you redeem manually.

Currently supports: Instacart (US and Canada). Region is per-account — set it in Settings → Integrations alongside the email. Adding more Instacart locales (AU, etc.) is a one-line addition to _BASE_URLS in the sidecar plus the country whitelist in agent/src/state/integrations.ts.

One-time install

Step 1: install uv (Python package manager) if you don't already have it.

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Or via Homebrew (macOS): brew install uv. Or via Scoop / winget (Windows): winget install --id=astral-sh.uv.

Step 2: install the sidecar deps and Chromium. Same commands on both OSes:

cd browser-sidecar
uv sync
uv run playwright install chromium    # ~150 MB
cp .env.example .env                  # PowerShell aliases cp; works as-is
# edit browser-sidecar/.env: at minimum add ANTHROPIC_API_KEY

Add merchant credentials

Open the desktop app → Settings → Integrations → fill in your Instacart email + password → Save.

Stored locally at:

• macOS / Linux: ~/.clawlet/credentials.json (set to mode 0600 — owner read/write only).
• Windows: C:\Users\<you>\.clawlet\credentials.json (protected by your user-profile ACL — only your Windows user can read it).

Plaintext for now — Phase 2 adds passphrase encryption. The sidecar reads this file directly; the agent never handles your password.

Run the sidecar

In a separate terminal alongside bun run dev:

cd browser-sidecar
uv run python -m src.main
# → Uvicorn running on http://127.0.0.1:4100

Now finish a purchase from chat — a Chrome window pops up, logs in, applies the code, reports the new Instacart balance.

Sidecar env vars (browser-sidecar/.env)

Var	Required	Default	Purpose
ANTHROPIC_API_KEY	yes	—	browser-use is itself LLM-driven; can be the same key as the agent's
TWOCAPTCHA_API_KEY	no	—	Auto-solve reCAPTCHA / hCaptcha / Cloudflare Turnstile via 2captcha. Without it, captchas surface as needs_human and you solve them in the visible Chrome window
CLAWLET_BROWSER_HEADLESS	no	0	1 to run Chromium headless (faster; you can't intervene on captcha/2FA)
CLAWLET_SIDECAR_PORT	no	4100	Sidecar HTTP port
CLAWLET_HOME	no	~/.clawlet (macOS/Linux) / %USERPROFILE%\.clawlet (Windows)	Override the data dir (mostly for tests)

Optional in agent/.env if you ever move the sidecar elsewhere:

CLAWLET_SIDECAR_URL=http://127.0.0.1:4100

Where session cookies live

• macOS / Linux: ~/.clawlet/browser-profiles/<merchant>/
• Windows: C:\Users\<you>\.clawlet\browser-profiles\<merchant>\

Persisted between runs so Instacart doesn't trigger a new-device challenge every redemption. Delete the folder to force a fresh login.

Spend caps

Configurable in agent/.env:

CLAWLET_AUTO_APPROVE_CAP_USD=25     # spends ≤ this auto-approve
CLAWLET_PER_TX_CAP_USD=200          # hard maximum per purchase
CLAWLET_PER_DAY_CAP_USD=500         # hard maximum across all orders today

Above the auto-approve cap, the chat shows an inline approval card; you click Confirm or Deny.

Useful scripts

bun run dev              # start frontend + agent concurrently
bun run dev:frontend     # frontend only
bun run dev:agent        # agent only

bun --cwd agent test     # run unit tests
bun --cwd agent run check  # typecheck

bun --cwd backend db:studio    # browse the SQLite DB
bun --cwd backend db:migrate dev --name <name>   # new schema migration

Project layout

clawlet/
├── frontend/         Next.js 16 chat + wallet UI
├── backend/          Prisma schema home (not a runtime)
├── agent/            Bun.serve sidecar — REST + SSE, agentic loop, tools
├── browser-sidecar/  Optional Python sidecar — browser-use auto-redemption
└── todo/             Backlog notes