Ping

Let AI Agents Ping You

Kick off a long build, walk away to grab coffee, and know exactly when it finishes. Or better yet, make decisions right from your phone when the agent needs approval.

Ping is a native interaction system for AI coding agents. When you tell your agent to “ping me when done,” it sends rich, interactive prompts to your devices and waits for your response. Works with Claude Code, Codex, Cursor, Windsurf, VS Code, Zed, and any MCP-compatible client.

How It Works

You: "Run the full test suite and ping me when it's done"

Claude: *runs tests for 10 minutes*

Claude: ping("Tests complete: 234 passed, 2 failed",
             input_type="choice",
             options=["Show failures", "Continue", "Stop"])

Your phone: "Tests complete: 234 passed, 2 failed"
            [Show failures] [Continue] [Stop]

You: *tap* "Show failures"

Claude: *receives your response and continues*

By default, ping() waits for your response (up to 5 minutes by default via the MCP tool timeout). The native dialog stays visible on screen for up to 10 minutes (configurable via dialog.timeout). The AI doesn’t continue until you respond or the MCP tool timeout expires.

Input Types

Ping supports 7 input types for different kinds of interactions:

notify - One-way notification (no response expected)

ping("Build complete: 0 errors", input_type="notify")

confirmation - Yes/no decision

ping("Deploy to production?", input_type="confirmation")
→ true / false

choice - Pick one option from a list (up to 20 options)

ping("Which branch?", input_type="choice",
     options=["main", "develop", "staging"])
→ "main"

multi_select - Pick multiple options

ping("Select services to restart:",
     input_type="multi_select",
     options=["api", "web", "worker", "scheduler"])
→ ["api", "worker"]

text - Free-form text input

ping("Enter the release tag:", input_type="text")
→ "v2.4.1"

secure_text - Password/secret input (masked, not saved to history)

ping("Enter deploy token:", input_type="secure_text")
→ "ghp_xxxx..."

questions - Multi-field form (up to 20 fields, wizard or accordion layout)

ping("Configure deployment:",
     input_type="questions",
     questions=[
       {"id": "env", "label": "Environment", "type": "choice",
        "options": ["staging", "production"]},
       {"id": "tag", "label": "Release tag", "type": "text"},
       {"id": "notify", "label": "Notify team?", "type": "confirmation"}
     ])
→ {"env": "staging", "tag": "v2.4.1", "notify": true}

Smart Routing

Ping automatically chooses the best way to reach you:

You’re at…	Free (Local)	Pro (Cloud)
Your computer	Native dialog on screen	Native dialog on screen
Away / idle	Dialog waits for you	Push notification to phone
Screen locked	Dialog waits for you	Push notification to phone

The routing is fully configurable. Set prefer = "local" to always use the native dialog, prefer = "remote" to always push to your devices, or leave it on "auto" (default) to let Ping decide based on your idle time.

Configuration

Ping is configured via a platform-specific config file:

• macOS: ~/Library/Application Support/strayfiles-ping/config.toml
• Linux: ~/.config/strayfiles-ping/config.toml

Run strayfiles-ping config path to see the exact location on your system.

[dialog]
enabled = true          # Enable native dialog popups
position = "top-right"  # Dialog position on screen
timeout = 600           # Dialog display timeout in seconds (1-3600)
sound = "none"          # Notification sound
always_on_top = true    # Keep dialog above other windows
cooldown = false        # Rate-limit dialog popups
cooldown_duration = 1.0 # Seconds between dialogs (0.1-3.0)

[routing]
prefer = "auto"         # "auto", "local", or "remote"
idle_threshold = 120    # Seconds of inactivity before routing remote

[theme]
accent = ""             # Custom accent color (hex, e.g. "#F5D547")

You can also configure via CLI:

strayfiles-ping config set dialog.timeout 300
strayfiles-ping config set routing.prefer local
strayfiles-ping config list
strayfiles-ping config path
strayfiles-ping config reset

Snooze

Temporarily silence all pings. When a native dialog appears, you can choose to snooze directly from the dialog UI. You can also manage snooze via the config:

# Check current snooze status
strayfiles-ping config get snooze.until

# Clear snooze early
strayfiles-ping config set snooze.until none

While snoozed, ping() returns immediately with a “snoozed” status so the agent knows you’re unavailable and can continue autonomously.

Feedback and Comments

Every interaction supports optional feedback. After responding, you can:

• Add a comment (free-form text sent back to the agent alongside your response)
• Leave feedback (thumbs up/down on the ping itself)

This helps the agent learn which pings are useful and which are noise.

Interaction History

Ping keeps a local history of all interactions (except secure_text, which is never recorded):

# View recent history (last 10 by default)
strayfiles-ping history show

# Show more entries
strayfiles-ping history show -n 25

# Filter by project
strayfiles-ping history show --project my-app

# Filter by date
strayfiles-ping history show --since 2026-02-01

# Search history
strayfiles-ping history show --search "deploy"

# Clear history
strayfiles-ping history clear

History is stored per-day in ~/.local/share/strayfiles-ping/history/ as JSON files. Each day caps at 200 entries and old files are automatically cleaned up.

Setting Up Ping

Ping works with any MCP-compatible AI coding agent.

Step 1: Install the binary

curl -fsSL https://strayfiles.com/ping-install.sh | sh

