---

name: MeshForge description: > MeshForge NOC (Network Operations Center) assistant for LoRa mesh network development. Handles Meshtastic and RNS (Reticulum) network operations, configuration, debugging, and development.

Use when working with: (1) Meshtasticd configuration and service management, (2) RNS/Reticulum network setup and bridging, (3) LoRa radio configuration (presets, frequencies, regions), (4) MeshForge GTK/TUI/Web UI development, (5) Gateway bridge between Meshtastic and RNS, (6) RF calculations and link budgets, (7) Node discovery and monitoring.

Triggers: meshtastic, meshtasticd, rnsd, reticulum, lora, meshforge, gateway, rnode, nomadnet

MeshForge Development Assistant

Project Context

MeshForge is a Network Operations Center (NOC) bridging Meshtastic and Reticulum mesh networks. First open-source tool to unify these incompatible mesh ecosystems.

Version: 0.4.7-beta Callsign: WH6GXZ (Nursedude)

Development Principles

Copy1. Make it work       ← First priority
2. Make it reliable   ← Security, testing
3. Make it maintainable ← Clean code, docs
4. Make it fast       ← Only when proven necessary

Security Rules (MUST FOLLOW)

MF001: Path.home() - NEVER use directly

Copy# WRONG
config = Path.home() / ".config" / "meshforge"

# CORRECT
from utils.paths import get_real_user_home
config = get_real_user_home() / ".config" / "meshforge"

MF002: shell=True - NEVER use

Copy# WRONG
subprocess.run(f"cmd {arg}", shell=True)

# CORRECT
subprocess.run(["cmd", arg], timeout=30)

MF003: Bare except - NEVER use

Copy# WRONG
except:
    pass

# CORRECT
except Exception as e:
    logger.debug("Error: %s", e)

MF004: Always include timeout

Copysubprocess.run(["cmd"], timeout=30)  # Always specify timeout

Key Ports

Service Status Pattern

For systemd services, trust systemctl only:

Copyfrom utils.service_check import check_service

status = check_service('meshtasticd')
if status.available:
    # Service running
else:
    print(status.fix_hint)  # "sudo systemctl start meshtasticd"

GTK Threading Rule

UI updates ONLY from main thread:

Copydef background_work():
    result = slow_operation()
    GLib.idle_add(update_ui, result)  # Schedule on main thread

threading.Thread(target=background_work, daemon=True).start()

Message Listener Pattern (RX Messages)

Copyfrom utils.message_listener import MessageListener

listener = MessageListener()
listener.add_callback(self._on_message)
listener.start()

def _on_message(self, msg_data):
    GLib.idle_add(self._update_ui, msg_data)

Common Commands

Copy# Launch interfaces
sudo python3 src/launcher.py      # Auto-detect UI
python3 src/standalone.py         # Zero-dependency mode

# Verify changes
python3 -m pytest tests/ -v       # Run tests
python3 scripts/lint.py           # Security lint

# Service management
sudo systemctl status meshtasticd
sudo systemctl start meshtasticd
systemctl status rnsd             # User service, no sudo

Architecture Quick Reference

Copysrc/
├── gateway/           # RNS-Meshtastic bridge
│   ├── rns_bridge.py  # Main gateway
│   └── message_queue.py # SQLite queue
├── utils/
│   ├── paths.py       # get_real_user_home()
│   ├── service_check.py # check_service()
│   └── message_listener.py # RX message callbacks
├── gtk_ui/
│   ├── panel_base.py  # Lifecycle management
│   └── panels/        # UI panels
└── core/
    └── orchestrator.py # Service management

Persistent Issues Reference

See .claude/foundations/persistent_issues.md for detailed issue tracking.

Critical resolved issues:

• #1 Path.home() → Use get_real_user_home()
• #17 Connection contention → Shared connection manager
• #20 Service detection → Phases 1&2 complete, Phase 3 uses MessageListener

For Detailed Reference

• Architecture: .claude/foundations/domain_architecture.md
• Timeline: .claude/memory_timeline.md
• Research: .claude/research/ directory
• Knowledge Base: src/utils/knowledge_base.py