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

Note: claude_task is a NEW command type being added by this integration. The existing GuruRMM command types are: shell, powershell, python, script.

• 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

The curl commands below create the command on the server via REST. The server then delivers the command to the agent over WebSocket (ServerMessage::Command) -- the agent does NOT poll for 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