<!--
hoody-watch Subskill (http)
Auto-generated by Hoody Skills Generator
Generated: 2026-06-20T00:43:32.474Z
Model: mimo-v2.5-pro + fixer:mimo-v2.5-pro
Mode: http


Tokens: 3871

DO NOT EDIT MANUALLY - Changes will be overwritten on next generation
-->

# hoody-watch Subskill

## Overview

The `hoody-watch` service provides real-time filesystem monitoring and event streaming for applications deployed in Hoody containers. It enables agents and users to set up watchers on specific file paths and receive real-time notifications when files change, are created, or deleted.

### Core Philosophy Alignment
- **Reactive Architecture**: Enables event-driven workflows instead of polling
- **Declarative Configuration**: Define watchers through simple path-based configuration
- **Real-time Feedback**: Provides immediate awareness of system state changes
- **Decoupled Monitoring**: Observes application behavior without direct integration

### When to Use hoody-watch
- Monitor configuration files for runtime changes
- Watch log files for error patterns
- Track data file modifications in real-time
- Implement file-based workflows and automation
- Debug application state through filesystem observation

## Common Workflows

### 1. Health Check & Service Verification

Before performing operations, verify the watch service is operational:

```
# Check service health
curl -s "https://{projectId}-{containerId}-watch-{serviceId}.{node}.containers.hoody.com/api/v1/watch/health"
```

**Expected Response**:
```
{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z"
}
```

**Verification**: Ensure response contains `"status": "healthy"` before proceeding.

### 2. Creating File System Watchers

Set up watchers to monitor specific filesystem paths:

```
# Create a watcher for configuration files
curl -s -X POST "https://{projectId}-{containerId}-watch-{serviceId}.{node}.containers.hoody.com/watchers" \
  -H "Content-Type: application/json" \
  -d '{
  "paths": ["/app/config", "/app/logs"]
}'
```

**Expected Response**:
```
{
  "id": "watcher_123abc",
  "paths": ["/app/config", "/app/logs"],
  "status": "active",
  "createdAt": "2024-01-15T10:30:00Z"
}
```

**Verification**: Save the `id` from the response for subsequent operations.

### 3. Managing Watchers

**List all active watchers**:
```
curl -s "https://{projectId}-{containerId}-watch-{serviceId}.{node}.containers.hoody.com/watchers"
```

**Get specific watcher details**:
```
curl -s "https://{projectId}-{containerId}-watch-{serviceId}.{node}.containers.hoody.com/watchers/watcher_123abc"
```

**Delete a watcher when no longer needed**:
```
curl -s -X DELETE "https://{projectId}-{containerId}-watch-{serviceId}.{node}.containers.hoody.com/watchers/watcher_123abc"
```

### 4. Real-time Event Monitoring

**Retrieve recent events (HTTP polling)**:
```
curl -s "https://{projectId}-{containerId}-watch-{serviceId}.{node}.containers.hoody.com/watchers/watcher_123abc/events"
```

**Expected Response**:
```
[
  {
    "timestamp": "2024-01-15T10:35:00Z",
    "type": "modified",
    "path": "/app/config/settings.json",
    "details": {
      "sizeChange": 128,
      "permissionsChanged": false
    }
  }
]
```

### 5. SSE Event Streaming (Recommended for Long-lived Connections)

For persistent real-time updates without polling:

```
# Stream events via Server-Sent Events
curl -s -H "Accept: text/event-stream" "https://{projectId}-{containerId}-watch-{serviceId}.{node}.containers.hoody.com/watchers/watcher_123abc/events/sse"
```

**SSE Stream Format**:
```
event: file_modified
data: {"timestamp":"2024-01-15T10:40:00Z","path":"/app/config/settings.json"}

event: file_created
data: {"timestamp":"2024-01-15T10:45:00Z","path":"/app/logs/access.log"}
```

## Advanced Operations

### Multi-path Watcher Configuration

Create watchers with multiple paths for comprehensive monitoring:

```
# Monitor both application and system files
curl -s -X POST "https://{projectId}-{containerId}-watch-{serviceId}.{node}.containers.hoody.com/watchers" \
  -H "Content-Type: application/json" \
  -d '{
  "paths": [
    "/app/src",
    "/app/config",
    "/var/log/app",
    "/tmp/shared"
  ]
}'
```

### Watcher Lifecycle Management

**Error Recovery Pattern**:
1. Check service health first
2. List existing watchers to avoid duplicates
3. Create watcher with appropriate paths
4. Verify watcher creation via GET request
5. Monitor events to confirm functionality

**Example Workflow**:
```
# Step 1: Health check
health_response=$(curl -s "https://{projectId}-{containerId}-watch-{serviceId}.{node}.containers.hoody.com/api/v1/watch/health")
echo "$health_response" | grep -q '"status":"healthy"' || exit 1

# Step 2: Check for existing watchers
existing=$(curl -s "https://{projectId}-{containerId}-watch-{serviceId}.{node}.containers.hoody.com/watchers")
echo "Existing watchers: $existing"

# Step 3: Create watcher
create_response=$(curl -s -X POST "https://{projectId}-{containerId}-watch-{serviceId}.{node}.containers.hoody.com/watchers" \
  -H "Content-Type: application/json" \
  -d '{
  "paths": ["/app/config"]
}')
watcher_id=$(echo "$create_response" | grep -o '"id":"[^"]*"' | cut -d'"' -f4)

# Step 4: Verify creation
curl -s "https://{projectId}-{containerId}-watch-{serviceId}.{node}.containers.hoody.com/watchers/$watcher_id"
```

### Performance Considerations

1. **Path Specificity**: Watch specific directories rather than broad filesystem paths
2. **Watcher Limits**: Monitor only critical paths to reduce resource consumption
3. **Event Filtering**: Use event types from SSE streams to filter relevant changes
4. **Connection Management**: For SSE/WebSocket, implement proper reconnection logic

### WebSocket Event Streaming

For bidirectional communication capabilities:

```
# Connect via WebSocket (requires wscat or similar tool)
wscat -c "wss://{projectId}-{containerId}-watch-{serviceId}.{node}.containers.hoody.com/watchers/watcher_123abc/events/ws"
```

## Quick Reference

### Essential Endpoints

| Method | Path | Purpose |
|--------|------|---------|
| `GET` | `/api/v1/watch/health` | Service health check |
| `POST` | `/watchers` | Create filesystem watcher |
| `GET` | `/watchers` | List all watchers |
| `GET` | `/watchers/{id}` | Get watcher details |
| `DELETE` | `/watchers/{id}` | Remove watcher |
| `GET` | `/watchers/{id}/events` | Get recent events (HTTP) |
| `GET` | `/watchers/{id}/events/sse` | Stream events (SSE) |
| `GET` | `/watchers/{id}/events/ws` | Stream events (WebSocket) |

### Required Parameters

**Create Watcher (`POST /watchers`)**:
```
{
  "paths": ["/absolute/path", "/relative/path"]
}
```
- `paths`: Array of filesystem paths to monitor (required)

### Typical Response Formats

**Watcher Object**:
```
{
  "id": "string",
  "paths": ["string"],
  "status": "active|inactive",
  "createdAt": "ISO8601 timestamp"
}
```

**Event Object**:
```
{
  "timestamp": "ISO8601 timestamp",
  "type": "created|modified|deleted",
  "path": "string",
  "details": {
    "sizeChange": 0,
    "permissionsChanged": false
  }
}
```

### Base URL Pattern
```
https://{projectId}-{containerId}-watch-{serviceId}.{node}.containers.hoody.com
```
Replace placeholders with actual values from your Hoody deployment.