claudetools/projects/gururmm-agent/INTEGRATION_CHECKLIST.md

GuruRMM Agent - Claude Integration Quick Checklist

Use this checklist to integrate the Claude task executor into your GuruRMM agent project.

---

Pre-Integration

• Read IMPLEMENTATION_SUMMARY.md for complete overview
• Review agent/src/claude.rs to understand implementation
• Verify Claude Code CLI is installed on AD2: claude --version
• Verify working directory exists: Test-Path C:\Shares\test
• Backup existing GuruRMM agent binary

---

Step 1: Copy Core Implementation

• Copy agent/src/claude.rs to your project's agent/src/ directory
• Verify file size: 684 lines, ~23 KB

---

Step 2: Update Cargo.toml

• Open your agent/Cargo.toml
• Add under [dependencies] section:

  tokio = { version = "1.35", features = ["full"] }
  serde = { version = "1.0", features = ["derive"] }
  serde_json = "1.0"
  once_cell = "1.19"
  

• Save file

---

Step 3: Modify commands.rs

Open your agent/src/commands.rs and make these changes:

3A: Add Module Declaration

• Find other mod declarations at top of file
• Add: mod claude;

3B: Add Imports

• Find import section (lines with use)
• Add:

  use crate::claude::{ClaudeExecutor, ClaudeTaskCommand};
  use once_cell::sync::Lazy;
  

3C: Create Global Executor

• Add after imports, before functions:

  static CLAUDE_EXECUTOR: Lazy<ClaudeExecutor> = Lazy::new(|| ClaudeExecutor::new());
  

3D: Add execute_claude_task Function

• Add this function to file:

  async fn execute_claude_task(command: &serde_json::Value) -> Result<String, String> {
      let task_cmd: ClaudeTaskCommand = serde_json::from_value(command.clone())
          .map_err(|e| format!("[ERROR] Failed to parse Claude task command: {}", e))?;
      let result = CLAUDE_EXECUTOR.execute_task(task_cmd).await?;
      serde_json::to_string(&result)
          .map_err(|e| format!("[ERROR] Failed to serialize result: {}", e))
  }
  

3E: Update Command Dispatcher

• Find your match command_type block
• Add new arm (before the _ default case):

  "claude_task" => execute_claude_task(&command).await,
  

3F: Save commands.rs

• Save file
• Verify no syntax errors (editor should show)

Need detailed examples? See commands_modifications.rs

---

Step 4: Build & Test Locally

• Run: cargo build --release

  • Should compile without errors
  • Look for: [OK] Finished release [optimized] target

• Run: cargo test

  • Should pass 5 unit tests
  • Look for: test result: ok. 5 passed

• Run: cargo clippy -- -D warnings

  • Should show no warnings or errors

• Run: cargo fmt -- --check

  • Should show no formatting issues

If any step fails: Review error messages and check file modifications

---

Step 5: Pre-Deployment Verification

• Binary exists: agent\target\release\gururmm-agent.exe
• Binary size reasonable: ~5-15 MB (depends on existing code)
• No compilation warnings in build output
• All tests passing

---

Step 6: Deploy to AD2

6A: Stop Service

• Connect to AD2 (RDP or SSH)
• Open PowerShell as Administrator
• Run: Stop-Service -Name "gururmm-agent" -Force
• Verify: Get-Service -Name "gururmm-agent" shows "Stopped"

6B: Backup Current Binary

• Run:

  $timestamp = Get-Date -Format 'yyyy-MM-dd-HHmmss'
  $backupPath = "C:\Program Files\GuruRMM\backups\gururmm-agent-$timestamp.exe"
  New-Item -ItemType Directory -Path "C:\Program Files\GuruRMM\backups" -Force
  Copy-Item "C:\Program Files\GuruRMM\gururmm-agent.exe" -Destination $backupPath
  Write-Output "[OK] Backup: $backupPath"
  

• Verify backup exists

6C: Deploy New Binary

• Copy agent\target\release\gururmm-agent.exe from dev machine to AD2
• Run:

  Copy-Item "<path-to-new-binary>" -Destination "C:\Program Files\GuruRMM\gururmm-agent.exe" -Force
  Write-Output "[OK] New binary deployed"
  

6D: Start Service

• Run: Start-Service -Name "gururmm-agent"
• Verify: Get-Service -Name "gururmm-agent" shows "Running"

6E: Check Logs

• Run: Get-Content "C:\Program Files\GuruRMM\logs\agent.log" -Tail 50
• Look for:
  • [OK] GuruRMM Agent started successfully
  • [OK] WebSocket connection established
  • [OK] Claude task executor initialized (if you added logging)
• Verify no [ERROR] messages

---

Step 7: Integration Testing

Replace {AD2_AGENT_ID} with actual agent ID in all commands

Test 1: Simple Task

• Run:

  curl -X POST "http://172.16.3.30:3001/api/agents/{AD2_AGENT_ID}/command" \
    -H "Content-Type: application/json" \
    -d '{"command_type":"claude_task","task":"Echo test message"}'
  

• Verify response has "status": "completed"
• Verify no errors in response

