Skip to content

ks6573/SysControl

Repository files navigation

SysControl

An AI agent for your Mac or Windows 11 PC that answers questions about your system — and can extend itself with new tools on the fly.

92 real-time tools covering CPU, RAM, GPU, disk, network, processes, iMessage, email, clipboard, browser, weather, reminders, Docker, Time Machine, Wi-Fi, calendar, contacts, Notes, Homebrew, media control, file management, Spotlight search, spreadsheets, Word documents, PDFs, image generation, deep web research, sub-agent orchestration, code editing, git integration, and more. The agent picks the right tools automatically, runs them in parallel, and answers in plain English.

Three ways to run it — pick whichever fits your workflow:

How Best for
App (macOS) Download the .dmg One-click native macOS (SwiftUI) experience — no setup required
App (Windows) Download the .zip Native Windows 11 desktop app (Flet) — unzip and run
CLI syscontrol (one-line install) Terminal-first workflow, scripting, SSH sessions (macOS · Windows · Linux)
Claude Desktop MCP server Using SysControl tools inside Claude Desktop

All interfaces share the same agent, tools, and providers — they're interchangeable.


App (macOS)

A native SwiftUI app with streaming chat, Markdown rendering, chat history sidebar, and auto-save — no Python, no terminal, no dependencies to install. Just download, open, and configure your provider in Settings.

Download

Option A — Pre-built DMG (no Xcode required):

Download the latest SysControl.dmg from GitHub Releases, drag to Applications, then bypass Gatekeeper on first launch (the app is ad-hoc signed, not notarized):

xattr -r -d com.apple.quarantine /Applications/SysControl.app

Or right-click the app → OpenOpen the first time.

Option B — Install from source (compiles locally, bypasses Gatekeeper automatically):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/ks6573/SysControl/master/swift/install.sh)"

To update later: use Check for Updates in the app (⇧⌘U), or run syscontrol-update from Terminal.

To uninstall: re-run with --uninstall.

Option C — Build manually:

git clone https://github.com/ks6573/SysControl.git
cd SysControl/swift
./build.sh release
open .build/SysControl.app

Requires: macOS 14 (Sonoma) or later. Options B and C also require Xcode Command Line Tools (xcode-select --install).

Features

  • Streaming responses — tokens appear as they arrive with live Markdown rendering
  • Auto-save — every conversation is saved automatically with an LLM-generated title
  • Chat history sidebar — browse and delete past chats
  • Settings — switch between local (Ollama) and cloud providers in-app
  • In-app updates — check for new versions from the menu bar (⇧⌘U) or Settings; DMG users get a one-click download, source-install users update automatically
  • No setup — everything is configured through the app itself

First Launch

On first launch an onboarding sheet appears automatically:

  1. Choose Local (Ollama) — requires Ollama running locally, no API key needed
  2. Or choose Cloud — enter your API key
  3. Click Done and start chatting

To change providers later, open Settings (⌘,).

Chat history is saved as Markdown in ~/.syscontrol/chat_history/ — view, edit, or delete freely.


App (Windows)

A native Windows 11 desktop app (built with Flet) with streaming chat, Markdown rendering, expandable tool-call cards, inline charts, a session sidebar, and in-app settings. It runs the same Python agent backend as the macOS app and CLI, bundled into a standalone .exe — no separate Python install to manage.

Download

  1. Download the latest SysControl-windows-x64.zip from GitHub Releases
  2. Unzip it anywhere (e.g. %LOCALAPPDATA%\Programs\SysControl)
  3. Run SysControl.exe

First launch: the build is not code-signed, so Windows SmartScreen may warn you. Click More info → Run anyway.

Requires: Windows 11 (x64). For local models, install Ollama for Windows and pull a model (ollama pull qwen3:30b); for cloud, enter your Ollama Cloud API key during onboarding.

Build from source

