@hrushiborhade/pingme 1.1.0 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +72 -96
  2. package/dist/index.js +1 -1
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,66 +1,53 @@
1
1
  # pingme
2
2
 
3
- > My Claude agent pings me when it's stuck. Now I doom scroll guilt-free. Yours is just... stuck.
3
+ pingme hooks into Claude Code's lifecycle events and texts your phone when your agent actually needs you.
4
4
 
5
- [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
6
-
7
- Get SMS notifications for all Claude Code agent lifecycle events. No more checking terminals.
5
+ [![npm version](https://img.shields.io/npm/v/@hrushiborhade/pingme)](https://www.npmjs.com/package/@hrushiborhade/pingme)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
8
7
 
9
8
  ## The Problem
10
9
 
11
10
  You're running multiple Claude Code instances across tmux panes. One stops because it needs permission or has a question. You think it's still working. Hours later, you find it blocked. Time wasted.
12
11
 
13
- ## The Solution
12
+ ## Quick Start
14
13
 
15
14
  ```bash
16
15
  npx @hrushiborhade/pingme init
17
16
  ```
18
17
 
19
- Now your Claude agent texts you when it needs you.
18
+ Follow the prompts — enter your Twilio credentials, choose which events should trigger an SMS, and you're done.
20
19
 
21
- ## What You Get
20
+ ## Supported Events
22
21
 
23
22
  SMS notifications for **14 Claude Code hook events** — you choose which ones:
24
23
 
25
24
  **Enabled by default:**
26
- - ✅ **Task completed** — agent finished a task
27
- - 🛑 **Agent stopped** — agent stopped running
28
- - ❓ **Asking question** — agent is asking you a question
29
- - 🔔 **Notification** — agent sent a notification
30
- - 🔐 **Needs permission** — agent needs your permission to proceed
25
+ | Event | Description |
26
+ |-------|-------------|
27
+ | ✅ Task completed | Agent finished a task |
28
+ | 🛑 Agent stopped | Agent stopped running |
29
+ | ❓ Asking question | Agent is asking you a question |
30
+ | 🔔 Notification | Agent sent a notification |
31
+ | 🔐 Needs permission | Agent needs your permission to proceed |
31
32
 
32
33
  **Available (off by default):**
33
- - ❌ Tool failed
34
- - 🤖 Subagent finished
35
- - 🔴 Session ended
36
- - 🟢 Session started
37
- - 🚀 Subagent started
38
- - 💤 Teammate idle
39
- - 📦 Pre-compact
40
- - 📝 Prompt submitted (spammy)
41
- - 🔧 Pre tool use (spammy)
42
-
43
- Each message includes:
34
+ | Event | Description |
35
+ |-------|-------------|
36
+ | ❌ Tool failed | A tool call failed |
37
+ | 🤖 Subagent finished | A subagent finished running |
38
+ | 🔴 Session ended | Claude Code session ended |
39
+ | 🟢 Session started | Claude Code session started |
40
+ | 🚀 Subagent started | A subagent started running |
41
+ | 💤 Teammate idle | A teammate agent is idle |
42
+ | 📦 Pre-compact | Context is about to be compacted |
43
+ | 📝 Prompt submitted | User submitted a prompt (spammy) |
44
+ | 🔧 Pre tool use | About to use a tool (spammy) |
45
+
46
+ Each SMS includes:
44
47
  - **Project name** — which codebase needs you
45
- - **tmux context** — which pane to jump to
48
+ - **tmux context** — which pane to jump to (if applicable)
46
49
  - **Reason** — what the agent needs
47
- - **Context** — extracted from JSON input (tool name, message, etc.) when `jq` is available
48
-
49
- ## Setup
50
-
51
- ### 1. Get Twilio Credentials (free trial works)
52
-
53
- 1. Sign up at [twilio.com/console](https://console.twilio.com)
54
- 2. Get your Account SID and Auth Token from the dashboard
55
- 3. Get a phone number (or use the trial number)
56
-
57
- ### 2. Install pingme
58
-
59
- ```bash
60
- npx @hrushiborhade/pingme init
61
- ```
62
-
63
- Follow the prompts — pick your Twilio creds, then choose which events should trigger an SMS. Done.
50
+ - **Context** — extracted from JSON input via `jq` (with raw text fallback)
64
51
 
65
52
  ## Commands
66
53
 
@@ -77,24 +64,24 @@ npx @hrushiborhade/pingme --help # Show help
77
64
 
78
65
  pingme uses Claude Code's [hooks system](https://docs.anthropic.com/en/docs/claude-code/hooks) to detect when the agent needs your attention.
79
66
 
80
- 1. **Installation**: When you run `npx @hrushiborhade/pingme init`, pingme creates:
67
+ 1. **Installation** — `npx @hrushiborhade/pingme init` creates:
81
68
  - A bash script at `~/.claude/hooks/pingme.sh` that sends SMS via Twilio
82
69
  - Hook entries in `~/.claude/settings.json` for each selected event
83
70
 
84
- 2. **Hook Triggers**: Hooks are configured for your selected events. For example:
85
- - `TaskCompleted` — triggers when a task finishes
86
- - `PostToolUse` with `AskUserQuestion` matcher — triggers when Claude asks you a question
87
- - `Stop` — triggers when Claude stops execution
88
- - `PermissionRequest` — triggers when Claude needs permission
71
+ 2. **Hook Triggers** — Hooks are registered for your selected events:
72
+ - `TaskCompleted` — when a task finishes
73
+ - `PostToolUse` (matcher: `AskUserQuestion`) — when Claude asks a question
74
+ - `Stop` — when Claude stops execution
75
+ - `PermissionRequest` — when Claude needs permission
89
76
  - ...and any other events you enable
90
77
 
91
- 3. **Notification Flow**: When triggered, the hook script:
78
+ 3. **Notification Flow** — When triggered, the hook script:
92
79
  - Detects your current project name from the working directory
93
80
  - Captures tmux session/window/pane info (if available)
94
81
  - Extracts context from JSON stdin using `jq` (with raw text fallback)
95
- - Sends an SMS via Twilio's API with context about what needs attention
82
+ - Sends an SMS via Twilio's API
96
83
 
97
- 4. **Reconfiguration**: Run `npx @hrushiborhade/pingme events` anytime to change which events trigger SMS — no need to re-enter Twilio credentials.
84
+ 4. **Reconfiguration** — Run `npx @hrushiborhade/pingme events` anytime to change which events trigger SMS without re-entering Twilio credentials.
98
85
 
99
86
  ## Example SMS
100
87
 
@@ -104,77 +91,70 @@ pingme uses Claude Code's [hooks system](https://docs.anthropic.com/en/docs/clau
104
91
  💬 Task completed
105
92
  ```
106
93
 
94
+ ## Setup
95
+
96
+ ### Prerequisites
97
+
98
+ - Node.js 18+
99
+ - [Twilio account](https://console.twilio.com) (free trial includes $15 credit)
100
+ - Claude Code CLI
101
+ - `curl` (pre-installed on most systems)
102
+ - `jq` (optional — enables richer context extraction from JSON input)
103
+
104
+ ### Twilio Configuration
105
+
106
+ 1. Sign up at [twilio.com/console](https://console.twilio.com)
107
+ 2. Get your Account SID and Auth Token from the dashboard
108
+ 3. Get a phone number (or use the trial number)
109
+ 4. Run `npx @hrushiborhade/pingme init` and follow the prompts
110
+
107
111
  ## Security
108
112
 
109
- - **Credentials are stored locally** in `~/.claude/hooks/pingme.sh`
113
+ - Credentials are stored locally in `~/.claude/hooks/pingme.sh`
110
114
  - Credentials are never sent to any server except Twilio's API
111
115
  - The hook script only runs when Claude Code triggers it
112
116
  - Input is sanitized to prevent shell injection
113
117
  - SMS requests are made over HTTPS
114
118
 
115
- To update or remove credentials, run `npx @hrushiborhade/pingme init` again or `npx @hrushiborhade/pingme uninstall`.
116
-
117
119
  ## Troubleshooting
118
120
 
119
121
  ### SMS not sending
120
122
 
121
- 1. **Verify credentials**: Run `npx @hrushiborhade/pingme test` to send a test message
122
- 2. **Check Twilio balance**: Free trial includes $15 credit; ensure it's not exhausted
123
- 3. **Verify phone numbers**: Both numbers must include country code (e.g., `+1` for US)
124
- 4. **Trial account limitations**: Twilio trial accounts can only send to verified numbers
123
+ 1. Run `npx @hrushiborhade/pingme test` to verify credentials
124
+ 2. Check your Twilio balance (free trial includes $15 credit)
125
+ 3. Verify both phone numbers include country code (e.g., `+1` for US)
126
+ 4. Twilio trial accounts can only send to verified numbers
125
127
 
126
128
  ### Hook not triggering
127
129
 
128
- 1. **Restart Claude Code**: Hooks are loaded on startup
129
- 2. **Check settings.json**: Verify hooks are present in `~/.claude/settings.json`
130
- 3. **Check script permissions**: Run `chmod +x ~/.claude/hooks/pingme.sh`
130
+ 1. Restart Claude Code — hooks are loaded on startup
131
+ 2. Verify hooks are present in `~/.claude/settings.json`
132
+ 3. Check script permissions: `chmod +x ~/.claude/hooks/pingme.sh`
131
133
 
132
- ### "curl not found" or no SMS sent
134
+ ### curl not found
133
135
 
134
- The hook script requires `curl`. Install it via your package manager:
136
+ Install via your package manager:
135
137
  - macOS: `brew install curl` (usually pre-installed)
136
138
  - Ubuntu/Debian: `sudo apt install curl`
137
139
 
138
- ### Uninstalling
139
-
140
- ```bash
141
- npx @hrushiborhade/pingme uninstall
142
- ```
143
-
144
- This removes the hook script and cleans up all hook entries from `~/.claude/settings.json`.
145
-
146
- ## Requirements
147
-
148
- - Node.js 18+
149
- - Twilio account (free trial includes $15 credit)
150
- - Claude Code CLI
151
- - `curl` (pre-installed on most systems)
152
- - `jq` (optional — enables richer context extraction from JSON input)
153
-
154
140
  ## Contributing
155
141
 
156
- Contributions are welcome! Here's how to get started:
157
-
158
- 1. Fork the repository
159
- 2. Create a feature branch: `git checkout -b feature/my-feature`
160
- 3. Make your changes
161
- 4. Run the build: `npm run build`
162
- 5. Test locally: `npm start init`
163
- 6. Commit your changes: `git commit -m 'Add my feature'`
164
- 7. Push to your fork: `git push origin feature/my-feature`
165
- 8. Open a Pull Request
166
-
167
- ### Development
142
+ Contributions are welcome.
168
143
 
169
144
  ```bash
170
145
  git clone https://github.com/HrushiBorhade/pingme.git
171
146
  cd pingme
172
147
  npm install
173
- npm run dev # Watch mode for TypeScript
148
+ npm run dev # Watch mode
174
149
  npm run build # Build for production
175
150
  npm test # Run tests
176
151
  ```
177
152
 
153
+ 1. Fork the repository
154
+ 2. Create a feature branch: `git checkout -b feature/my-feature`
155
+ 3. Make your changes and run `npm run build && npm test`
156
+ 4. Open a Pull Request
157
+
178
158
  ### Ideas for Contribution
179
159
 
180
160
  - Support for other notification providers (Slack, Discord, Pushover)
@@ -184,8 +164,4 @@ npm test # Run tests
184
164
 
185
165
  ## License
186
166
 
187
- MIT
188
-
189
- ---
190
-
191
- Built for developers who run AI agents and want their life back.
167
+ [MIT](LICENSE)
package/dist/index.js CHANGED
@@ -4,7 +4,7 @@ import { init } from './commands/init.js';
4
4
  import { test } from './commands/test.js';
5
5
  import { uninstall } from './commands/uninstall.js';
6
6
  import { events } from './commands/events.js';
7
- const VERSION = '1.1.0';
7
+ const VERSION = '1.1.1';
8
8
  async function main() {
9
9
  const args = process.argv.slice(2);
10
10
  const command = args[0] || 'init';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hrushiborhade/pingme",
3
- "version": "1.1.0",
3
+ "version": "1.1.1",
4
4
  "description": "Get texted when your Claude agent is stuck",
5
5
  "type": "module",
6
6
  "bin": {