Autonomous monitoring and management system for Claude Code sessions
Stop babysitting your AI coding agents. Let the Watchdog keep them productive while you focus on higher-value work.
- Overview
- The Problem
- The Solution
- Key Features
- How It Works
- Quick Start
- Project Structure
- Configuration
- Usage Examples
- Architecture
- Development
- Roadmap
- Contributing
- License
Claude Code Watchdog is a PowerShell-based automation system that monitors Claude Code sessions and intelligently manages their progression. It detects when sessions are waiting for input, makes decisions about how to proceed, and executes actions automatically - enabling true end-to-end autonomous development workflows.
Perfect for:
- Engineering managers overseeing multiple AI-assisted projects
- Developers running long-running refactoring or cleanup tasks
- Teams implementing AI-driven development pipelines
- Anyone tired of checking Claude Code every 10 minutes
Claude Code is powerful, but sessions frequently stall:
❌ "Continue with next TODO?" - Waiting for you to tell it to keep going
❌ "Phase complete" - Needs approval to commit and move forward
❌ Error encountered - Unsure how to proceed without guidance
❌ Ambiguous requirements - Pauses for clarification
Result: You spend your day monitoring AI agents instead of doing strategic work.
The Watchdog sits between you and Claude Code, acting as an intelligent intermediary:
✅ Continuous Monitoring - Polls Claude Code sessions every 2 minutes
✅ Smart Decision-Making - Uses Claude API + rules to decide next steps
✅ Autonomous Execution - Sends commands, makes commits, creates PRs
✅ Human-in-the-Loop - Pauses for your approval when configured
✅ Skill Integration - Leverages your Claude Skills for error resolution
✅ Multi-Project Support - Manages parallel workstreams simultaneously
Result: Set it and forget it. Get notified only when human judgment is needed.
- Detects 6 distinct Claude Code states (InProgress, HasTodos, Error, PhaseComplete, Idle, WaitingForInput)
- Identifies TODOs, errors, and completion indicators
- Tracks idle time and session health
- API-Powered: Uses Claude API to make contextual decisions
- Rule-Based Fallback: Works without API for cost control
- Skill-Aware: Automatically invokes appropriate Claude Skills for errors
- Configuration-Driven: Respects project-specific approval requirements
- Auto-Continue: Progresses through TODOs automatically
- Phase-Based Commits: Batches work into logical checkpoints
- PR Creation: Generates pull requests at phase boundaries
- Cost Management: Tracks API usage and enforces budgets
- Windows toast notifications for urgent items
- Comprehensive markdown decision logs
- Activity tracking per project
- Daily progress summaries
- Graceful error handling and retries
- Session recovery after crashes
- Secure credential storage
- Resource-efficient polling
┌─────────────────────────────────────────────┐
│ 1. You register a project with the │
│ Watchdog and start a Claude Code │
│ session │
└─────────────────┬───────────────────────────┘
│
v
┌─────────────────────────────────────────────┐
│ 2. Watchdog monitors the Claude Code UI │
│ every 2 minutes using Windows MCP │
└─────────────────┬───────────────────────────┘
│
v
┌─────────────────────────────────────────────┐
│ 3. Detects state: "Has 5 TODOs remaining" │
│ Checks project config: autoProgress=true│
└─────────────────┬───────────────────────────┘
│
v
┌─────────────────────────────────────────────┐
│ 4. Calls Claude API: "Should I continue │
│ with next TODO or use a skill?" │
└─────────────────┬───────────────────────────┘
│
v
┌─────────────────────────────────────────────┐
│ 5. API responds: {action: "continue", │
│ command: "Continue with next TODO"} │
└─────────────────┬───────────────────────────┘
│
v
┌─────────────────────────────────────────────┐
│ 6. Watchdog sends command to Claude Code │
│ via Windows MCP (click, type, enter) │
└─────────────────┬───────────────────────────┘
│
v
┌─────────────────────────────────────────────┐
│ 7. Logs decision and continues monitoring │
│ Repeats until project complete │
└─────────────────────────────────────────────┘
- Windows 10/11 (required for Windows MCP)
- PowerShell 7.0+ (Download)
- Windows MCP Server configured and running
- Claude API Key (Get one)
- Git with SSH configured
- BurntToast Module:
Install-Module BurntToast -Scope CurrentUser
-
Clone this repository:
git clone https://github.com/yourusername/claude-code-watchdog.git cd claude-code-watchdog
-
Run the installation script:
.\Install-Watchdog.ps1 -
Set your Claude API key:
.\Set-WatchdogAPIKey.ps1 -APIKey "your-api-key-here"
-
Register your first project:
.\Register-Project.ps1 ` -ProjectName "my-project" ` -ConfigPath "C:\repos\my-project\.claude-automation\project-config.json"
-
Start the Watchdog:
.\Start-Watchdog.ps1 -
Open Claude Code and start working on your project
The Watchdog will automatically detect your session and begin monitoring!
claude-code-watchdog/
├── src/
│ ├── Core/
│ │ ├── Start-Watchdog.ps1 # Main entry point
│ │ ├── Initialize-Watchdog.ps1 # Setup
│ │ └── Stop-Watchdog.ps1 # Shutdown
│ ├── Registry/
│ │ ├── Register-Project.ps1 # Project registration
│ │ ├── Get-RegisteredProjects.ps1 # Load projects
│ │ └── Update-ProjectState.ps1 # State management
│ ├── Detection/
│ │ ├── Get-ClaudeCodeState.ps1 # State detection
│ │ └── Find-ClaudeCodeSession.ps1 # Session location
│ ├── Decision/
│ │ ├── Invoke-ClaudeDecision.ps1 # API-based decisions
│ │ └── Invoke-SimpleDecision.ps1 # Rule-based decisions
│ ├── Action/
│ │ ├── Send-ClaudeCodeCommand.ps1 # Execute commands
│ │ └── Invoke-PhaseTransition.ps1 # Phase management
│ ├── Logging/
│ │ ├── Write-WatchdogLog.ps1 # Logging
│ │ └── Send-Notification.ps1 # Notifications
│ └── Utils/
│ └── Invoke-WindowsMCP.ps1 # MCP wrapper
├── config/
│ └── watchdog-config.json # Global settings
├── docs/
│ ├── REQUIREMENTS.md # Detailed requirements
│ ├── ARCHITECTURE.md # Technical architecture
│ ├── IMPLEMENTATION-GUIDE.md # Development guide
│ └── TROUBLESHOOTING.md # Common issues
├── tests/
│ ├── Unit/ # Unit tests
│ └── Integration/ # Integration tests
├── examples/
│ └── example-project-config.json # Sample config
├── README.md # This file
├── Install-Watchdog.ps1 # Installation script
├── Register-Project.ps1 # Project registration
├── Set-WatchdogAPIKey.ps1 # API key setup
└── Start-Watchdog.ps1 # Start monitoring
Create a .claude-automation/project-config.json in your project repository:
{
"projectName": "my-awesome-project",
"repoPath": "C:/repos/my-awesome-project",
"repoUrl": "github.com/user/my-awesome-project",
"branch": "main",
"automation": {
"autoCommit": true,
"autoProgress": true,
"maxRunDuration": "8h",
"stallThreshold": "10m"
},
"humanInLoop": {
"requiresApprovalFor": [
"database-schema-changes",
"API-breaking-changes"
],
"requiresHumanAfter": [
"compilation-errors",
"test-failures"
]
},
"skills": [
"/mnt/skills/user/type-error-resolution",
"/mnt/skills/user/compilation-error-resolution",
"/mnt/skills/user/lint-error-resolution"
],
"phases": [
{
"name": "requirements-analysis",
"autoProgress": false,
"estimatedDuration": "1h"
},
{
"name": "implementation",
"autoProgress": true,
"estimatedDuration": "6h"
},
{
"name": "testing",
"autoProgress": false,
"estimatedDuration": "2h"
}
],
"commitStrategy": {
"frequency": "phase-completion",
"branchNaming": "claude/{phase-name}-{timestamp}",
"prCreation": "phase-completion"
},
"notifications": {
"onError": true,
"onPhaseComplete": true,
"onHumanNeeded": true
}
}See example-project-config.json for a fully annotated example.
# Register and start monitoring
.\Register-Project.ps1 -ProjectName "lint-cleanup" -ConfigPath "C:\repos\myapp\.claude-automation\project-config.json"
.\Start-Watchdog.ps1
# In another window, start Claude Code on your project
# The Watchdog automatically detects and manages it# Register multiple projects
.\Register-Project.ps1 -ProjectName "frontend-refactor" -ConfigPath "C:\repos\frontend\.claude-automation\project-config.json"
.\Register-Project.ps1 -ProjectName "api-migration" -ConfigPath "C:\repos\api\.claude-automation\project-config.json"
.\Register-Project.ps1 -ProjectName "docs-update" -ConfigPath "C:\repos\docs\.claude-automation\project-config.json"
# Start Watchdog - monitors all three simultaneously
.\Start-Watchdog.ps1# List all registered projects
.\Get-RegisteredProjects.ps1
# Get detailed status for a project
.\Get-ProjectStatus.ps1 -ProjectName "frontend-refactor"
# View decision log
Get-Content "C:\repos\frontend\.claude-automation\decision-log.md"# Pause a project (stop monitoring)
.\Set-ProjectStatus.ps1 -ProjectName "api-migration" -Status "Paused"
# Resume monitoring
.\Set-ProjectStatus.ps1 -ProjectName "api-migration" -Status "Active"# Check API costs
.\Get-APICosts.ps1
# Set cost limits
.\Set-CostLimits.ps1 -DailyLimit 10.00 -WeeklyLimit 50.00
# Export cost report
.\Export-CostReport.ps1 -OutputPath "costs-november.csv"┌─────────────────────────────────────┐
│ Watchdog Process (PowerShell) │
│ ┌────────────────────────────────┐ │
│ │ Project Registry │ │
│ │ - Multi-project tracking │ │
│ └────────────────────────────────┘ │
│ ┌────────────────────────────────┐ │
│ │ State Detection │ │
│ │ - Windows MCP integration │ │
│ └────────────────────────────────┘ │
│ ┌────────────────────────────────┐ │
│ │ Decision Engine │ │
│ │ - Claude API / Rule-based │ │
│ └────────────────────────────────┘ │
│ ┌────────────────────────────────┐ │
│ │ Action Executor │ │
│ │ - Commands, Git, PRs │ │
│ └────────────────────────────────┘ │
└──────────────┬──────────────────────┘
│
├──> Windows MCP ──> Claude Code (Chrome)
├──> Claude API ──> Decision-making
└──> Git/GitHub ──> Version control
- State Detection: Uses Windows MCP to capture and parse Claude Code UI
- Decision Engine: Claude API or rules determine next action
- Action Executor: Sends commands, performs Git operations
- Project Registry: Manages multiple projects and their state
- Logging System: Comprehensive audit trail and notifications
See ARCHITECTURE.md for detailed technical documentation.
# Clone the repository
git clone https://github.com/yourusername/claude-code-watchdog.git
cd claude-code-watchdog
# Install development dependencies
.\Install-DevDependencies.ps1
# Run tests
.\Run-Tests.ps1The project includes a comprehensive test suite with 185+ test cases:
# Run all tests with the test runner
cd tests
.\Run-AllTests.ps1
# Run only unit tests
.\Run-AllTests.ps1 -TestType Unit
# Run with code coverage report
.\Run-AllTests.ps1 -GenerateCoverageReport
# Run using Pester directly
Invoke-Pester -Path .\tests\Unit\
Invoke-Pester -Path .\tests\Integration\Test Coverage:
- Unit Tests: 155+ tests across Core, Detection, and Decision modules
- Integration Tests: 30+ end-to-end scenarios
- Code Coverage: 70-80% of critical modules
- Frameworks: Pester 5.0+, NUnit XML output, JaCoCo coverage
See tests/README.md for detailed testing documentation.
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
Areas we'd love help with:
- Additional Claude Skills integration
- Support for other browsers (Edge, Firefox)
- Azure DevOps integration
- Web dashboard for monitoring
- Mobile notifications
- Cost optimization strategies
- ✅ Project structure and module system
- ✅ Windows MCP integration wrapper
- ✅ Installation scripts and setup
- ✅ Configuration management
- ✅ 6-state detection system (InProgress, HasTodos, Error, PhaseComplete, Idle, WaitingForInput)
- ✅ TODO parsing with 95%+ accuracy
- ✅ Error detection and classification
- ✅ Multi-project session detection
- ✅ Rule-based decision system
- ✅ Claude API integration for intelligent decisions
- ✅ Cost tracking and budget management
- ✅ Decision history and context awareness
- ✅ Automatic fallback mechanisms
- ✅ Command execution with retry logic
- ✅ Skill-based error resolution
- ✅ Git operations (branch, commit, push)
- ✅ Phase transition management
- ✅ Automated GitHub PR creation
- ✅ Multi-project registration and tracking
- ✅ Concurrent project processing
- ✅ Session recovery after crashes
- ✅ State persistence and restoration
- ✅ Resource monitoring
- ✅ Comprehensive decision logs with API metadata
- ✅ Multi-level logging (Info, Warning, Error, Debug)
- ✅ Progress reports and analytics
- ✅ Daily summaries across projects
- ✅ Cost analysis and tracking
- ✅ CSV export functionality
- ✅ 185+ unit and integration tests
- ✅ Comprehensive error handling guidelines
- ✅ Automated test runner with coverage reporting
- ✅ 70-80% code coverage of critical modules
- ✅ CI/CD ready testing framework
- 🔄 User documentation
- 🔄 Developer documentation
- 🔄 Troubleshooting guide
- 🔄 Performance optimization
- 🔄 Release preparation
- 📋 v1.0 production release
- Web dashboard for monitoring
- Slack/Teams integration
- Azure DevOps support
- Cross-platform support (macOS/Linux)
- Cloud deployment options
- Team collaboration features
Q: Does this work with any Claude Code session?
A: Yes, as long as it's running in Chrome and accessible via Windows MCP.
Q: What if Claude Code crashes or I close the browser?
A: The Watchdog detects the session is gone and pauses monitoring. You'll get a notification. When you restart Claude Code, the Watchdog resumes automatically.
Q: How much does the API cost?
A: Depends on usage, but typically $1-5 per day for a single active project. The Watchdog tracks costs and can fall back to rule-based decisions to stay within budget.
Q: Can I use this without the Claude API?
A: Yes! Phase 1 uses rule-based decisions only. The API is optional (added in Phase 2) for smarter decisions.
Q: Is my code safe?
A: The Watchdog only reads Claude Code's UI and sends text commands. It doesn't access your code directly. All Git operations use your configured credentials.
Q: Can I run this on a remote server?
A: Currently, it requires Windows with desktop access for Windows MCP. Cloud deployment is planned for Phase 4.
Q: What about macOS/Linux?
A: Windows MCP is Windows-only. We're exploring cross-platform alternatives for future versions.
Check:
- Windows MCP server is running
- Chrome window title contains "Claude Code"
- Project is registered:
.\Get-RegisteredProjects.ps1
Solution: Restart Windows MCP, verify Chrome window title format
Check:
- Reply field coordinates are correct
- No popup dialogs blocking UI
- Claude Code session is responsive
Solution: Capture screenshot with Get-ClaudeCodeState -IncludeScreenshot, adjust coordinates if needed
Check:
- Daily limit set:
.\Get-CostLimits.ps1 - Decision frequency: reduce polling interval
Solution: Increase polling interval to 5 minutes, enable rule-based fallback
Check:
- State files exist in
.claude-automation/ - No file permission issues
Solution: Manually restart Claude Code, Watchdog will reconnect automatically
For more issues, see TROUBLESHOOTING.md
MIT License - see LICENSE file for details
- Anthropic for Claude and Claude Code
- Windows MCP for making UI automation possible
- The PowerShell community for excellent modules and tools
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Email: your-email@example.com
✅ Production Beta - All core features complete (WS01-WS07)
Current Version: 1.0.0-beta
Last Updated: November 22, 2025
Built with ❤️ for engineering teams who want AI to work for them, not the other way around.
- Quick Start Guide ⭐ Start here!
- Installation
- First Project