Cardputer Companion

Cardputer Companion

The Cardputer is a credit-card-sized handheld the user carries in their pocket. It exposes MCP tools over a BLE bridge — notify, ask, confirm, show, and progress — provided by the cardputer MCP server in this repo (mcp/server.py). Those tools are the hands. This skill is the manners: it tells you when to reach for them and how to shape what you send, so the device stays useful instead of annoying.

These rules apply no matter where you run. The same tools reach the same device whether you're local Claude Code over loopback or a cloud Managed Agent / Messages-API agent over an MCP tunnel (tunnel/). If anything, restraint and the fail-closed confirm discipline matter more when you're an unattended cloud agent — the user isn't watching a terminal, and the physical gesture is the only thing standing between you and an irreversible mistake. The device shows which agent is asking on every ask/confirm banner (derived from your bearer token, so you can't misrepresent it) — keep your requests honest and legible.

Core ethos: default to silence

A buzz should mean something. The user is wearing this thing; every alert costs their attention. Earn each one. When in doubt, stay quiet and keep working — do not narrate progress to the device. The daemon now enforces a per-agent floor on non-critical notifys (a second non-crit buzz within ~60 s comes back rate-limited and never reaches the device), but treat that as a safety net, not a budget — keep self-imposed restraint as the real throttle. If you want a long task to stay visible without buzzing, use show (see below), not repeated notifys.

1. Confirm policy — mandatory, non-negotiable

Before any irreversible operation, call cardputer.confirm and wait for the physical hold gesture. Do not substitute a chat-message "are you sure?" — the whole point is that no tool output or prompt injection can synthesize a sustained physical keypress, but it can forge a convincing chat confirmation.

Operations that require confirm:

• Production deploys / releases
• git push --force (especially to main/master)
• DROP TABLE, TRUNCATE, or DELETE / UPDATE without a WHERE
• rm -rf, mass file deletion, or destroying uncommitted work
• Paid API calls or financial transactions with large side effects
• Anything the user could not undo in about a minute

Rules:

• If confirm returns cancelled or timeout, abort the operation and tell the user — never proceed on a non-confirmation.
• If confirm returns unavailable: … (device off or out of range), do not silently fall through to running the destructive command. Stop and tell the user the device isn't reachable; let them decide how to proceed.
• Keep the title to ~18 characters and declarative — the user must recognize the operation at a glance: FORCE PUSH main, DROP customers, deploy prod.
• Pass details whenever you can: the actual content being approved — the real shell command, the SQL, a short diff hunk, or payee + amount. The device renders it in a scrollable box above the gesture, so the user approves what they read, not just the title (the hardware-wallet model). Keep it to the essential ~256 chars and strip noise. It's text you supply, so it's legibility of intent, not cryptographic proof — and the title must still stand on its own (older firmware shows the title only).
• Do not call confirm for routine yes/no decisions — that's what ask is for.
• Every confirm decision (confirmed / cancelled / timeout / unavailable) is written to a local consent audit log (~/.cardputer-mcp/audit.log) with the agent label, title, and details. Another reason to pass a real, legible details: it's the durable record of what the user approved.

2. Proactive notify — quiet

Buzz the device on the final completion of a genuinely long-running task — multi-step or multi-minute work the user is plausibly waiting on while away from the keyboard (a full test suite, a migration, a build, a long agent run).

• One notify at the end, not one per step.
• Lead with the verdict: tests green, build failed, deploy ready.
• Do not notify for quick interactive turns where the user is clearly watching the screen — that's just noise.
• Use urgency honestly: info for "done, all good", warn for "done but needs your eyes", crit only for something that needs a reaction within seconds.

3. Ask when blocked — quiet

Use cardputer.ask only when you are genuinely blocked on a decision and the user may be away from their laptop. If they are plainly at the keyboard, ask in the chat instead — the device round-trip is slower and more intrusive.

• Provide 2–4 short choices (each ≤ ~32 chars).
• Keep the question to ~60 chars (wraps to two lines on the LCD).
• On timeout or cancelled, fall back to chat — do not loop re-asking.

3b. Ambient status — show, glanceable not noisy

cardputer.show(text, channel) writes one silent line to the device's idle screen — no chirp, no screen takeover, not gated by DND. Use it to leave a live heartbeat of a long task the user can glance at, instead of buzzing them: building…, pytest 142/300, deploy ok.

• It is NOT a notify. Never use it for something the user must react to — that's notify (or confirm). show is the status bar, not an alert.
• Update at a human cadence — a few times across a task, not every step/token.
• One line per channel (defaults to your agent label); keep text ≤ ~40 chars. The device keeps only the most recent few channels.
• The pattern: a show heartbeat while working, then one notify at the very end (tests green). Don't replace the end-of-task notify with show.