azcomputerguru/claudetools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
63e46eacdf34af3f2ff5c6b1c8762ce848ebd257
claudetools/session-logs/2026-05-30-guruconnect-specs.md
Mike Swanson e8b8411bdb sync: auto-sync from Mikes-MacBook-Air.local at 2026-05-30 19:18:44 
Author: Mike Swanson
Machine: Mikes-MacBook-Air.local
Timestamp: 2026-05-30 19:18:44
2026-05-30 19:22:11 -07:00

11 KiB
Raw Blame History

Session Log — 2026-05-30 GuruConnect Feature Specifications

User

  • User: Mike Swanson (mike)
  • Machine: Mikes-MacBook-Air.local
  • Role: admin

Session Summary

The session opened with building HTML show notes for the 2026-05-30 radio show episode ("Promised vs Got and Inventions"). Created a professionally formatted HTML version from the existing markdown show prep, added color-coded sections, phone hook callouts, and responsive styling using the March 28 show notes as a template. The HTML file was committed and opened in browser for review.

The bulk of the session focused on processing three GuruConnect feature requests and producing comprehensive technical specifications. Mike requested "Mac/Linux/Other agents" support, triggering the /gc-feature-request skill workflow. Created SPEC-010 for cross-platform agent support (macOS and Linux), specifying platform abstraction traits for capture/input/encoding with macOS using ScreenCaptureKit/VideoToolbox and Linux using X11 XShm/VA-API. Priority set to P2 (elevated from existing roadmap P3) due to market criticality—all major competitors support multi-platform. Estimated effort: X-Large (12-16 weeks).

Mike then requested mobile agent support (iOS/Android as remote control targets, not mobile viewer apps). Created SPEC-011 specifying native Swift/SwiftUI iOS app with ReplayKit screen sharing (view-only, no input injection due to sandboxing) and Kotlin/Jetpack Compose Android app with MediaProjection capture plus Accessibility Service input injection. Both use same protobuf-over-WSS protocol with support-code authentication and push notifications (APNs/FCM). Documented platform constraints: foreground-only operation, user consent required per session, iOS fundamentally view-only. Priority P3, effort X-Large (16-20 weeks, requires mobile development expertise).

Mike's third request was for "headless Linux mode - provides direct tty access." Initial interpretation was PTY shell access (like SSH). After presenting SPEC-012 draft, Mike clarified he wanted "remote console" access (as if sitting at the physical machine). Updated SPEC-012 to include dual modes: Serial Console Mode (direct /dev/ttyS0 access for GRUB bootloader, kernel boot messages, kernel panics—like KVM-over-IP Serial-over-LAN) and PTY Shell Mode (interactive bash/zsh for normal server management). Dashboard shows mode selector ("Console" vs "Shell" buttons) for headless agents. Serial console requires root privileges and one-time GRUB configuration. Priority P2, effort Medium (5-7 weeks).

