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

Claude CLI installed and configured
(Optional) ccusage for accurate timing:
```
npm install -g ccusage
```

🔥 Plugin Installation (Recommended)

Option 1: Install as Claude Code Plugin

# Method 1: From marketplace (when available)
claude plugins marketplace add https://github.com/aniketkarne/claude-plugins-marketplace
claude plugins add claude-nights-watch

# Method 2: Direct from GitHub
claude plugins add https://github.com/aniketkarne/ClaudeNightsWatch

# Method 3: From local directory (for development)
claude plugins add /path/to/ClaudeNightsWatch

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

Clone this repository:

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

Make scripts executable:
```
chmod +x *.sh
```
Run the interactive setup:
```
./setup-nights-watch.sh
```

Daemon Usage

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

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

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

Monitoring: The daemon continuously monitors your Claude usage windows
Timing: When approaching the 5-hour limit (within 2 minutes), it prepares for execution
Task Preparation: Reads both rules.md and task.md, combining them into a single prompt
Autonomous Execution: Executes the task using claude --dangerously-skip-permissions
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:

Always test tasks manually first before setting up autonomous execution
Use comprehensive rules.md to prevent destructive actions
Start with simple, safe tasks and gradually increase complexity
Monitor logs regularly to ensure proper execution
Keep backups of important data
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)

The original standalone daemon structure:

claude-nights-watch/
├── claude-nights-watch-daemon.sh      # Core daemon process
├── claude-nights-watch-manager.sh     # Daemon management interface
├── setup-nights-watch.sh              # Interactive setup script
├── view-logs.sh                       # Interactive log viewer
├── README.md                          # This file
├── LICENSE                            # MIT License
├── CONTRIBUTING.md                    # Contribution guidelines
├── CHANGELOG.md                       # Version history
├── SUMMARY.md                         # Project summary
├── .gitignore                         # Git ignore file
├── .github/                           # GitHub templates
│   ├── ISSUE_TEMPLATE/
│   │   ├── bug_report.md
│   │   └── feature_request.md
│   └── pull_request_template.md
├── logs/                              # All logs stored here (created on first run)
├── examples/                          # Example files
│   ├── task.example.md                # Example task file
│   └── rules.example.md               # Example rules file
└── test/                              # Test scripts and files
    ├── README.md                      # Testing documentation
    ├── test-immediate-execution.sh    # Direct task execution test
    ├── test-simple.sh                 # Simple functionality test
    ├── test-task-simple.md            # Simple test task
    ├── test-rules-simple.md           # Simple test rules
    ├── test-plugin-comprehensive.sh   # Plugin functionality tests (NEW!)
    └── test-functional-realworld.sh   # Real-world testing suite (NEW!)

📊 Logging

All logs are stored in the logs/ directory within the project. Each log contains:

Timestamps: Every action is timestamped
Full Prompts: Complete prompt sent to Claude (rules + task)
Full Responses: Everything Claude outputs
Status Messages: Success/failure indicators

Viewing Logs

Use the interactive log viewer:

./view-logs.sh

Features:

Browse all log files
View full logs or last 50 lines
Filter to see only prompts sent to Claude
Filter to see only Claude's responses
Search for errors
Follow logs in real-time

🧪 Testing

Plugin Testing (NEW!)

Comprehensive test suites for the Claude Code plugin:

cd test

# Run comprehensive plugin structure tests
./test-plugin-comprehensive.sh

# Run functional and real-world testing
./test-functional-realworld.sh

# Run immediate execution test (no waiting)
./test-immediate-execution.sh

# Run simple functionality test
./test-simple.sh

Original Daemon Testing (Legacy)

cd test
./test-simple.sh  # Run a simple test

See test/README.md for detailed testing instructions.

New Testing Features:

Plugin Structure Validation: Tests all plugin components
Functional Testing: Validates script execution and integration
Real-World Simulation: Tests complete user workflows
Environment Testing: Validates plugin environment variables
Error Handling: Tests graceful failure scenarios

🐛 Troubleshooting

Plugin Issues (NEW!)

Plugin not loading:

# Check plugin installation
claude plugins list | grep claude-nights-watch

# Reinstall if needed
claude plugins remove claude-nights-watch
claude plugins add https://github.com/aniketkarne/ClaudeNightsWatch

# Debug mode
claude --debug

Commands not working:

# Verify command scripts are executable
ls -la ~/.claude/plugins/claude-nights-watch/commands/bin/

