• 🧭 Design Philosophy
• 🔍 What Stuart Can and Cannot Do
• 🔐 Permission Model
• 🔑 Privilege Escalation
• 🌐 Web Fetch
• 📊 Data and Privacy
• ⚖️ Risk Assessment

Agents are powerful tools. Use this software at your own risk. Absolutely no warranty is offered.

Stuart ships with a read-only default posture. Every MCP tool queries system state — none modify it. This is a deliberate defensive choice: in read-only mode, Stuart cannot break your system, install unwanted packages, stop services, or modify your configuration.

Write operations (package installs, service restarts, config edits) are not enabled by default. If you ask Stu to make a change, he should tell you the command to run yourself rather than running it. The polkit privilege helper includes commented-out write commands that power users can enable — see PRIVILEGES.md.

• Query journals, logs, and system messages
• List and inspect systemd units, timers, and dependencies
• Enumerate storage devices, filesystems, mount points, and disk health
• Check network interfaces, routing, DNS, sockets, and connectivity
• List and inspect containers, images, volumes, and compose stacks
• Read package info, repo metadata, and available updates
• Monitor CPU, memory, disk I/O, thermals, and process state
• Enumerate USB, Thunderbolt, and serial devices
• List and inspect KVM/QEMU virtual machines, storage pools, and networks

Stuart's shipped MCP tools are read-only. The following operations are not exposed through MCP tools, though Stu may suggest manual commands for them:

• Install, remove, or update packages
• Start, stop, restart, or modify services
• Create, mount, format, or resize filesystems
• Modify network configuration, firewall rules, or DNS settings
• Create, start, stop, or delete containers
• Edit configuration files or write to disk
• Execute arbitrary commands as root

Note: Stu can still perform write operations if you approve Bash commands or file edits when prompted. The read-only posture is a default, not a hard limitation.

Occasionally Stuart falls back to shell commands via Bash when MCP tools don't cover a specific query. Every Bash command requires your explicit approval before execution. You see the exact command and can reject it. This is enforced by Claude Code, not by Stuart — it cannot be bypassed by the plugin.

Stuart uses Claude Code's layered permission system:

The plugin hook is the only permission mechanism Stuart ships. It works by returning {"decision": "allow"} for matching tool patterns. You can inspect the hook at hooks/hooks.json — it's a small, readable JSON file.

No settings.json permissions are required. Earlier versions of Stuart required manual permission rules. The hook replaces all of that.

Some read-only queries need root access (SMART health, NVMe data, firewall rules, socket process info). Stuart supports optional privilege escalation via polkit:

• A helper script (stuart-privilege-helper) defines a whitelist of approved commands — nothing outside this list can run as root
• A polkit rules file (49-stuart.rules) authorizes the helper for users in the wheel group on active local sessions
• Arguments are validated by type (/dev/* for device paths, alphanumeric for interface names)
• No passwords are stored or transmitted

Without polkit configured, Stuart still works. Tools that need root return a clear error message with the exact sudo command you can run manually.

For setup and full details: PRIVILEGES.md

Stuart auto-approves web fetches via its plugin hook. This allows Stu to retrieve documentation, check URLs, and look up external references without prompting.

Risk assessment: Web fetches are read-only HTTP requests. They do not modify system state. A compromised or misbehaving model could theoretically encode data in URL query parameters — this risk is low and consistent with Claude Code's own auto-approval of WebSearch. If this concerns you, you can disable the WebFetch auto-approval by editing hooks/hooks.json and removing the WebFetch matcher.

• Stuart processes data locally via Claude Code. MCP tool output goes to the Claude API as part of the conversation context — the same as any Claude Code session.
• Stuart does not phone home, collect telemetry, or send data anywhere other than through Claude Code's normal API calls.
• MCP tool output may contain sensitive system information (hostnames, IPs, usernames, service names, log contents). This data is sent to Anthropic's API as part of the conversation. Review Anthropic's data usage policy for how conversation data is handled.
• Stuart does not write to disk during normal operation. The profiles/ directory (for cached system profiles) is the only write target, and it's .gitignored.