Skip to main content

​
watercooler_daemon_status

Get detailed status and findings from background daemons. Watercooler runs background daemons that periodically scan threads for hygiene issues, update metadata, and perform maintenance tasks.
Safety: Read-only tool - does not modify any state

​
Overview

Watercooler includes background daemons that:
  • thread_scanner: Periodically scans threads for new entries and metadata changes
  • hygiene: Checks for common issues (missing metadata, broken references, stale threads)
These daemons:
  • Run every N seconds (configurable)
  • Generate “findings” when issues detected
  • Auto-fix certain issues (if configured)
  • Track errors and retry failures

​
Parameters

​
daemon_name
string
default:"null"
Specific daemon to queryOptions:
  • "thread_scanner" - Thread scanning daemon
  • "hygiene" - Hygiene checking daemon
  • null - All daemons (default)
​
include_findings
boolean
default:"true"
Include detailed findings in output
​
code_path
string
default:""
Path to code repository for context-specific daemon status

​
Return Value

Returns JSON with daemon status:
​
daemons
object
Object mapping daemon names to status objects:
  • status: State (running/stopped/paused/failed)
  • interval: Run interval in seconds
  • total_ticks: Total executions since start
  • total_findings: Total issues found
  • error_count: Total errors encountered
  • last_run: Timestamp of last execution
  • last_error: Most recent error message (if any)
  • findings: List of recent findings (if include_findings=true)

​
Usage Examples

​
Get All Daemon Status

await use_mcp_tool(
    "watercooler_daemon_status",
    code_path="."
)

​
Get Specific Daemon

await use_mcp_tool(
    "watercooler_daemon_status",
    daemon_name="hygiene",
    code_path="."
)

​
Status Without Findings

await use_mcp_tool(
    "watercooler_daemon_status",
    include_findings=False,
    code_path="."
)

​
Example Output

{
  "daemons": {
    "thread_scanner": {
      "status": "running",
      "interval": 300,
      "total_ticks": 48,
      "total_findings": 12,
      "error_count": 0,
      "last_run": "2025-01-15T14:30:00Z",
      "last_error": null,
      "findings": [
        {
          "type": "new_entries",
          "severity": "info",
          "message": "Found 3 new entries in feature-auth",
          "timestamp": "2025-01-15T14:30:00Z",
          "details": {
            "topic": "feature-auth",
            "entry_count": 3
          }
        },
        {
          "type": "metadata_update",
          "severity": "info",
          "message": "Updated thread summary for bug-fix-123",
          "timestamp": "2025-01-15T14:25:00Z",
          "details": {
            "topic": "bug-fix-123"
          }
        }
      ]
    },
    "hygiene": {
      "status": "running",
      "interval": 3600,
      "total_ticks": 8,
      "total_findings": 2,
      "error_count": 0,
      "last_run": "2025-01-15T14:00:00Z",
      "last_error": null,
      "findings": [
        {
          "type": "stale_thread",
          "severity": "warning",
          "message": "Thread inactive for 30 days: old-feature",
          "timestamp": "2025-01-15T14:00:00Z",
          "details": {
            "topic": "old-feature",
            "last_activity": "2024-12-15T10:00:00Z",
            "days_inactive": 31
          }
        }
      ]
    }
  }
}

​
Daemon States

​
Running

{
  "status": "running",
  "interval": 300,
  "total_ticks": 48
}
Daemon is active and executing on schedule.

​
Paused

{
  "status": "paused",
  "interval": 300,
  "total_ticks": 48,
  "last_error": "Rate limit exceeded"
}
Daemon temporarily paused (e.g., due to rate limits). Will resume automatically.

​
Failed

{
  "status": "failed",
  "error_count": 5,
  "last_error": "FalkorDB connection failed"
}
Daemon encountered fatal error and stopped. Requires manual intervention.

​
Disabled

{
  "status": "disabled"
}
Daemon not enabled in configuration.

​
Finding Types

​
thread_scanner Findings

new_entries
  • Severity: info
  • New entries detected in thread
  • Auto-triggers metadata refresh
metadata_update
  • Severity: info
  • Thread metadata updated (title, summary, status)
orphan_entries
  • Severity: warning
  • Entries found without corresponding thread
  • Suggests data corruption

​
hygiene Findings

stale_thread
  • Severity: warning
  • Thread inactive for >30 days
  • Consider closing or archiving
missing_metadata
  • Severity: warning
  • Thread missing meta.json file
  • Auto-fix: generates metadata from entries
broken_reference
  • Severity: error
  • Entry references non-existent file or commit
  • Requires manual review
duplicate_entry_id
  • Severity: error
  • Multiple entries with same Entry-ID
  • Data corruption - requires manual fix

​
Configuration

​
Enable/Disable Daemons

# config.toml
[mcp.daemons]
thread_scanner = true
hygiene = true
Or via environment: 
export WATERCOOLER_DAEMON_THREAD_SCANNER=true
export WATERCOOLER_DAEMON_HYGIENE=true

​
Set Intervals

[mcp.daemons]
thread_scanner_interval = 300  # 5 minutes
hygiene_interval = 3600        # 1 hour

​
Auto-Fix Settings

[mcp.daemons.hygiene]
auto_fix_metadata = true      # Auto-generate missing metadata
auto_archive_stale = false    # Don't auto-archive (require manual)

​
Troubleshooting

​
Daemon Not Running

Problem: Status shows “disabled” or “stopped” Solution: Enable in config: 
[mcp.daemons]
thread_scanner = true
Restart MCP server.

​
High Error Count

Problem: error_count increasing Solution: Check last_error for details: 
{
  "error_count": 10,
  "last_error": "FalkorDB connection timeout"
}
Fix underlying issue (e.g., start FalkorDB), errors will clear.

​
Paused Due to Rate Limits

Problem: Daemon paused with “Rate limit exceeded” Solution: Wait for rate limit reset (see watercooler_health): 
health = await use_mcp_tool("watercooler_health")
# Check "Rate Limit: X/5000 (Y%) - resets in Zmin"
Daemon will auto-resume after reset.

​
Many Findings

Problem: total_findings very high Solution: Review recent findings: 
await use_mcp_tool(
    "watercooler_daemon_status",
    daemon_name="hygiene",
    include_findings=True
)
Address issues manually or enable auto-fix.

​
Best Practices

​
Monitor Regularly

Check daemon status weekly: 
# Weekly health check
await use_mcp_tool("watercooler_daemon_status")

​
Review Findings

Periodically review findings: 
# Get hygiene findings
status = await use_mcp_tool(
    "watercooler_daemon_status",
    daemon_name="hygiene",
    include_findings=True
)
Address warnings and errors promptly.

​
Adjust Intervals

For active projects, decrease intervals: 
thread_scanner_interval = 120  # 2 minutes (more responsive)
For stable projects, increase intervals: 
thread_scanner_interval = 600  # 10 minutes (less overhead)

Build docs developers (and LLMs) love

Get started for freeTalk to us