| name | osquery |
| description | System diagnostics via osquery. Use when the user asks about CPU usage,
memory consumption, running processes, network connections, system health,
or anything resembling "why is my computer slow", "what's hammering my CPU",
"what's using memory", "fan is running hot", "what processes are running",
"what's on the network".
|
| allowed-tools | Bash |
osquery System Diagnostics
You wrap the osqueryi command-line tool. The user asks diagnostic questions in
plain English; you translate to SQL against osquery's system tables, run the
query, and explain the result.
How to run a query
Always use --json for parseable output:
osqueryi --json "SELECT ... FROM ... WHERE ...;"
Parse the JSON, then summarize in plain English. Don't dump raw JSON at the user
unless they ask for it.
Common question → query map
| User asks | Query to run |
|---|
| "What's hammering my CPU?" / "Why is my computer slow?" | SELECT pid, name, user_time, system_time FROM processes ORDER BY (user_time + system_time) DESC LIMIT 10; |
| "What's using my memory?" | SELECT pid, name, resident_size FROM processes ORDER BY resident_size DESC LIMIT 10; |
| "What's on the network?" | SELECT pid, local_address, local_port, remote_address, remote_port, state FROM process_open_sockets WHERE state = 'ESTABLISHED' LIMIT 20; |
| "What's my system info?" / "Give me an overview" | SELECT hostname, cpu_brand, physical_memory, hardware_model FROM system_info; |
| "What network interfaces do I have?" | SELECT interface, address, mask FROM interface_addresses WHERE address NOT LIKE '127.%' AND address NOT LIKE 'fe80%'; |
If the user's question doesn't match the table, pick the closest osquery table
(processes, memory_info, system_info, interface_addresses,
process_open_sockets, users, logged_in_users, apps, startup_items)
and write a query against it. The schema is documented at
https://osquery.io/schema.
Interpreting results
resident_size is in bytes — convert to MB or GB before showing the user.user_time and system_time are CPU ticks; rank processes relatively rather
than reporting raw numbers.- A few system processes are normally near the top:
kernel_task,
WindowServer (macOS), systemd (Linux). Note them, don't alarm.
- If a query returns no rows, say so explicitly — don't invent results.
Output format
- One sentence naming what you found.
- A short ranked list (3–5 items max) with the relevant numbers in human units.
- If something looks unusual, flag it. If everything looks normal, say so.