git clone https://github.com/ks6573/SysControl.git
cd SysControl
uv sync --extra gui --extra build
uv run pyinstaller SysControl.spec     # -> dist\SysControl\SysControl.exe

Or run it directly without bundling: uv run syscontrol-gui.

Platform notes

The Windows app exposes the same agent and tools as macOS. System tools — CPU, RAM, GPU, disk, network, processes, battery, files, clipboard, screenshots, volume, Wi-Fi, system logs (Event Log), shell (PowerShell/cmd), web research, charts, spreadsheets/Word/PDF, sub-agents — work natively. macOS-only integrations (iMessage, Apple Mail, Calendar/Contacts, Notes, Time Machine, Homebrew) report that they're unavailable on Windows rather than failing.


CLI

A terminal agent that runs the same backend as the app. Two install paths:

Option A — One-line install (recommended):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/ks6573/SysControl/master/install-cli.sh)"

Installs uv if missing, then runs uv tool install against the GitHub repo, exposing syscontrol and syscontrol-server on your PATH in an isolated venv. No clone required.

To update later: run syscontrol --update (or /update inside the REPL); the standalone syscontrol-cli-update script is also still installed.

To uninstall: re-run with -- --uninstall.

Option B — From a clone (for development):

git clone https://github.com/ks6573/SysControl.git
cd SysControl
curl -LsSf https://astral.sh/uv/install.sh | sh   # if uv not installed
uv sync
uv run agent.py

Requirements

  • macOS or Linux
  • Python 3.11+ (uv will fetch one if your system Python is older)
  • Ollama for local mode, or an Ollama Cloud API key for cloud mode

CLI Flags

syscontrol                                          # interactive
syscontrol --provider local --model qwen3:30b      # local, skip prompt
syscontrol --provider cloud --api-key sk-...       # cloud, skip prompt (key is remembered)
syscontrol --provider cloud --no-save-key          # cloud, prompt every time
syscontrol --continue                              # resume the most recent session
syscontrol --resume                                # pick a previous session from a list
syscontrol --coding --approval normal              # coding agent, ask before edits/shell
syscontrol --coding --approval plan                # read-only planning mode
syscontrol --coding --approval auto                # auto-accept coding edits/shell

Cloned (Option B) users can substitute uv run agent.py for syscontrol in any of the commands below.

The first time you enter your Ollama Cloud API key (via --api-key or the prompt), it's saved to ~/.syscontrol/cli_credentials.json (0600) so you won't be asked again. Use --no-save-key to opt out, or /logout from the REPL to forget it.

Coding Mode

The CLI can run as a coding agent with a narrowed code tool set: file search/read/edit, git status/diff, and shell commands. Approval modes:

Mode Behavior
plan Read-only. The agent can inspect and produce an implementation plan, but edits and shell commands are blocked.
normal Reads are automatic; file writes and shell commands ask for approval in the terminal.
auto "Just do it" mode. Auto-accepts coding edits and shell commands for the session.

Press Shift+Tab to toggle between system monitor mode and coding mode. Inside coding mode, use /approval plan, /approval normal, or /approval auto to switch policies. The old standard and nuke names still work as aliases.

Slash Commands & Keyboard Shortcuts

The interactive CLI feels like Codex / Claude Code: type / to pop a completion menu, @ to inline a file from the cwd, ! to run a one-off shell command, and the bottom toolbar shows the active model, provider, approval mode, and message count at all times.

