Configuration

Plexus stores its configuration in a JSON file that you can edit manually or through the Settings UI in the app.

Configuration File Location

The configuration file is located at different paths depending on your operating system:

Configuration Structure

The configuration file uses JSON format with the following structure:

{
  "general": {
    "theme": "system",
    "language": "en",
    "autoStart": false,
    "minimizeToTray": true
  },
  "agents": {
    "autoDetect": true,
    "refreshInterval": 1000
  },
  "notifications": {
    "enabled": true,
    "sound": true,
    "webhookUrl": ""
  },
  "data": {
    "retentionDays": 30,
    "exportFormat": "json"
  }
}

General Settings

General application settings that control the overall behavior and appearance of Plexus.

theme

The application color theme.

{
  "general": {
    "theme": "dark"
  }
}

• light - Always use light theme
• dark - Always use dark theme
• system - Follow operating system preference

language

The application display language.

{
  "general": {
    "language": "ko"
  }
}

• en - English
• ko - Korean
• ja - Japanese

autoStart

Automatically launch Plexus when the system starts.

{
  "general": {
    "autoStart": true
  }
}

When enabled, Plexus will be added to your system's startup applications.

minimizeToTray

Minimize to system tray instead of closing when the window close button is clicked.

{
  "general": {
    "minimizeToTray": false
  }
}

When enabled, closing the window will minimize Plexus to the system tray. The app can be reopened by clicking the tray icon.

Agents Settings

Settings related to AI agent detection and monitoring.

autoDetect

Automatically detect and monitor AI coding agents when they start.

{
  "agents": {
    "autoDetect": true
  }
}

Plexus uses hooks installed in supported agents to automatically detect new sessions. Supported agents include:

• Claude Code
• Cursor
• Gemini CLI

refreshInterval

How often to refresh agent status information, in milliseconds.

{
  "agents": {
    "refreshInterval": 2000
  }
}

Lower values provide more real-time updates but may increase CPU usage. Recommended range is 1000-3000ms for most use cases.

Notifications Settings

Settings for desktop and webhook notifications.

enabled

Enable or disable all notifications.

{
  "notifications": {
    "enabled": true
  }
}

When disabled, no notifications will be shown, including desktop notifications and webhooks.

sound

Play a sound when notifications are triggered.

{
  "notifications": {
    "sound": false
  }
}

Uses the system default notification sound.

webhookUrl

URL for sending webhook notifications to external services like Discord or Slack.

{
  "notifications": {
    "webhookUrl": "https://discord.com/api/webhooks/..."
  }
}

Leave empty to disable webhook notifications. See the Integrations guide for setup instructions.

Supported webhook formats:

• Discord Webhooks
• Slack Incoming Webhooks
• Custom HTTP endpoints (POST with JSON payload)

Data Settings

Settings for data storage and export.

retentionDays

Number of days to retain session history and logs.

{
  "data": {
    "retentionDays": 90
  }
}

Sessions older than this value will be automatically deleted. Set to a higher value if you need to keep historical data for longer periods.

exportFormat

Default format for exporting session data.

{
  "data": {
    "exportFormat": "csv"
  }
}

• json - Export as JSON file (includes all metadata)
• csv - Export as CSV file (tabular format, limited metadata)

Complete Example

Here is a complete configuration example with all available options:

{
  "general": {
    "theme": "dark",
    "language": "en",
    "autoStart": true,
    "minimizeToTray": true
  },
  "agents": {
    "autoDetect": true,
    "refreshInterval": 1000
  },
  "notifications": {
    "enabled": true,
    "sound": true,
    "webhookUrl": "https://hooks.slack.com/services/..."
  },
  "data": {
    "retentionDays": 60,
    "exportFormat": "json"
  }
}

Resetting Configuration

To reset all settings to defaults:

1. Close Plexus completely
2. Delete the configuration file at the path for your OS
3. Restart Plexus

A new configuration file with default values will be created automatically.

Environment Variables

Some settings can be overridden using environment variables:

Environment variables take precedence over configuration file settings.