nights-watch

Claude Nights Watch 🌙

🚀 NEW: Now available as a Claude Code Plugin! 🎉

Autonomous task execution system for Claude CLI that monitors your usage windows and executes predefined tasks automatically. Built on top of the claude-auto-renew concept but instead of simple renewals, it executes complex tasks from a task.md file.

⚠️ Warning: This tool uses --dangerously-skip-permissions for autonomous execution. Use with caution!

🎯 Two Ways to Use Claude Nights Watch

Choose your preferred installation method:

🔥 Recommended: Claude Code Plugin (NEW!)

• Seamless Integration: Works directly within Claude Code
• 7 Slash Commands: /nights-watch start/stop/status/logs/task/setup/restart
• AI Agent Integration: Built-in Task Executor agent for autonomous guidance
• Smart Hooks: Automatic session integration and activity logging
• MCP Server: Programmatic control tools for Claude
• Enhanced UX: Better error handling and user experience

⚡ Original Daemon Method (Legacy)

• Standalone Operation: Works independently of Claude Code
• Script-based Control: Direct shell script execution
• Proven Reliability: Battle-tested daemon implementation
• Full Feature Set: All core functionality available

🎯 Overview

Claude Nights Watch extends the auto-renewal concept to create a fully autonomous task execution system. When your Claude usage window is about to expire, instead of just saying "hi", it reads your task.md file and executes the defined tasks autonomously.

Key Features

• 🤖 Autonomous Execution: Runs tasks without manual intervention
• 📋 Task-Based Workflow: Define tasks in a simple markdown file
• 🛡️ Safety Rules: Configure safety constraints in rules.md
• ⏰ Smart Timing: Uses ccusage for accurate timing or falls back to time-based checking
• 📅 Scheduled Start: Can be configured to start at a specific time
• 📊 Comprehensive Logging: Track all activities and executions
• 🔄 Based on Proven Code: Built on the reliable claude-auto-renew daemon

🚀 Quick Start

Prerequisites

1. Claude CLI installed and configured
2. (Optional) ccusage for accurate timing:

   npm install -g ccusage
   

---

🔥 Plugin Installation (Recommended)

Option 1: As Claude Code Plugin

Standard Installation

# Method 1: From marketplace
claude plugin marketplace add https://github.com/aniketkarne/ClaudeNightsWatch
claude plugin install claude-nights-watch@claude-nights-watch-marketplace

# Method 2: Direct from GitHub
claude plugin install https://github.com/aniketkarne/ClaudeNightsWatch

# Method 3: From local directory (for development)
claude plugin marketplace add /path/to/ClaudeNightsWatch
claude plugin install claude-nights-watch@claude-nights-watch-marketplace

One-Command Installation

Use the Claude Plugins CLI to skip the marketplace setup:

npx claude-plugins install @aniketkarne/claude-nights-watch-marketplace/claude-nights-watch

This automatically adds the marketplace and installs the plugin in a single step.

Plugin Usage

# Interactive setup
/nights-watch setup

# Start daemon
/nights-watch start

# Check status
/nights-watch status

# View logs in real-time
/nights-watch logs -f

# Stop daemon
/nights-watch stop

Plugin Features:

• 🎯 7 Slash Commands: /nights-watch start/stop/status/logs/task/setup/restart
• 🧠 AI Agent: Built-in Task Executor for autonomous guidance
• 🔗 MCP Server: 8 programmatic tools for Claude control
• 🎣 Smart Hooks: Automatic session integration

---

⚡ Original Daemon Installation (Legacy)

Option 2: Install as Standalone Daemon

1. Clone this repository:

   git clone https://github.com/aniketkarne/ClaudeNightsWatch.git
   cd ClaudeNightsWatch
   

2. Make scripts executable:

   chmod +x *.sh
   

3. Run the interactive setup:

   ./setup-nights-watch.sh
   

Daemon Usage

1. Create your task file (task.md):

   # Daily Development Tasks
   
   1. Run linting on all source files
   2. Update dependencies to latest versions
   3. Run the test suite
   4. Generate coverage report
   5. Create a summary of changes
   

2. Create safety rules (rules.md):

   # Safety Rules
   
   - Never delete files without backing up
   - Only work within the project directory
   - Always create feature branches for changes
   - Never commit sensitive information
   

3. Start the daemon:

   ./claude-nights-watch-manager.sh start
   

Legacy Commands:

./claude-nights-watch-manager.sh start [--at TIME]  # Start daemon
./claude-nights-watch-manager.sh stop              # Stop daemon
./claude-nights-watch-manager.sh status            # Check status
./claude-nights-watch-manager.sh logs [-f]         # View logs
./claude-nights-watch-manager.sh task              # View task/rules
./claude-nights-watch-manager.sh restart           # Restart daemon

📝 Configuration

Task File (task.md)

The task file contains the instructions that Claude will execute. It should be clear, specific, and well-structured. See examples/task.example.md for a comprehensive example.

Rules File (rules.md)

The rules file defines safety constraints and best practices. It's prepended to every task execution to ensure safe autonomous operation. See examples/rules.example.md for recommended rules.

Environment Variables

• CLAUDE_NIGHTS_WATCH_DIR: Set the directory containing task.md and rules.md (default: current directory)