Command Description
/help Show all commands and keyboard shortcuts
/clear Clear the screen
/reset Clear conversation history (keeps system prompt)
/tools [filter] List available tools, optionally filtered by substring
/model Show the active model and provider
/mode [system|coding] [plan|normal|auto] Toggle system/coding mode or enter a coding sub-mode
/test [command] Run a detected test command, or a provided command, in coding mode
/lint [command] Run a detected lint/typecheck command, or a provided command, in coding mode
/memory <note> Append a timestamped note to SysControl_Memory.md
/show [tool_name] Dump the full output of the most recent tool call
/sessions List recently saved CLI sessions
/init Generate a CLAUDE.md for the current project
/compact [undo] Summarize the conversation; undo restores the prior history
/approval plan|normal|auto Switch coding-mode approval policy
/update [force] Check for and install the latest SysControl release
/logout Forget the saved Ollama Cloud API key
/exit Quit the session
Key Action
Enter Submit a single-line buffer; insert a newline once the buffer is multi-line
Ctrl+D Submit any non-empty buffer; exit on an empty buffer
Ctrl+C Cancel the in-flight LLM/tool stream (press again within 1s to exit cleanly)
/ History navigation
Ctrl+R Reverse history search
Tab Complete the current slash command, @file, or argument
Shift+Tab Toggle system/coding mode
Ctrl+L Clear the screen
Esc, Enter Always insert a newline (alternative to letting Enter add one in multi-line mode)

Type @<partial> to pop a file picker scoped to the current directory (uses git ls-files when available; falls back to a recursive walk). Selected paths stay literal in the buffer and are inlined at submit time as fenced code blocks (capped at 64 KB per file).

Type !<command> to run a shell command directly — output prints inline and the LLM is bypassed. Requires allow_shell=true in ~/.syscontrol/config.json.

History is persisted to ~/.syscontrol/cli_history. Conversations auto-save to ~/.syscontrol/cli_sessions/; resume the most recent with syscontrol --continue or pick from a list with syscontrol --resume.

Local Mode (Ollama)

ollama pull qwen3:30b   # recommended
ollama serve
syscontrol --provider local

Tool-calling capable models:

Model Notes
qwen3:30b Default. Best tool use and reasoning
qwen3:8b Faster, lower memory — includes thinking mode
qwen2.5:7b Lightweight alternative
llama3.1:8b Battle-tested fallback

Models without native tool-calling (e.g. gemma3) will error.

Cloud Mode (Ollama Cloud)

syscontrol --provider cloud
# Enter your key when prompted — not echoed or stored in shell history

Get a key at ollama.com/settings/keys. Default cloud model: gpt-oss:120b.

Ending a Session

Say any natural goodbye (bye, exit, quit, done, farewell, cya, goodnight, …) or press Ctrl-C. The agent will offer to save your session before exiting.

Session Memory

On exit you are prompted to save a short note about the session. Notes are appended to SysControl_Memory.md with a timestamp. On next startup, if the file exists its contents are injected into the system prompt so the agent has context from prior sessions. The file is append-only and plain text — edit or delete entries freely.

The agent can also save and recall memory mid-session via the read_memory and append_memory_note tools — no need to wait for exit.

Privacy: SysControl stores only what you explicitly save. Ollama processes queries locally by default.


Permissions & Security

Sensitive tools are disabled by default. Enable them in ~/.syscontrol/config.json:

{
  "allow_shell":           true,
  "allow_messaging":       true,
  "allow_message_history": true,
  "allow_screenshot":      true,
  "allow_file_read":       true,
  "allow_file_write":      true,
  "allow_calendar":        true,
  "allow_contacts":        true,
  "allow_accessibility":   true,
  "allow_tool_creation":   true,
  "allow_deep_research":   true,
  "allow_email":           true,
  "allow_notes":           true,
  "allow_brew":            true,
  "allow_agents":          true
}

Each disabled tool returns an error with the exact flag needed to enable it.


Claude Desktop Setup

1. Add the MCP server to your config

Platform Config path
macOS ~/Library/Application Support/Claude/claude_desktop_config.json
Windows %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "system-monitor": {
      "command": "/path/to/uv",
      "args": ["run", "/absolute/path/to/SysControl/mcp/server.py"],
      "env": {}
    }
  }
}

Use which uv to get the uv path.

2. Set the system prompt — create a Claude Desktop Project and paste the contents of mcp/prompt.json into the Project Instructions field.