This installs only the Ping binaries required by MCP (strayfiles-ping and optional strayfiles-dialog on macOS), not the full macOS app bundle/DMG.

Step 2: Add the MCP server to your agent

Claude Code:

claude mcp add --transport stdio strayfiles-ping -- strayfiles-ping

Or use the plugin for auto-configuration (includes skills and prompts):

claude plugin install https://github.com/titofebus/strayfiles-ping.git

Codex:

codex mcp add strayfiles-ping -- strayfiles-ping

Cursor — add to .cursor/mcp.json:

{"mcpServers":{"strayfiles-ping":{"command":"strayfiles-ping"}}}

Windsurf — add to ~/.codeium/windsurf/mcp_config.json:

{"mcpServers":{"strayfiles-ping":{"command":"strayfiles-ping"}}}

VS Code — add to .vscode/mcp.json:

{"servers":{"strayfiles-ping":{"type":"stdio","command":"strayfiles-ping"}}}

Zed — add to your Zed settings:

{"context_servers":{"strayfiles-ping":{"command":"strayfiles-ping","args":[]}}}

Step 3 (Optional): Authenticate for cloud sync

strayfiles-ping auth

The auth token is verified online against your Strayfiles account before it is stored locally.

After installation, Ping works immediately in free mode with native dialogs on your screen. No account required.

To enable Pro mode with cross-device push notifications:

1. Run strayfiles-ping auth and sign in with your Strayfiles Pro account
2. Restart your agent
3. Pings will now sync across all your devices

Receiving Notifications

Device	Free (Local)	Pro (Cloud)
Native dialog	Same machine	Same machine
Strayfiles TUI	Same machine	All devices
iPhone/iPad	---	Push notifications
Mac (native app)	---	System notifications

Free mode:

• Native macOS dialog appears on screen with buttons, text fields, and forms
• Falls back to TUI notifications if the dialog binary isn’t installed
• No account required

Pro mode:

• All free features, plus cross-device push notifications
• First device to respond wins
• Rich interactions on iOS (quick-reply buttons, text input)

Natural Triggers

You don’t need special commands. Agents recognize natural phrases:

• “Ping me when you’re done”
• “Let me know when the build finishes”
• “Ask me before deploying”
• “Notify me if there are errors”

Auto-Response Queue

Pre-write responses that automatically answer future pings. When the agent sends a ping, it first checks your queue. If responses are available, the oldest one is used automatically.

strayfiles-ping queue add "continue"
strayfiles-ping queue add "yes, keep going"
strayfiles-ping queue list
strayfiles-ping queue remove <id>
strayfiles-ping queue clear

Responses are used in FIFO order. Rate limited to 10 auto-responses per hour.

Privacy and Security

• End-to-end: Only you see your notifications
• Secure text: Password inputs are masked and never saved to history
• Ephemeral: Notifications disappear after response or expiration
• Lock screen safe: Messages truncated on lock screen
• Local-first: Free mode stores everything locally, no cloud required

Pricing

Feature	Free (Local)	Pro (Cloud)
All 7 input types	Local dialog	All devices
Native macOS dialog	Same machine	Same machine
TUI notifications	Same machine	All devices
Configuration and snooze	Local file	Local file
Interaction history	Local file	Local file
Queue auto-responses	Local file	Cloud sync
Push to iPhone/iPad	---	Pro only
Push to Mac native app	---	Pro only
Cross-device sync	---	Pro only
Feedback and comments	Local only	Synced

Free mode works immediately after installation with zero configuration. Native dialogs appear on your screen for all 7 input types.

Pro mode ($10/month) adds cross-device push notifications so you can respond from your phone when you’re away from your desk. Run strayfiles-ping auth to enable.

Troubleshooting

“Native dialog not appearing”

• Verify the dialog binary is installed: which strayfiles-dialog
• If missing, re-run: curl -fsSL https://strayfiles.com/ping-install.sh | sh
• On macOS, remove quarantine: xattr -d com.apple.quarantine $(which strayfiles-dialog)
• Check that dialog.enabled = true in config: strayfiles-ping config list

“Notifications not appearing on phone”

• Verify you’re signed in: strayfiles-ping status
• Check notification permissions in iOS Settings
• Make sure you’re signed into the same Strayfiles account on all devices

“Agent doesn’t seem to use ping”

• Verify the MCP server is registered in your agent’s settings
• Restart your agent after adding the MCP server
• Try explicitly saying “ping me when done”
• Run strayfiles-ping status to verify setup

“Response not received by agent”

• Check your internet connection (for Pro mode)
• Make sure you responded before the timeout
• If the agent moved on, just tell it your answer in chat

“Dialog appearing too frequently”

• Enable cooldown: strayfiles-ping config set dialog.cooldown true
• Adjust cooldown duration: strayfiles-ping config set dialog.cooldown_duration 2.0
• Or snooze temporarily via the native dialog UI

Requirements

• For free mode (local):

  • Any MCP-compatible agent with strayfiles-ping configured
  • macOS for native dialog (Linux falls back to TUI)
  • No account required

• For Pro mode (cross-device):

  • Strayfiles Pro subscription ($10/month)
  • Run strayfiles-ping auth to sign in
  • Strayfiles iOS or macOS app for push notifications