🎮 Commands

🔥 Plugin Commands (NEW!)

When using as a Claude Code plugin, use slash commands:

# Start the daemon
/nights-watch start

# Start with scheduled time
/nights-watch start --at "09:00"
/nights-watch start --at "2025-01-28 14:30"

# Stop the daemon
/nights-watch stop

# Check status
/nights-watch status

# View logs
/nights-watch logs
/nights-watch logs -f  # Follow mode

# View current task and rules
/nights-watch task

# Interactive setup
/nights-watch setup

# Restart daemon
/nights-watch restart

⚡ Original Daemon Commands (Legacy)

For standalone daemon usage:

# Start the daemon
./claude-nights-watch-manager.sh start

# Start with scheduled time
./claude-nights-watch-manager.sh start --at "09:00"
./claude-nights-watch-manager.sh start --at "2025-01-28 14:30"

# Stop the daemon
./claude-nights-watch-manager.sh stop

# Check status
./claude-nights-watch-manager.sh status

# View logs
./claude-nights-watch-manager.sh logs
./claude-nights-watch-manager.sh logs -f  # Follow mode

# Use interactive log viewer
./view-logs.sh

# View current task and rules
./claude-nights-watch-manager.sh task

# Restart daemon
./claude-nights-watch-manager.sh restart

---

🧠 Plugin Features (NEW!)

Task Executor Agent

Built-in AI agent that helps with:

• Autonomous Task Planning: Designing effective autonomous workflows
• Safety Rule Creation: Building comprehensive safety constraints
• Daemon Management: Starting, stopping, and troubleshooting
• Log Analysis: Interpreting execution results and identifying issues

Usage:

User: "Help me create an autonomous code review workflow"
Agent: Provides expert guidance and can execute /nights-watch commands

User: "My daemon isn't working, help debug"
Agent: Analyzes logs and suggests solutions

MCP Server Integration

Provides 8 programmatic tools for Claude:

• get_daemon_status - Query daemon state
• start_daemon - Start with optional schedule
• stop_daemon - Stop the daemon
• get_logs - Retrieve log entries
• read_task - Read task.md content
• read_rules - Read rules.md content
• write_task - Update task.md
• write_rules - Update rules.md

Smart Hooks

Automatic integration with Claude Code sessions:

• SessionStart: Shows daemon status when starting Claude Code
• SessionEnd: Prompts to start daemon if tasks are configured
• PostToolUse: Logs file modifications for audit trail

These hooks run silently in the background, enhancing your workflow.

🔧 How It Works

1. Monitoring: The daemon continuously monitors your Claude usage windows
2. Timing: When approaching the 5-hour limit (within 2 minutes), it prepares for execution
3. Task Preparation: Reads both rules.md and task.md, combining them into a single prompt
4. Autonomous Execution: Executes the task using claude --dangerously-skip-permissions
5. Logging: All activities are logged to logs/claude-nights-watch-daemon.log

Timing Logic

• With ccusage: Gets accurate remaining time from the API
• Without ccusage: Falls back to timestamp-based checking
• Adaptive intervals:
  • >30 minutes remaining: Check every 10 minutes
  • 5-30 minutes remaining: Check every 2 minutes
  • <5 minutes remaining: Check every 30 seconds

⚠️ Safety Considerations

IMPORTANT: This tool runs Claude with the --dangerously-skip-permissions flag, meaning it will execute tasks without asking for confirmation.

Best Practices:

1. Always test tasks manually first before setting up autonomous execution
2. Use comprehensive rules.md to prevent destructive actions
3. Start with simple, safe tasks and gradually increase complexity
4. Monitor logs regularly to ensure proper execution
5. Keep backups of important data
6. Run in isolated environments when possible

Recommended Restrictions:

• Limit file system access to project directories
• Prohibit deletion commands
• Prevent system modifications
• Restrict network access
• Set resource limits

📁 File Structure

🔥 Plugin Structure (NEW!)

When installed as a Claude Code plugin, the following structure is used:

claude-nights-watch/
├── .claude-plugin/                    # Plugin metadata (NEW!)
│   └── plugin.json                   # Plugin manifest
├── commands/                         # Slash command definitions (NEW!)
│   ├── bin/nights-watch             # Command wrapper
│   ├── start.md                     # Start command documentation
│   ├── stop.md                      # Stop command documentation
│   ├── status.md                    # Status command documentation
│   ├── logs.md                      # Logs command documentation
│   ├── task.md                      # Task command documentation
│   ├── setup.md                     # Setup command documentation
│   └── restart.md                   # Restart command documentation
├── agents/                           # AI agents (NEW!)
│   └── task-executor.md             # Autonomous task planning agent
├── hooks/                            # Event handlers (NEW!)
│   ├── hooks.json                   # Hook configuration
│   └── scripts/                     # Hook implementation scripts
│       ├── check-daemon-status.sh   # Session start hook
│       ├── session-end-prompt.sh    # Session end hook
│       └── log-file-changes.sh      # File modification hook
├── mcp-server/                       # Model Context Protocol (NEW!)
│   └── nights-watch-server.sh       # MCP server implementation
├── .mcp.json                        # MCP server configuration (NEW!)
└── [original files continue below...]

⚡ Original Daemon Structure (Legacy)