Skip to content

Commit ff16167

Browse files
timothyandrewclaude
timothyandrew
and
claude
committed
Redesign README with SVG logo and architecture diagram
Add a custom SVG logo (terminal + mail icon), ASCII flow diagram, Mermaid architecture graph, and restructured sections with better visual hierarchy. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 430b366 commit ff16167

2 files changed

Lines changed: 188 additions & 41 deletions

File tree

‎.github/logo.svg‎

Lines changed: 74 additions & 0 deletions
Loading

‎README.md‎

Lines changed: 114 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,93 @@
1-
# watch+
1+
<p align="center">
2+
<img src=".github/logo.svg" alt="watch+" width="520" />
3+
</p>
24

3-
Like GNU `watch`, but emails you when command output changes.
5+
<p align="center">
6+
<strong>GNU <code>watch</code>, supercharged with email notifications.</strong><br/>
7+
Know the instant your command output changes — in the terminal <em>and</em> your inbox.
8+
</p>
49

5-
Built with Bun + TypeScript. Uses [Resend](https://resend.com) for email delivery.
10+
<p align="center">
11+
<a href="#quickstart">Quickstart</a> · <a href="#examples">Examples</a> · <a href="#flags">Flags</a> · <a href="#configuration">Configuration</a>
12+
</p>
613

7-
## Install
14+
---
815

9-
### macOS (Apple Silicon)
16+
## Why watch+?
1017

11-
```bash
12-
bun install
13-
bun run build
14-
# produces a standalone ./watch+ binary
18+
You're already running `watch` to keep an eye on things. But you can't stare at a terminal forever.
19+
20+
**watch+** is a drop-in replacement for GNU `watch` that adds email alerts via [Resend](https://resend.com). Same flags, same behavior — plus a `--email` flag that changes everything.
21+
22+
```
23+
┌─────────────┐
24+
│ your shell │
25+
│ command │
26+
└──────┬───────┘
27+
│ runs every N seconds
28+
▼
29+
┌──────────────┐
30+
│ watch+ │──────────┐
31+
│ │ │ output changed?
32+
└──────┬───────┘ ▼
33+
│ ┌──────────────┐
34+
│ │ 📧 Resend │
35+
▼ │ email alert │
36+
┌──────────────┐ └──────────────┘
37+
│ terminal │
38+
│ (fullscreen │
39+
│ with diff │
40+
│ highlight) │
41+
└──────────────┘
1542
```
1643

17-
### Linux (amd64)
44+
## Quickstart
1845

1946
```bash
47+
# Install dependencies
2048
bun install
21-
bun build --compile --target=bun-linux-x64 src/index.ts --outfile watch+-linux-amd64
22-
```
2349

24-
### Development
50+
# Build a standalone binary
51+
bun run build # → ./watch+
2552

26-
```bash
53+
# Or run directly
2754
bun run src/index.ts -n 1 date
2855
```
2956

30-
## Usage
57+
> **Cross-compile for Linux:** `bun build --compile --target=bun-linux-x64 src/index.ts --outfile watch+-linux-amd64`
3158
59+
## Examples
60+
61+
```bash
62+
# 🕐 Live-updating clock
63+
watch+ -n 1 date
64+
65+
# 🔍 Highlight changes to a file
66+
watch+ -d -n 1 "cat /tmp/test.txt"
67+
68+
# 🚪 Exit as soon as output changes
69+
watch+ -g -n 1 "date +%S"
70+
71+
# 📧 Email yourself when an API response changes
72+
watch+ --email me@example.com \
73+
--from noreply@mydomain.com \
74+
--cooldown 30s \
75+
-n 2 \
76+
"curl -s https://api.example.com/status"
77+
78+
# 📊 Count errors in a log file
79+
watch+ -n 5 -- grep -c ERROR /var/log/app.log
3280
```
33-
watch+ [options] <command...>
34-
```
3581

36-
### GNU watch flags
82+
## Flags
83+
84+
### GNU watch compatible
85+
86+
All the flags you know. Fully compatible — swap `watch` for `watch+` in your scripts.
3787

3888
| Flag | Description |
3989
|------|-------------|
40-
| `-n, --interval <secs>` | Seconds between updates (default: 2) |
90+
| `-n, --interval <secs>` | Seconds between updates (default: `2`) |
4191
| `-d, --differences [permanent]` | Highlight changes between updates |
4292
| `-e, --errexit` | Exit on non-zero return code |
4393
| `-g, --chgexit` | Exit when output changes |
@@ -49,45 +99,68 @@ watch+ [options] <command...>
4999
| `-p, --precise` | Attempt precise timing |
50100
| `-b, --beep` | Beep on change |
51101

52-
### Email flags
102+
### Email notifications (the + in watch+)
53103

54104
| Flag | Description |
55105
|------|-------------|
56106
| `--email <address>` | Email address to notify on change |
57107
| `--from <address>` | Sender email address (required with `--email`) |
58-
| `--cooldown <duration>` | Min time between emails (default: `1m`) |
108+
| `--cooldown <duration>` | Min time between emails — e.g. `30s`, `5m`, `1h` (default: `1m`) |
59109
| `--subject <text>` | Custom email subject |
60110
| `--api-key <key>` | Resend API key |
61111

62-
### Keyboard shortcuts
112+
### Keyboard
63113

64-
- `q` — quit
65-
- `Space` — immediate re-run
66-
- `Ctrl+C` — quit
114+
| Key | Action |
115+
|-----|--------|
116+
| <kbd>Space</kbd> | Force an immediate re-run |
117+
| <kbd>q</kbd> | Quit |
118+
| <kbd>Ctrl+C</kbd> | Quit |
67119

68-
## Examples
120+
## Architecture
69121

70-
```bash
71-
# Live-updating clock
72-
watch+ -n 1 date
122+
```mermaid
123+
graph LR
124+
CLI["CLI<br/><small>commander</small>"] --> Config["Config<br/><small>~/.watch+/config.json</small>"]
125+
Config --> Watch["Watch Loop<br/><small>execute → compare → render</small>"]
126+
Watch --> Terminal["Terminal<br/><small>fullscreen + diff highlight</small>"]
127+
Watch -->|output changed?| Email["Email<br/><small>Resend API + cooldown</small>"]
73128
74-
# Highlight changes to a file
75-
watch+ -d -n 1 "cat /tmp/test.txt"
129+
style CLI fill:#1e293b,stroke:#475569,color:#e2e8f0
130+
style Config fill:#1e293b,stroke:#475569,color:#e2e8f0
131+
style Watch fill:#2d1f4e,stroke:#7c3aed,color:#e2e8f0
132+
style Terminal fill:#164e63,stroke:#06b6d4,color:#e2e8f0
133+
style Email fill:#4c1d95,stroke:#a78bfa,color:#e2e8f0
134+
```
76135

77-
# Exit when output changes
78-
watch+ -g -n 1 "date +%S"
136+
| Module | Responsibility |
137+
|--------|---------------|
138+
| **index.ts** | CLI parsing with Commander, flag validation |
139+
| **config.ts** | Loads `~/.watch+/config.json`, merges CLI + env + config with correct priority |
140+
| **watch.ts** | Core loop — executes command, diffs output, renders fullscreen terminal UI |
141+
| **diff.ts** | Change detection, unified diff generation, HTML formatting for emails |
142+
| **email.ts** | Sends notifications via Resend with cooldown throttling |
79143

80-
# Email on change with 30s cooldown
81-
watch+ --email me@example.com --from noreply@mydomain.com --cooldown 30s -n 2 "curl -s https://api.example.com/status"
144+
## Configuration
82145

83-
# Commands with flags (use --)
84-
watch+ -n 5 -- grep -c ERROR /var/log/app.log
146+
Create `~/.watch+/config.json` to set defaults so you don't have to pass flags every time:
147+
148+
```json
149+
{
150+
"resendApiKey": "re_...",
151+
"defaultTo": "alerts@example.com",
152+
"defaultFrom": "watch+@mydomain.com",
153+
"defaultCooldown": "5m",
154+
"defaultInterval": 2
155+
}
85156
```
86157

87-
## Configuration
158+
The Resend API key can also be set via the `RESEND_API_KEY` environment variable.
88159

89-
Create `~/.watch+/config.json` to set defaults. See `config.example.json` for the format.
160+
> **Priority:** CLI flags > environment variables > config file > defaults
90161
91-
The Resend API key can also be set via the `RESEND_API_KEY` environment variable.
162+
---
92163

93-
Priority: CLI flags > env vars > config file > defaults.
164+
<p align="center">
165+
Built with <a href="https://bun.sh">Bun</a> + TypeScript
166+
</p>

0 commit comments

Comments
 (0)