sysdoctor

A command line AI assistant that figures out why your computer is being weird

How it works

sysdoctor provides LLMs real-time system data from your machine:

• Runs a background daemon that continuously collects system metrics (CPU, memory, disk, processes)
• Maintains a history of system snapshots in ~/.sysdoctor/snapshots.json to track performance trends
• Provides a chat interface that automatically includes current system state as context for every user question
• Daemon persists across chat sessions, so you always have fresh data ready

The goal is to get specific action items based on your machine's state rather than generic advice.

Example

Setup

1. Install dependencies: pip install -r requirements.txt

2. Create a .env file in the sysdoctor directory with either:

   OPENAI_API_KEY=your_api_key_here
   

   or

   ANTHROPIC_API_KEY=your_api_key_here
   

   sysdoctor will automatically use whichever API key is available. If both are present, OpenAI will be used.

Usage

Basic Usage

# Start chat interface (auto-starts daemon if needed)
sysdoctor

# Check if daemon is running
sysdoctor --daemon-status

# Manually start daemon in background
sysdoctor --daemon

# Stop daemon
sysdoctor --stop-daemon

Run as a CLI command (recommended)

sysdoctor

One-time setup for CLI usage

1. Make the script executable:

   chmod +x sysdoctor.py

2. Create a symlink to /usr/local/bin:

   ln -sf "$PWD/sysdoctor.py" /usr/local/bin/sysdoctor

3. Now you can run sysdoctor from anywhere in your terminal.

Run as a Python script

python sysdoctor.py

Arguments:

• --daemon: Start daemon in background and exit
• --stop-daemon: Stop running daemon and exit
• --daemon-status: Check if daemon is running and exit## Data Storage

sysdoctor stores data in ~/.sysdoctor/:

• snapshots.json: System snapshots collected by daemon
• daemon.pid: Process ID of running daemon

sysdoctor logs to a log file called sysdoctor.log which gets created in the directory you run the sysdoctor command in.

Chat Interface

Type your questions about system performance and sysdoctor will analyze current and recent system state to provide specific recommendations.

Type exit or quit to exit. You'll be asked whether to keep the daemon running for future sessions.