3. Restart Claude Desktopsystem-monitor will appear in the MCP servers list.


Self-Extension

When you ask for something no tool covers, the agent offers to build it:

You: What song is playing in Spotify right now?

Agent: I don't have a tool for that. Want me to create one? (yes/no)

You: yes

Agent: ✓ Tool `get_spotify_track` installed. Restart and ask again.

The agent writes a Python function, validates syntax, scans for dangerous patterns (eval, exec, etc.), and appends it to mcp/server.py. Requires:

{ "allow_tool_creation": true }

Tools (92 total)

Monitoring

Tool What it does
get_cpu_usage CPU load (total + per-core), clock frequency, inline bar chart
get_ram_usage RAM and swap — used, available, percent, inline stacked chart
get_gpu_usage GPU load, VRAM, temperature per device (NVIDIA/pynvml), inline chart
get_disk_usage Per-partition space and cumulative I/O counters
get_network_usage Cumulative bytes sent/received and per-interface status
get_realtime_io Live disk read/write and network download/upload speed (MB/s)
get_top_processes Top N processes by CPU or memory
get_full_snapshot Single call: CPU + RAM + GPU + disk + network + top processes
get_system_alerts Triage scan returning prioritized critical/warning alerts

System & Hardware

Tool What it does
get_device_specs Static profile: CPU model, core count, RAM, GPU VRAM, disks, OS
get_battery_status Percent, charging state, time remaining
get_temperature_sensors CPU/motherboard sensors (Linux/Windows)
get_system_uptime Boot time, uptime, 1/5/15-min load averages
get_hardware_profile Live pressure + specs + OC capability + upgrade feasibility + bottleneck analysis

Process Management

Tool What it does
get_process_details Deep inspection of a PID: path, cmdline, user, RSS/VMS, threads, open files
search_process Find processes by name (case-insensitive partial match)
kill_process SIGTERM (default) or SIGKILL a PID. Refuses critical system processes.

Network & Connectivity

Tool What it does
get_network_connections All active TCP/UDP connections with state and owning process
network_latency_check Pings gateway, Cloudflare, Google DNS in parallel and diagnoses slowness
get_wifi_networks Nearby networks with SSID, channel, security, signal strength

Storage

Tool What it does
find_large_files Top N largest files under a path. Skips .git, node_modules, .venv
eject_disk Unmount and eject an external disk by mountpoint

Messaging & Communication

Tool What it does
send_imessage Send an iMessage or SMS via Messages.app. macOS only.
get_imessage_history Read recent messages from ~/Library/Messages/chat.db. macOS only.
read_emails Read recent emails from Mail.app (by folder). Requires allow_email. macOS only.
send_email Send an email via Mail.app. Requires allow_email. macOS only.
search_emails Search emails across all accounts and mailboxes. Requires allow_email. macOS only.

Browser & Web

Tool What it does
web_search DuckDuckGo search — title, URL, snippet. No API key.
web_fetch Fetch a URL as plain text. No browser required.
grant_browser_access Unlock browser control (called once, after user consent)
browser_open_url Open a URL in the default browser
browser_navigate Navigate the active tab via AppleScript (macOS)
browser_get_page Return the URL, title, and text of the current tab (macOS)

Clipboard & Screen

Tool What it does
get_clipboard Return current clipboard text
set_clipboard Write text to the clipboard
take_screenshot Full-screen PNG returned inline. Optionally save to file. macOS only.
generate_image Generate an inline visual image artifact from a prompt. Requires an OpenAI image API key.

App Control & System

Tool What it does
open_app Open an app by name (open -a). macOS only.
quit_app Gracefully quit (AppleScript) or force-kill an app. macOS only.
get_volume Output, input, and alert volume; mute state
set_volume Set system output volume (0–100)
get_now_playing Currently playing track in Music.app or Spotify (title, artist, album, position). macOS only.
media_control Play, pause, skip, or stop Music.app / Spotify. Auto-detects active player. macOS only.
get_frontmost_app Return the name of the focused application
toggle_do_not_disturb Enable/disable Focus / DnD
run_shortcut Run a named Shortcut via shortcuts run. macOS 12+.

