8.5 KiB

Raw Blame History

Claude Code Notify Assistant – Product Specification

1 Purpose & Vision

Provide developers with an event‑driven companion for Claude‑powered CLI sessions. When a long‑running task finishes, the assistant instantly notifies the user on their preferred channel and lets them reply from mobile to trigger the next command, achieving a seamless desktop↔mobile↔AI loop.

2 Problem Statement

CLI workflows often involve scripts that run for minutes or hours. Users must poll the terminal or stay near the computer, wasting time and focus. Existing notification tools are channel‑specific or lack bi‑directional control, and none are optimised for Claude Code agents.

3 Solution Overview

CLI Hook: A tiny cross‑platform wrapper (claude-notify run <cmd>) that executes any shell command, streams logs to the backend, and raises a TaskFinished event when exit‑code ≠ “running”.
Notification Orchestrator (backend): Consumes events, applies user quota/business rules, and fan‑outs messages via pluggable channel adapters.
Interactive Relay: Converts user replies (e.g., from Telegram) into authenticated API calls that queue the next CLI command on the origin machine through a persistent WebSocket tunnel.
Usage Metering: Tracks daily quota (3 e‑mails for free tier) and subscription status (Stripe webhook).

4 Personas & User Journeys

Persona	Primary Goal	Typical Flow
Indie Dev – Free	Compile & test large project remotely	1) `claude-notify run make` → 2) E‑mail sent on finish → 3) Next morning sees mail; quota resets
Startup Engineer – Pro	Continuous fine‑tuning jobs on GPU VM	1) Task completes → 2) Telegram alert with success log snippet → 3) Replies `launch next.sh` from subway → 4) Claude Code executes instantly
Ops Lead – Pro	Batch data pipelines	1) Weekly cron triggers job → 2) Feishu group ping with status + link to dashboard

5 Feature Matrix

Area	Free	Pro (USD 4.9/mo)
Daily notification quota	3	Unlimited
Channels	E‑mail	E‑mail, Discord, Telegram, SMS, Feishu, Webhooks
Command Relay	—	✅
Notification Templates	Default	Custom markdown & rich‑link cards
Log Attachment	10 KB tail	Full log (configurable)
Team Workspaces	—	Up to 5 members
SLA	Best effort	99.9 %

6 System Architecture

+-----------+                 HTTPS / WSS                  +-----------------+
| CLI Agent |  <──────────▶  API Gateway   ───────────▶  |  Auth Service   |
|  (Go/Rust)|                                            +-----------------+
|           |── stream logs ─▶  Event Queue (NATS) ──▶  Task Processor
+-----------+                                            │(Python Worker)
          ▲                                                │              │
          │ SSH/WebSocket                                  │              │
          │                                                ▼              ▼
          │                                    +-----------------+  +-----------------+
          │                                    | Notification    |  |  Usage / Billing|
          └── receive command ◀── Relay ◀──────┤   Fan‑out       |  |  (Postgres +   |
                                               +-----------------+  |   Stripe)      |

Tech choices

CLI Agent: Rust binary, ~3 MB, single‑file, auto‑updates (GitHub Releases).
Backend: FastAPI + Celery, Redis broker, Postgres store.
Channel Adapters: Modular; each implements send(message: Notification) -> DeliveryResult.
Security: JWT (CLI) + signed HMAC Webhook secrets; all data in‑flight TLS 1.2+.
Scaling: Horizontal via Kubernetes; stateless workers.

7 API Contracts (simplified)

POST /v1/tasks
{
  "cmd": "python train.py",
  "session_id": "abc",
  "notify_on": "exit", // or "partial", "custom_regex"
  "channels": ["email", "tg"]
}
→ 201 Created {"task_id":"t123"}

POST /v1/commands
Authorization: Bearer <mobile_reply_token>
{
  "session_id": "abc",
  "command": "git pull && make test"
}
→ 202 Accepted

Complete OpenAPI spec in appendix.

8 Data Model (Postgres)

CREATE TABLE users (
  id UUID PK, email TEXT UNIQUE, plan TEXT, quota_used INT, …
);
CREATE TABLE tasks (
  id UUID PK, user_id FK, session_id TEXT, cmd TEXT, status TEXT,
  started_at TIMESTAMPTZ, finished_at TIMESTAMPTZ, log_url TEXT, …
);
CREATE TABLE notifications (
  id UUID PK, task_id FK, channel TEXT, delivered BOOL, …
);

9 Quota & Pricing Logic

If plan == "free":
    limit daily_sent_email <= 3
    reject other channel
Else if plan == "pro":
    no channel limit
    fair‑use: 30 SMS / day default

Billing via Stripe Billing Portal; pro‑rated upgrades.

10 On‑boarding Flow

OAuth (GitHub) or E‑mail link signup.
Download CLI (curl -sL https://cli.claude‑notify.sh | bash).
claude-notify login <token> – stores token locally.
Configure channels in Web UI (Discord bot auth, etc.).
First task run offers interactive tour.

11 Operational & Security Considerations

Secrets: Only hash task logs > 10 MB for storage; encrypt full logs (AES‑256‑GCM) at rest.
Abuse prevention: Per‑minute rate limits on incoming mobile commands; banlist keywords.
Observability: Prometheus metrics, Grafana dashboard; Sentry for exceptions.
Compliance: GDPR + China PIPL data residency via multi‑region storage.

11a Implementation Phases

Phase 1 – Local Desktop Notification MVP

Scope: Notify on local machine only.
Trigger: CLI Agent detects task exit and calls OS‑native notification helper.
OS Support:
- macOS: terminal-notifier or AppleScript.
- Windows: Toast via SnoreToast.
- Linux: libnotify.
Customization: --title, --message, --sound=/path/to/file flags; sensible defaults provided.
Offline & Privacy: No network calls; runs entirely locally.
Quota: Unlimited (cloud quota applies in later phases).
Future‑Proofing: Uses the same TaskFinished event schema as the cloud orchestrator, enabling a smooth upgrade path.

Phase 2 – Cloud Notification Service (E‑mail, Telegram, Discord)

Add backend Notification Orchestrator, channel adapters, and basic auth.
Implement daily quota enforcement and Pro billing (Stripe).

Phase 3 – Mobile Command Relay & Team Features

Enable interactive replies that queue new commands via WebSocket tunnel.
Introduce Workspaces, role permissions, and activity audit logs.

12 Roadmap

Quarter	Milestone
Q3‑25	MVP (E‑mail + Telegram) / Invite‑only beta
Q4‑25	Payments, Discord & Feishu adapters / Public launch
Q1‑26	Mobile app (Flutter) push notifications / Team workspaces
Q2‑26	Marketplace for community adapters (e.g., Slack, WhatsApp)

13 Open Questions

Support for streaming partial logs?
Granular role permissions for team plans.
Enterprise SSO & on‑prem backend – worth pursuing?
Automatic Claude Code context carry‑over between sequential commands.

8.5 KiB Raw Blame History Unescape Escape