Key Decisions

  • SPEC-010 priority elevation: Promoted from existing roadmap P3 to P2 because multi-platform support is market-critical (ScreenConnect, Splashtop, AnyDesk all support macOS/Linux; GuruConnect's Windows-only limitation blocks adoption).
  • SPEC-011 mobile target interpretation: User requested mobile "agents" (devices as remote control targets), not mobile viewer apps. This is technically challenging due to sandboxing; spec documents limitations prominently (iOS view-only, foreground-only sessions, consent-first model).
  • SPEC-011 vs GuruRMM SPEC-017 distinction: GuruConnect SPEC-011 is remote control of mobile devices; GuruRMM SPEC-017 is MDM/inventory management. Documented as complementary, not overlapping.
  • SPEC-012 dual-mode architecture: User clarified "remote console" meant boot-level access (GRUB, kernel messages), not just shell. Added Serial Console Mode alongside PTY Shell Mode. Serial console provides true KVM-over-IP equivalent (text mode).
  • SPEC-012 security model: Serial console mode requires root (boot-level control risk); recommend separate RBAC permission (console_access vs shell_access) and MFA for console mode (Phase 2).
  • Platform abstraction approach (SPEC-010): Refactor existing Windows code behind traits (PlatformCapture, PlatformInput, PlatformEncoder, PlatformTray) rather than duplicating logic. macOS and Linux implementations go in platform-specific modules.
  • Mobile app architecture (SPEC-011): iOS uses ReplayKit broadcast extension (App Group for shared data), Android uses MediaProjection foreground service. Input injection via AccessibilityService on Android only (iOS cannot inject input without jailbreak).

Configuration Changes

GuruConnect repository (azcomputerguru/guru-connect):

  • Created: docs/specs/SPEC-010-cross-platform-agents.md (359 lines)
  • Created: docs/specs/SPEC-011-mobile-agents.md (483 lines)
  • Created: docs/specs/SPEC-012-headless-linux-tty.md (628 lines initially, then 352 additions for dual-mode update)
  • Modified: docs/FEATURE_ROADMAP.md — added SPEC-010 (P2, Future Considerations), SPEC-011 (P3, Future Considerations), SPEC-012 (P2, Core Remote Control section)

ClaudeTools repository (azcomputerguru/claudetools):

  • Created: projects/radio-show/episodes/2026-05-30-promised-vs-got-and-inventions/show-notes.html (343 lines)
  • Modified: projects/msp-tools/guru-connect submodule pointer — advanced through 5 commits (SPEC-010, SPEC-011, SPEC-012 initial, SPEC-012 dual-mode update)

Commit sequence:

  1. df25e91 - feat(radio): add HTML show notes for 2026-05-30 episode
  2. 1c0b119 - feat(radio): add HTML show notes (after rebase)
  3. 5e23255 - spec: add SPEC-010 Cross-Platform Agent Support (macOS and Linux) [guru-connect]
  4. 4890649 - chore: update GuruRMM submodule to ad63b35 [separate — GuruRMM SPEC-017 + credential management roadmap item]
  5. 75c4c47 - chore: bump guru-connect submodule (SPEC-010 cross-platform agents)
  6. b186280 - spec: add SPEC-011 Mobile Agent Support (iOS and Android) [guru-connect]
  7. fcbeae3 - chore: bump guru-connect submodule (SPEC-011 mobile agents)
  8. a062a82 - spec: add SPEC-012 Headless Linux Mode (Direct TTY Access) [guru-connect]
  9. 95dfbe1 - chore: bump guru-connect submodule (SPEC-012 headless Linux TTY)
  10. 761bae5 - spec: update SPEC-012 to include both Serial Console + PTY Shell modes [guru-connect]
  11. 5bdb0c4 - chore: bump guru-connect submodule (SPEC-012 dual-mode update)

Credentials & Secrets

No new credentials created. All specs use existing GuruConnect authentication model (support codes, per-agent keys from SPEC-004).

Certificates/provisioning referenced:

  • SPEC-010 macOS: requires Apple Developer Program ($99/year, already in place) for code signing + notarization
  • SPEC-011 iOS: requires Apple Developer Program for APNs + App Store; Google Play Developer account ($25 one-time) for Play Store
  • SPEC-011 push: Firebase project (free tier) for FCM

Infrastructure & Servers

GuruConnect coordination:

  • Specs added to standalone azcomputerguru/guru-connect repo
  • Submodule tracked at projects/msp-tools/guru-connect in claudetools repo
  • No deployment changes (specs are proposed, not implemented)

Radio show notes:

  • HTML file location: projects/radio-show/episodes/2026-05-30-promised-vs-got-and-inventions/show-notes.html
  • Markdown source: show-prep.md in same directory

Commands & Outputs

Ollama classification attempt (failed):

curl -s http://localhost:11434/api/generate -d '{"model":"qwen3.6:latest",...}'
# Result: {"error":"model 'qwen3.6:latest' not found"}
# Fallback: Used qwen3:14b (available), but returned empty JSON
# Proceeded with manual classification

GuruConnect submodule operations:

cd projects/msp-tools/guru-connect
git add docs/specs/SPEC-NNN-*.md docs/FEATURE_ROADMAP.md
git commit -m "spec: add SPEC-NNN ..."
# (did not push — pushing triggers CI)

cd ../../..
git add projects/msp-tools/guru-connect
git commit -m "chore: bump guru-connect submodule (SPEC-NNN ...)"

Sync operations:

  • Multiple /sync commands throughout session to pull incoming work from GURU-5070 (27 commits related to GuruConnect v2 dashboard development)
  • Final session shows repos fully synchronized

Pending / Incomplete Tasks

SPEC-010 (Cross-Platform Agents):

  • Implementation requires 12-16 weeks
  • Dependencies: macOS/Linux test infrastructure, SPEC-004 deterministic machine identity completion
  • Blocked by: resource allocation decision

SPEC-011 (Mobile Agents):

  • Implementation requires 16-20 weeks + mobile development expertise
  • Dependencies: Apple Developer + Google Play accounts, Firebase project, mobile developer hire/contract
  • Open question: iOS view-only limitation acceptable to market? (Answer: yes, competitors same)
  • Open question: Android Accessibility Service onboarding friction — need step-by-step wizard

SPEC-012 (Headless Linux TTY):

  • Implementation requires 5-7 weeks
  • Dependencies: extends SPEC-010 Linux agent (can implement in parallel with or after SPEC-010)
  • Open questions:
    1. Serial console permissions: root vs capabilities (CAP_SYS_TTY_CONFIG)?
    2. RBAC for console vs shell access (recommend yes: separate permissions)
    3. MFA for console mode (defer to Phase 2 broader MCP feature)
    4. Default mode if serial console unavailable (recommend auto-fallback to shell with warning)

Radio show:

  • HTML notes ready for Saturday 2026-05-30 broadcast
  • If show date slips, refresh Segment 3 items (current tech news dated May 2026)

Reference Information

Specs created:

  • SPEC-010: Cross-Platform Agent Support (macOS and Linux) — guru-connect/docs/specs/SPEC-010-cross-platform-agents.md
  • SPEC-011: Mobile Agent Support (iOS and Android) — guru-connect/docs/specs/SPEC-011-mobile-agents.md
  • SPEC-012: Headless Linux Mode (Serial Console + PTY Shell) — guru-connect/docs/specs/SPEC-012-headless-linux-tty.md

Roadmap updates:

  • SPEC-010: P2, Future Considerations section
  • SPEC-011: P3, Future Considerations section
  • SPEC-012: P2, Core Remote Control section (between web viewer and multi-monitor switching)

Commit SHAs (GuruConnect):

  • 5e23255 - SPEC-010
  • b186280 - SPEC-011
  • a062a82 - SPEC-012 initial
  • 761bae5 - SPEC-012 dual-mode update

Commit SHAs (ClaudeTools):

  • df25e91 / 1c0b119 - radio show HTML
  • 75c4c47 - SPEC-010 submodule bump
  • fcbeae3 - SPEC-011 submodule bump
  • 95dfbe1 - SPEC-012 submodule bump
  • 5bdb0c4 - SPEC-012 dual-mode submodule bump

External references:

  • GuruRMM SPEC-017: Mobile Device Support (MDM/inventory) — distinct from GuruConnect SPEC-011 (remote control)
  • SPEC-002: v2 modernization architecture (per-agent keys model used by all three new specs)
  • SPEC-004: Stable machine identity (dependency for SPEC-010 and SPEC-012)
  • ADR-001: GuruConnect is standalone (no RMM coupling)

Related files:

  • Radio show prep: projects/radio-show/episodes/2026-05-30-promised-vs-got-and-inventions/show-prep.md
  • Radio show HTML: projects/radio-show/episodes/2026-05-30-promised-vs-got-and-inventions/show-notes.html
  • Previous HTML template: session-logs/2026-03-28-show-notes.html
Reference in New Issue View Git Blame Copy Permalink