docs: apply vix-inspired token efficiency optimizations
- CLAUDE.md: trim ~45 lines — compress Live State Tracking, Automatic Context Loading, File Placement, Ollama sections; add single-agent guidance for coupled explore→implement tasks - CODING_GUIDELINES.md: add GrepAI-first rule with token cost rationale; add GuruRMM platform parity matrix and cross-platform coding standards - OLLAMA.md: expand tier-0 scope to include diff summarization, error categorization, agent phase handoff summaries, client email drafts, ticket classification with priority Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -65,6 +65,23 @@ powershell.exe -Command '$x = 5; Write-Host $x'
|
||||
|
||||
---
|
||||
|
||||
## Context Lookup — GrepAI First
|
||||
|
||||
Before reading any file for context, search with GrepAI or Grep. Only open a file when you need its full content for editing or line-by-line review.
|
||||
|
||||
| Goal | Tool |
|
||||
|------|------|
|
||||
| Find where a function is defined | `grepai_search` or `Grep` |
|
||||
| Understand how a feature works | `grepai_search` |
|
||||
| Find all callers of a function | `grepai_trace_callers` |
|
||||
| Full file content needed (edit, review) | `Read` |
|
||||
| Recent changes | `git log`, then `Read` specific file |
|
||||
|
||||
Reading a 500-line file to find one function costs ~3000 tokens. A targeted search costs ~100.
|
||||
Never open a large file to scan for context. Search first, read only if the search is insufficient.
|
||||
|
||||
---
|
||||
|
||||
## Security
|
||||
|
||||
- Never hardcode credentials -- use SOPS vault or environment variables
|
||||
@@ -104,4 +121,89 @@ All scripts and tools use ASCII status markers:
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2026-05-12
|
||||
## GuruRMM Agent — Platform Parity
|
||||
|
||||
All agent features that are not inherently platform-specific must ship on Windows, Linux, and macOS.
|
||||
A feature that silently no-ops on one platform is a gap, not a cross-platform implementation.
|
||||
|
||||
### The rule
|
||||
|
||||
> If you add or change a feature in the agent and the change is not blocked by OS-level APIs,
|
||||
> you must implement or stub it on all three platforms in the same PR.
|
||||
> If a real implementation is not feasible, add a `// TODO(platform): <os> — <reason>` comment
|
||||
> and open a tracking item.
|
||||
|
||||
### cfg gating — choose the right target
|
||||
|
||||
| Condition | Attribute | When to use |
|
||||
|-----------|-----------|-------------|
|
||||
| Windows only | `#[cfg(windows)]` | Windows API (Win32, WMI, SCM, OpenSSH registry) |
|
||||
| Linux + macOS | `#[cfg(unix)]` | POSIX: nix crate, signals, `/proc`, `/sys`, sockets |
|
||||
| Linux only | `#[cfg(target_os = "linux")]` | `/sys/class/thermal`, systemd, procfs, D-Bus |
|
||||
| macOS only | `#[cfg(target_os = "macos")]` | CoreFoundation, IOKit, launchd, NSStatusBar |
|
||||
| Build flag | `#[cfg(feature = "native-service")]` | Service harness (Windows only in Cargo.toml) |
|
||||
|
||||
Never use `#[cfg(not(windows))]` as a proxy for "Linux + macOS works the same" without verifying
|
||||
the macOS codepath. Linux and macOS diverge on `/sys`, D-Bus, and GUI IPC.
|
||||
|
||||
### Current parity matrix (as of 2026-05-15)
|
||||
|
||||
| Feature | Windows | Linux | macOS |
|
||||
|---------|---------|-------|-------|
|
||||
| CPU / memory / disk / network metrics | [OK] | [OK] | [OK] |
|
||||
| Temperature via sysinfo | [OK] fallback | [WARN] empty if no hwmon | [WARN] empty if no sensors |
|
||||
| Temperature via LibreHardwareMonitor | [OK] primary | N/A | N/A |
|
||||
| Temperature via /sys/class/thermal | N/A | [GAP] not implemented | N/A |
|
||||
| User detection (logged-in user) | [OK] | [OK] nix crate | [OK] nix crate |
|
||||
| User idle time | [OK] GetLastInputInfo | [GAP] returns None | [GAP] returns None |
|
||||
| IPC / tray | [OK] named pipe + WinTray | [GAP] stub no-op | [GAP] stub no-op |
|
||||
| Watchdog (process monitor) | [OK] native-service | [GAP] stub no-op | [GAP] stub no-op |
|
||||
| Script execution | [OK] cmd / PowerShell | [OK] bash / sh | [OK] bash / sh |
|
||||
| Hardware inventory | [OK] WMI | [OK] /proc + lshw | [OK] system_profiler |
|
||||
| Auto-updater | [OK] full | [OK] simpler | [OK] simpler |
|
||||
| Checks (AV, updates, firewall) | [OK] full | [WARN] partial stub | [WARN] partial stub |
|
||||
| Network discovery | [OK] | [OK] | [OK] |
|
||||
|
||||
### Known gaps — priority order
|
||||
|
||||
**1. Linux temperature collection** (`agent/src/metrics/mod.rs`)
|
||||
- sysinfo `Components` returns empty on most Linux systems (requires kernel hwmon driver exposure).
|
||||
- Correct approach: read `/sys/class/thermal/thermal_zone*/temp` directly (always available on Linux).
|
||||
- Pattern:
|
||||
```rust
|
||||
#[cfg(target_os = "linux")]
|
||||
fn collect_temps_linux() -> (Option<f32>, Option<f32>, Vec<TemperatureReading>) {
|
||||
// read /sys/class/thermal/thermal_zone*/temp
|
||||
// parse millidegrees, classify by type label in /sys/class/thermal/thermal_zone*/type
|
||||
}
|
||||
```
|
||||
|
||||
**2. Linux / macOS user idle time** (`agent/src/metrics/mod.rs` — `get_user_idle_time()`)
|
||||
- Linux: use X11 `XScreenSaverQueryInfo` (display sessions) or parse `/proc/interrupts` delta (headless).
|
||||
- macOS: use `CGEventSourceSecondsSinceLastEventType` (IOKit, always available).
|
||||
- Stub is acceptable short-term; mark with `// TODO(platform): linux/macos idle time`.
|
||||
|
||||
**3. Watchdog on Linux / macOS** (`agent/src/watchdog/`)
|
||||
- Windows: Windows Service Control Manager restarts the agent.
|
||||
- Linux: systemd `Restart=on-failure` in the unit file is the correct equivalent — no in-process watchdog needed.
|
||||
- macOS: launchd `KeepAlive` key in the plist.
|
||||
- Document the OS-native mechanism in `build-agents.sh` / installer rather than porting the Rust watchdog.
|
||||
|
||||
**4. Checks on Linux / macOS** (`agent/src/checks.rs`)
|
||||
- Windows-specific checks (Windows Update pending, Windows Defender status, Windows Firewall) have no
|
||||
direct equivalents; that is expected.
|
||||
- Cross-platform checks (disk SMART, certificate expiry, open ports) should run on all platforms.
|
||||
- Add `// TODO(platform): linux/macos — <check name>` for each unimplemented cross-platform check.
|
||||
|
||||
### Cargo.toml dependency discipline
|
||||
|
||||
- Platform-specific crates go in `[target.'cfg(...)'.dependencies]`, never in `[dependencies]`.
|
||||
- Keep `lhm` (LibreHardwareMonitor) and `windows-service` under `cfg(windows)`.
|
||||
- Keep `nix` under `cfg(unix)`.
|
||||
- When adding a new crate, verify it compiles on all three targets before merging. Use the build server
|
||||
for Windows; CI covers Linux. macOS cross-compile via `--target aarch64-apple-darwin` on Linux
|
||||
(requires `osxcross` toolchain — see build-agents.sh TODO-MACOS).
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2026-05-15
|
||||
|
||||
Reference in New Issue
Block a user