File I/O & Shell

Tool What it does
read_file Read a text file (up to 16,000 chars)
write_file Write text to any path, creating directories as needed
list_directory List directory contents with name, type, size, and modification time
move_file Move or rename a file or directory
copy_file Copy a file to a new location
delete_file Delete a file or directory (Trash by default on macOS, recoverable)
create_directory Create a directory and any missing parents
search_files Search for files system-wide using macOS Spotlight (mdfind). Instant. macOS only.
read_spreadsheet Read cells from .xlsx or .csv — supports sheet selection and cell ranges
edit_spreadsheet Write cells (A1 notation) or append rows to .xlsx / .csv. Create new files.
read_document Read paragraphs from .docx, .txt, or .md with word count
edit_document Find/replace text, overwrite paragraphs, or append to .docx files
read_pdf Extract text from PDF files, page by page (up to 200 pages)
run_shell_command Execute a bash command and return stdout/stderr. Disabled by default.

Calendar, Contacts & Logs

Tool What it does
get_calendar_events Upcoming events from Calendar.app for the next N days. macOS only.
get_contact Search Contacts.app by name — phone and email. macOS only.
list_notes List notes from Notes.app with title, folder, and timestamps. Requires allow_notes.
read_note Read the full body of a note by title (partial match). Requires allow_notes.
create_note Create a new note in Notes.app. Requires allow_notes.
get_startup_items Auto-start items (macOS LaunchAgents, Windows Registry, Linux .desktop)
tail_system_logs Last N lines of the system log with optional keyword filter

Utilities

Tool What it does
set_reminder Schedule a macOS notification. Accepts "in 2 hours", "tomorrow at 9am", etc.
list_reminders All pending reminders with IDs and fire times
cancel_reminder Cancel a reminder by ID
get_weather Current weather + clothing recommendations. Auto-detects location from IP.
check_app_updates Homebrew, Mac App Store, and system software updates. macOS only.
brew_list List all installed Homebrew formulae and casks. Requires allow_brew.
brew_install Install a Homebrew formula or cask. Requires allow_brew.
brew_upgrade Upgrade one or all Homebrew packages. Requires allow_brew.
brew_uninstall Uninstall a Homebrew formula or cask. Requires allow_brew.
get_docker_status Running containers with live CPU%, memory, image, status, and ports
get_time_machine_status Last backup time, phase and progress if running, destination. macOS only.
track_package Track UPS, USPS, FedEx, or DHL shipments by tracking number

Memory

Tool What it does
read_memory Read the persistent memory file — facts and notes saved across sessions
append_memory_note Append a concise note to the memory file for future recall

Research

Tool What it does
deep_research Multi-step web research agent: plans subquestions, searches multiple sources, extracts and cross-verifies claims, returns a citation-backed answer. Takes 1-3 minutes.

Code Editing & Navigation