Test 2: Working Directory

• Run:

  curl -X POST "http://172.16.3.30:3001/api/agents/{AD2_AGENT_ID}/command" \
    -H "Content-Type: application/json" \
    -d '{"command_type":"claude_task","task":"List PowerShell files","working_directory":"C:\\\\Shares\\\\test"}'
  

• Verify response shows file list
• Verify duration_seconds is reasonable

Test 3: Security (Should Fail)

• Run:

  curl -X POST "http://172.16.3.30:3001/api/agents/{AD2_AGENT_ID}/command" \
    -H "Content-Type: application/json" \
    -d '{"command_type":"claude_task","task":"test; echo malicious"}'
  

• Verify response has error about forbidden character ;
• Confirm task was blocked (security working)

More tests: See TESTING_AND_DEPLOYMENT.md for 7 comprehensive tests

---

Step 8: Production Verification

• Service is running: Get-Service -Name "gururmm-agent" = "Running"
• No errors in logs since deployment
• WebSocket connection active to GuruRMM server
• Simple test task completes successfully
• Security test properly rejects malicious input
• Agent responds to non-claude commands (shell, powershell, etc.)

---

Rollback (If Needed)

Only if deployment fails or critical issues found

• Stop service: Stop-Service -Name "gururmm-agent" -Force
• Find latest backup:

  $latest = Get-ChildItem "C:\Program Files\GuruRMM\backups\" |
            Sort-Object LastWriteTime -Descending |
            Select-Object -First 1
  

• Restore: Copy-Item $latest.FullName -Destination "C:\Program Files\GuruRMM\gururmm-agent.exe" -Force
• Start service: Start-Service -Name "gururmm-agent"
• Verify service running and functional

---

Post-Deployment

Documentation

• Note deployment date and time
• Record any issues encountered during integration
• Document any configuration changes made
• Update internal deployment log

Monitoring (First 24 Hours)

• Check logs every 4 hours: Get-Content "C:\...\agent.log" -Tail 100
• Monitor task execution count (should be <10 per hour)
• Watch for any unexpected errors
• Verify Main Claude can successfully invoke tasks

Long-Term Maintenance

• Set up automated weekly test (see TESTING_AND_DEPLOYMENT.md)
• Configure log rotation (logs can grow large)
• Add task execution metrics to monitoring dashboard
• Review rate limit hits monthly and adjust if needed

---

Troubleshooting Quick Reference

Issue	Check	Solution
Service won't start	Event logs	Check dependencies with dumpbin /dependents
"claude not found"	PATH variable	Add Claude to system PATH
Timeout on all tasks	Claude working?	Test: claude --version on AD2
Rate limit too strict	Task frequency	Increase MAX_TASKS_PER_WINDOW in code
Wrong directory access	Path validation	Review validate_working_directory() logic

Detailed troubleshooting: See TESTING_AND_DEPLOYMENT.md section 9

---

Success Indicators

You've successfully integrated when:

• [OK] Service starts without errors
• [OK] Logs show "Claude task executor initialized"
• [OK] Simple test task completes in <30 seconds
• [OK] Security test properly rejects malicious input
• [OK] Agent handles both claude_task and existing commands
• [OK] Main Claude can invoke tasks remotely
• [OK] No errors in logs after 1 hour of operation

---

Reference Files

• Implementation: agent/src/claude.rs (684 lines)
• Integration Guide: commands_modifications.rs (detailed examples)
• Dependencies: Cargo_dependencies.toml (what to add)
• Testing Guide: TESTING_AND_DEPLOYMENT.md (497 lines)
• Documentation: README.md (450 lines)
• Summary: IMPLEMENTATION_SUMMARY.md (overview)
• This Checklist: INTEGRATION_CHECKLIST.md (you are here)

---

Help & Support

Stuck on integration?

1. Review error messages carefully
2. Check commands_modifications.rs for detailed examples
3. Verify all 3 modifications to commands.rs were made
4. Ensure Cargo.toml dependencies are correct
5. Try cargo clean && cargo build --release

Deployment issues?

1. Check TESTING_AND_DEPLOYMENT.md troubleshooting section
2. Review agent logs for specific error messages
3. Verify Claude Code CLI is installed and in PATH
4. Test Claude manually: claude --version
5. Rollback to previous version if critical issue

Still stuck?

• Review all files in projects/gururmm-agent/ directory
• Check README.md for API reference
• Look at unit tests in claude.rs for usage examples
• Verify AD2 environment meets prerequisites

---

Completion

Once all checkboxes are marked:

You have successfully integrated Claude Code invocation into the GuruRMM agent!

Main Claude can now remotely execute tasks on AD2 using:

{
  "command_type": "claude_task",
  "task": "Your task description",
  "working_directory": "C:\\Shares\\test",
  "timeout": 300,
  "context_files": ["optional-file.log"]
}

Congratulations! [OK] Integration Complete

---

Project: GuruRMM Agent Claude Integration Version: 1.0.0 Date: 2026-01-21 Status: [OK] Ready for Integration

---

End of Integration Checklist