# Make executable if needed
chmod +x ~/.claude/plugins/claude-nights-watch/commands/bin/nights-watch

Agent not responding:

Ensure plugin is properly installed
Check that agent file exists in agents/task-executor.md
Verify MCP server is running

Original Daemon Issues (Legacy)

Daemon won't start:

Check if Claude CLI is installed: which claude
Verify task.md exists in the working directory
Check logs: ./claude-nights-watch-manager.sh logs

Tasks not executing:

Verify you have remaining Claude usage: ccusage blocks
Check if past scheduled start time
Ensure task.md is not empty
Review logs for errors

Timing issues:

Install ccusage for better accuracy: npm install -g ccusage
Check system time is correct
Verify .claude-last-activity timestamp

Common Issues (Both Methods)

Permission errors:

# Ensure all scripts are executable
chmod +x *.sh
chmod +x commands/bin/nights-watch
chmod +x hooks/scripts/*.sh
chmod +x mcp-server/*.sh

Missing dependencies:

Install Claude CLI: https://docs.anthropic.com/claude-code
Install ccusage: npm install -g ccusage (recommended)
Verify bash is available: which bash

Configuration issues:

Check task.md exists and has content
Verify rules.md exists (recommended)
Ensure proper file permissions
Check environment variables

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository on GitHub
Clone your fork locally
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes following our guidelines
Test thoroughly using the test suite
Commit your changes (git commit -m 'Add amazing feature')
Push to your fork (git push origin feature/amazing-feature)
Create a Pull Request on GitHub

Please ensure:

Code follows existing style
Safety is prioritized
Documentation is updated
Examples are provided
Tests pass

See CONTRIBUTING.md for detailed guidelines.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Created by: Aniket Karne
Built on top of: The excellent CCAutoRenew project
Plugin Development: Complete Claude Code plugin implementation with slash commands, AI agents, MCP server, and smart hooks
Enhanced Features: Task Executor agent, comprehensive testing suites, and dual installation methods
Thanks to: The Claude CLI team for the amazing tool and plugin system

🔄 Migration Guide

From Daemon to Plugin

If you're currently using the standalone daemon and want to migrate to the plugin:

Install the plugin:

claude plugins add https://github.com/aniketkarne/ClaudeNightsWatch

Copy your existing files:

# Copy your task.md and rules.md to the new location
cp task.md rules.md ~/.claude/plugins/claude-nights-watch/

Update your workflow:
- Replace ./claude-nights-watch-manager.sh start with /nights-watch start
- Replace ./claude-nights-watch-manager.sh logs with /nights-watch logs
- Use /nights-watch setup for configuration
Benefits you'll gain:
- 🤖 AI Agent Integration: Get help from the Task Executor agent
- 🎯 Better Commands: More intuitive slash command interface
- 🔗 MCP Integration: Programmatic control for Claude
- 🎣 Smart Hooks: Automatic session integration

From Plugin to Daemon

If you prefer the standalone approach:

Install as daemon:

git clone https://github.com/aniketkarne/ClaudeNightsWatch.git
cd ClaudeNightsWatch
chmod +x *.sh

Copy your plugin files:

# Copy from plugin location to daemon location
cp ~/.claude/plugins/claude-nights-watch/task.md .
cp ~/.claude/plugins/claude-nights-watch/rules.md .

Use daemon commands:
```
./claude-nights-watch-manager.sh start
```

Note: The plugin method is recommended for new users due to better integration and enhanced features.

Remember: With great automation comes great responsibility. Always review your tasks and rules carefully before enabling autonomous execution! 🚨

Name		Name	Last commit message	Last commit date
Latest commit History 17 Commits
.claude-plugin		.claude-plugin
.github		.github
agents		agents
claude-plugins-marketplace		claude-plugins-marketplace
commands		commands
examples		examples
hooks		hooks
marketplace-example		marketplace-example
mcp-server		mcp-server
test		test
.gitignore		.gitignore
.mcp.json		.mcp.json
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
claude-nights-watch-daemon.sh		claude-nights-watch-daemon.sh
claude-nights-watch-manager.sh		claude-nights-watch-manager.sh
setup-nights-watch.sh		setup-nights-watch.sh
verify-plugin.sh		verify-plugin.sh
view-logs.sh		view-logs.sh

License

aniketkarne/ClaudeNightsWatch

Folders and files

Latest commit

History

Repository files navigation