Tool What it does
read_file_lines Read a file with line numbers, offset, and limit — large-file friendly. Requires allow_file_read.
edit_file Targeted find-and-replace editing. Exact string match, fails if ambiguous. Requires allow_file_write.
glob_files Find files by glob pattern (e.g. **/*.py). Skips .git, node_modules, .venv.
grep_files Regex content search across files with optional context lines. Skips binary files.
git_status Show branch, staged/unstaged/untracked files, and recent commits.
git_diff Show git diff for unstaged or staged changes.

Sub-Agent Orchestration

Tool What it does
list_agents List available sub-agents with names and descriptions
run_agent Delegate a focused task to a named sub-agent (explorer, analyst, researcher, writer) running in an isolated subprocess with restricted tools. Requires allow_agents.

Self-Extension

Tool What it does
create_tool Write, validate, and install a new MCP tool into server.py. Requires allow_tool_creation.
list_user_tools List all tools installed via create_tool

Overclocking Support

Detected automatically from hardware and platform:

Platform CPU OC GPU OC
Apple Silicon (M-series) ✗ Not supported ✗ Not supported
Intel Mac ✗ Not supported (no BIOS) ✗ Not supported (macOS)
Intel K/KF/KS — Windows/Linux ✅ Intel XTU or BIOS ✅ MSI Afterburner
AMD Ryzen — Windows/Linux ✅ Ryzen Master / PBO ✅ MSI Afterburner

Project Structure

SysControl/
├── agent.py                 # CLI entry-point shim
├── install-cli.sh           # One-line CLI installer (curl one-liner)
├── agent/
│   ├── cli.py               # Interactive terminal REPL
│   ├── core.py              # Shared agent logic: MCP client, streaming loop, helpers
│   ├── bridge.py            # JSON-over-stdio bridge for the Swift app
│   ├── agents.py            # Sub-agent specs: AgentSpec, AgentRegistry, built-in agents
│   ├── runner.py            # Sub-agent runner: isolated context, filtered tools
│   └── paths.py             # Path resolution (repo root, user data dir, memory file)
├── mcp/
│   ├── server.py            # MCP tool server (104 tools + self-extension)
│   └── prompt.json          # System prompt for the agent
├── deep_research/           # Deep research agent (iterative web research with citation verification)
├── swift/
│   ├── Package.swift         # SwiftPM package definition
│   ├── build.sh              # Builds the .app bundle and DMG
│   ├── install.sh            # One-line source installer
│   └── SysControl/           # SwiftUI source (App, Models, Views, Services, Storage)
├── scripts/
│   └── make_icon.py          # Generates the .icns app icon from source PNGs
├── pyproject.toml            # Python project config, dependencies, linting
├── VERSION                   # Current release version (single source of truth)
└── tests/                    # Pytest suite for agent core + MCP helpers

Architecture

┌──────────────────────┐
│    SwiftUI App       │   Native macOS frontend
│  (swift/SysControl/) │   Onboarding, chat, settings, history
└────────┬─────────────┘
         │  JSON-over-stdio (bridge.py)
┌────────▼─────────────┐
│    Agent Core        │   Streaming agentic loop, LLM client
│  (agent/core.py)     │   Provider selection, tool dispatch
└────────┬─────────────┘
         │  JSON-RPC (stdio)
┌────────▼─────────────┐
│    MCP Server        │   104 tools, self-extension, permission checks
│  (mcp/server.py)     │   Concurrent tool execution via client pool
└──────────────────────┘

The Swift frontend communicates with the Python backend through agent/bridge.py, which speaks a simple JSON-over-stdio protocol. The bridge reuses the same MCPClientPool and streaming loop used by the CLI, so all tools and capabilities are shared across every interface.


Entry Points

After installing via the one-liner (or pip install -e . from a clone):

Script Description
syscontrol Interactive CLI agent
syscontrol --update Check for and install the latest release in place
syscontrol --version Print the installed version and exit
syscontrol-server MCP server (stdio)
syscontrol-cli-update Standalone updater script (same as syscontrol --update)

From a clone without installing, use uv run:

Command Description
uv run agent.py Interactive CLI agent
uv run -m mcp.server MCP server (stdio) — for Claude Desktop integration

License

This project is licensed under the MIT License. See LICENSE.

About

92 real-time tools covering CPU, RAM, GPU, disk, network, processes, iMessage, clipboard, browser, weather, reminders, Docker, Time Machine, Wi-Fi, calendar, contacts, shell, spreadsheets, Word documents, deep web research, and more. The agent picks the right tools automatically, runs them in parallel, and answers in plain English.

Resources

License

Security policy

Stars

Watchers

Forks

Packages

 
 
 

Contributors