Metadata-Version: 2.5
Name: logicroot
Version: 0.3.5
Summary: LOGICROOT - a hardware-aware, capability-driven, local-first Linux Command Center
Project-URL: Homepage, https://github.com/madhav-manchanda/LogicRoot
Project-URL: Documentation, https://github.com/madhav-manchanda/LogicRoot#readme
Project-URL: Issues, https://github.com/madhav-manchanda/LogicRoot/issues
Project-URL: Changelog, https://github.com/madhav-manchanda/LogicRoot/blob/main/CHANGELOG.md
Author: LOGICROOT Contributors
License: MIT License
        
        Copyright (c) 2026 Madhav Manchanda
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: diagnostics,hardware,linux,macos,system-monitor,terminal,tui,windows
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Provides-Extra: all
Requires-Dist: textual>=0.60; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: tui
Requires-Dist: textual>=0.60; extra == 'tui'
Description-Content-Type: text/markdown

<div align="center">

# ⚡ LOGICROOT

### **Your Linux Command Center.**

A powerful, terminal-first Linux system monitor, diagnostics suite, process manager, service controller, storage analyzer, and AI-powered troubleshooting assistant.

<br />

[![Linux](https://img.shields.io/badge/Linux-000000?style=for-the-badge\&logo=linux\&logoColor=white)](#)
[![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?style=for-the-badge\&logo=python\&logoColor=white)](#)
[![Rich](https://img.shields.io/badge/Rich-Terminal-000000?style=for-the-badge)](#)
[![Textual](https://img.shields.io/badge/Textual-TUI-000000?style=for-the-badge)](#)
[![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)](#)

<br />

**Monitor · Diagnose · Manage · Understand**

<br />

<img src="https://raw.githubusercontent.com/madhav-manchanda/LogicRoot/main/assets/logicroot-dashboard.gif" width="900" alt="LOGICROOT Dashboard Demo">

</div>

---

# 🧠 What is LOGICROOT?

**LOGICROOT** is a modern Linux command center built entirely for the terminal.

Instead of switching between:

```text
htop
systemctl
du
df
ip
journalctl
nvidia-smi
ps
top
```

LOGICROOT brings the most useful Linux system operations into a single, consistent interface.

```text
                         ┌──────────────────────┐
                         │        LOGICROOT           │
                         │  Linux Command Center │
                         └──────────┬───────────┘
                                    │
             ┌──────────────────────┼──────────────────────┐
             │                      │                      │
        MONITOR                  MANAGE                DIAGNOSE
             │                      │                      │
       CPU / RAM               Processes              Problems
       GPU / Disk              Services               Health
       Network                 Storage                Boot
       Temperature             Logs                   System
             │                      │                      │
             └──────────────────────┼──────────────────────┘
                                    │
                              🧠 AI Assistant
```

LOGICROOT is designed to be:

* ⚡ Fast
* 🐧 Linux-native
* 🛡️ Safe
* 🔒 Local-first
* 🧩 Modular
* 🎨 Beautiful in the terminal
* 🤖 AI-enhanced
* 🛠️ Developer-friendly

---

# ✨ Features

<table>
<tr>
<td width="50%">

### 🖥️ System Monitor

Real-time monitoring for:

* CPU
* RAM
* Swap
* Disk
* Temperature
* Battery
* Uptime
* Kernel
* Operating system

</td>

<td width="50%">

### ⚙️ Process Manager

Inspect and manage running processes.

* CPU sorting
* Memory sorting
* Process search
* Process details
* Safe termination
* Resource monitoring

</td>
</tr>

<tr>
<td>

### 🔧 Service Manager

Manage Linux services through a clean interface.

```bash
logicroot services
logicroot services start nginx
logicroot services stop nginx
logicroot services restart nginx
```

Built around `systemd` where available.

</td>

<td>

### 💾 Storage Analyzer

Understand where your disk space is going.

* Large files
* Directory sizes
* Cache analysis
* Duplicate detection
* Filesystem usage
* Cleanup recommendations

</td>
</tr>

<tr>
<td>

### 🌐 Network Monitor

Monitor your network in real time.

* Interfaces
* IP addresses
* Traffic
* Connections
* Upload/download rates
* Ping
* Network diagnostics

</td>

<td>

### 🎮 GPU Monitor

Hardware-aware GPU monitoring.

Supports:

* NVIDIA
* AMD
* Intel

Displays:

* GPU utilization
* VRAM
* Temperature
* Power
* GPU processes

</td>
</tr>

<tr>
<td>

### 🩺 Diagnostics Engine

Automatically identify potential system issues.

```text
✓ CPU
⚠ MEMORY
✓ GPU
⚠ DISK
✓ NETWORK
⚠ SERVICES
```

Then explain what may be causing the problem.

</td>

<td>

### 🤖 AI Assistant

Ask your system questions naturally.

```bash
logicroot ask "Why is my laptop slow?"
```

LOGICROOT analyzes relevant system information and provides a human-readable explanation.

</td>
</tr>
</table>

---

# 🎬 Terminal Demo

<div align="center">

<img src="https://raw.githubusercontent.com/madhav-manchanda/LogicRoot/main/assets/demo.gif" width="850" alt="LOGICROOT terminal demo">

</div>

Example:

```text
╭────────────────────────────────────────────────────────────╮
│                         LOGICROOT                                │
│                  Linux Command Center                       │
├────────────────────────────────────────────────────────────┤
│                                                            │
│  CPU       ███████░░░  67%        GPU       ███░░░░░░ 31% │
│  RAM       ██████░░░░  61%        DISK      ███████░░░ 72% │
│  TEMP                  52°C        NETWORK   ↓ 4.2 MB/s    │
│                                                            │
├────────────────────────────────────────────────────────────┤
│ SYSTEM                                                     │
│                                                            │
│ OS       Fedora Linux                                      │
│ Kernel   6.x                                               │
│ Uptime   4h 32m                                            │
│                                                            │
├────────────────────────────────────────────────────────────┤
│ QUICK ACTIONS                                              │
│                                                            │
│  [1] Processes     [2] Services      [3] Storage           │
│  [4] Network       [5] GPU            [6] Diagnostics       │
│  [7] Logs          [8] Cleanup        [9] Assistant         │
│                                                            │
│  ? Help                                             q Quit  │
╰────────────────────────────────────────────────────────────╯
```

---

# 🚀 Quick Start

## Requirements

* Linux
* Python **3.11+**
* pip / pipx
* systemd is recommended but not mandatory

Optional tools:

```text
systemctl
nvidia-smi
journalctl
ip
ping
```

LOGICROOT gracefully handles missing optional tools.

---

## Installation

### Recommended on all operating systems: pipx

LOGICROOT defines the `logicroot` console command in its package metadata.
However, Python installers put that command in the active environment's
scripts directory, and your terminal can run it by name only if that directory
is on `PATH`. This varies by OS, Python installation, and environment.

`pipx` is the recommended way to install command-line Python applications
because it isolates dependencies and can configure its command directory.

1. Install `pipx` using the official instructions for your OS:
   https://pipx.pypa.io/stable/installation/
2. Run:

   ```bash
   pipx install logicroot
   pipx ensurepath
   ```

3. Close and reopen your terminal, then verify:

   ```bash
   logicroot --version
   ```

On Windows, if `pipx` itself is not recognized, use the Python launcher to run
it (for example, `py -m pipx ensurepath`) after installing pipx. Follow the
pipx instructions for your particular Python installation.

### If `pip install logicroot` succeeds but the command is not found

This is normally a PATH/environment issue, not a failed package download.

- **Virtual environment:** activate the same environment where you installed
  LOGICROOT before running `logicroot`.
- **Windows:** the executable is normally placed in the active Python
  environment's `Scripts` directory. For a user install, this is commonly
  under your user profile's Python `Scripts` directory.
- **Linux/macOS:** the executable is normally placed in the active environment's
  `bin` directory. For a user install, this is often `~/.local/bin` or a
  Python-version-specific user bin directory.
- Find which Python received the package with
  `python -m pip show logicroot` (or `py -m pip show logicroot` on Windows).
  The Python environment used to install it may not be the one your terminal
  uses to run commands.

Python packages should not silently rewrite a user's shell configuration or
system PATH during installation. Use `pipx ensurepath` or configure the
appropriate scripts directory using your OS's normal PATH settings.

### From source

```bash
git clone https://github.com/madhav-manchanda/LogicRoot.git
cd LogicRoot
python -m venv .venv
```

Activate the environment, then install:

Linux/macOS:
```bash
source .venv/bin/activate
python -m pip install -e .
```

Windows PowerShell:
```powershell
.venv\\Scripts\\Activate.ps1
python -m pip install -e .
```

Run the CLI:

```bash
logicroot
```

## Commands

```bash
logicroot
```

System information:

```bash
logicroot status
```

Processes:

```bash
logicroot processes
```

Sort processes by CPU:

```bash
logicroot processes --sort cpu
```

Sort by memory:

```bash
logicroot processes --sort memory
```

Search processes:

```bash
logicroot processes --search chrome
```

---

## ⚙️ Services

List services:

```bash
logicroot services
```

Failed services:

```bash
logicroot services --failed
```

Restart a service:

```bash
logicroot services restart bluetooth
```

Stop a service:

```bash
logicroot services stop nginx
```

Start a service:

```bash
logicroot services start nginx
```

LOGICROOT always asks for confirmation before potentially disruptive actions.

---

# 💾 Storage

Analyze your filesystem:

```bash
logicroot storage
```

Find large files:

```bash
logicroot storage large
```

Find duplicate files:

```bash
logicroot storage duplicates
```

Analyze caches:

```bash
logicroot storage cache
```

---

# 🌐 Network

Network overview:

```bash
logicroot network
```

Interfaces:

```bash
logicroot network interfaces
```

Active connections:

```bash
logicroot network connections
```

Ping:

```bash
logicroot network ping google.com
```

---

# 🎮 GPU

Check GPU information:

```bash
logicroot gpu
```

Example:

```text
GPU
──────────────────────────────────

NVIDIA RTX 3050

Utilization       41%
VRAM              2.8 / 4 GB
Temperature       53°C
Power             37 W

Processes
──────────────────────────────────

python            1.7 GB
chrome            410 MB
```

---

# 🩺 Diagnostics

Run a complete system diagnosis:

```bash
logicroot diagnose
```

Example:

```text
LOGICROOT DIAGNOSTICS
──────────────────────────────────────

✓ CPU
  Normal

⚠ MEMORY
  RAM usage is 91%

  Top consumers:
  chrome      5.8 GB
  code        2.1 GB

⚠ DISK
  /home is 94% full

✓ GPU
  Normal

⚠ SERVICES
  1 failed service

✓ NETWORK
  Connected

──────────────────────────────────────

3 potential issues detected.
```

LOGICROOT provides suggestions rather than blindly modifying the system.

---

# 🤖 AI Assistant

LOGICROOT can optionally provide AI-powered diagnostics. AI is **optional**:
every diagnostic command works fully offline with no API key or provider.

Ask:

```bash
logicroot ask "Why is my laptop slow?"
```

Or:

```bash
logicroot ask "What is using most of my RAM?"
```

Or:

```bash
logicroot ask "Why is my boot taking so long?"
```

LOGICROOT collects relevant system metrics and provides a contextual explanation.

## Multi-provider AI diagnostics

`logicroot ai` is the provider-agnostic diagnostic system. Supported providers:

| Provider | Local? | Key variable |
| --- | --- | --- |
| Ollama (local) | yes | none required |
| OpenAI | no | `LOGICROOT_OPENAI_API_KEY` |
| Anthropic | no | `LOGICROOT_ANTHROPIC_API_KEY` |
| Google Gemini | no | `LOGICROOT_GEMINI_API_KEY` |
| OpenRouter | no | `LOGICROOT_OPENROUTER_API_KEY` |
| Groq | no | `LOGICROOT_GROQ_API_KEY` (or TUI secure storage) |
| OpenAI-compatible | depends on endpoint | `LOGICROOT_AI_API_KEY` |

```bash
logicroot ai status        # provider, model, key state, privacy mode
logicroot ai providers     # every supported provider and how it authenticates
logicroot ai config --provider openai --model gpt-4o-mini
logicroot ai test          # minimal connectivity/model test
logicroot ai diagnose      # collect, ask once, validate, gate actions
logicroot ai diagnose --json
```

`logicroot analyze` and `logicroot analyze --ollama` keep working as
backward-compatible aliases for rule-based analysis.

### API key security

Keys are never accepted as CLI arguments (shell history and `ps` would expose
them) and never printed, logged, or included in errors, JSON, or diagnostics.
Only `configured` / `not configured` is ever displayed.

Lookup order per provider: an explicitly configured environment variable first,
then the provider-scoped environment variable above, OS keyring, then LogicRoot's
private credential store. Environment variables override stale stored credentials.
Configuration files never contain keys and are written with `0600` permissions:

```bash
logicroot ai config --provider openai --set-key   # prompts with hidden input
export LOGICROOT_OPENAI_API_KEY="..."             # fallback when no keyring
```

### Privacy modes

- `local` — only local models; nothing leaves the machine.
- `cloud` — hosted providers allowed; payloads are sanitized to `[REDACTED]` first.
- `hybrid` — local by default; cloud only with `--allow-cloud` for that request.

Fallback providers are never used silently: configure one with
`--fallback-provider`/`--fallback`, then allow it per request with
`--allow-fallback`.

### Diagnostic workflow and permissions

`ai diagnose` runs Observe → Collect → Normalize → Analyze → Diagnose →
Recommend → Permission gate → Optional action → Verify. The model only returns
data: findings, recommendations, and `action_id`s. Only three allowlisted
actions can ever execute (`cleanup_cache`, `restart_allowed_service`,
`refresh_package_metadata`), each with schema-validated arguments. Mutating
actions need explicit confirmation (`[y/N]`, or typed `CONFIRM` for HIGH risk),
and every action is verified by re-measuring before/after.

Troubleshooting: `ai test` classifies failures (auth, rate limit, unknown
model, timeout, network, malformed response, downtime) with causes and fixes.
If Ollama is not running it says so and suggests `ollama serve` or another
provider.

Example:

```text
LOGICROOT ANALYSIS
────────────────────────────────────────

Your system is experiencing high memory usage.

RAM:
5.8 GB  Chrome
2.1 GB  VS Code
1.7 GB  Python

Available RAM:
1.4 GB

Possible actions:

1. Close unused browser tabs
2. Inspect the Python process
3. Check swap usage

No changes were made to your system.
```

---

## Extended system command center

These commands are part of the expanded command set. Optional utilities are
detected rather than installed automatically. Read-only checks never install,
upgrade, or remove packages.

| Command | Purpose |
| --- | --- |
| `logicroot dashboard --json` | Compact system-health overview |
| `logicroot battery health` | Battery health and capacity comparison |
| `logicroot sensors` | Linux thermal-zone and hwmon temperatures |
| `logicroot disk health [DEVICE]` | SMART data when smartctl is available |
| `logicroot boot analyze` | systemd boot timing and slow units |
| `logicroot packages updates` | Inspect locally available package updates |
| `logicroot security` | Basic firewall, listening-port, and SSH checks |
| `logicroot network diagnose` | DNS, route, and ping diagnostics |
| `logicroot containers` | Read-only Docker/Podman inventory and resource usage |
| `logicroot history record` / `history` / `history stats` | Local JSONL metrics history and aggregates |
| `logicroot watch --once` | Check CPU, memory, disk, and temperature thresholds once; omit --once to keep watching |
| `logicroot alert` | Explain default alert thresholds |
| `logicroot doctor --json` | Quick system-health checklist |
| `logicroot analyze --json` | Evidence-based local analysis; optionally `--ollama --model MODEL` for a local LLM |
| `logicroot ai status` | Configured provider, model, key state, and privacy mode |
| `logicroot ai providers` | All supported providers and their key variables |
| `logicroot ai config` | Select provider/model/privacy/fallback; `--set-key` uses the OS keyring |
| `logicroot ai test --json` | Minimal provider connectivity/model test |
| `logicroot ai diagnose --json` | Provider-assisted diagnosis with gated, verified actions |
| `logicroot explain TOPIC` | Offline advice for common symptoms |
| `logicroot env audit --path DIR` | Find likely secret-bearing files without showing values |
| `logicroot plugins` | List plugin metadata without importing plugins |
| `logicroot plugins run NAME --json` | Explicitly load and execute a selected installed plugin |
| `logicroot k8s` | Inspect Kubernetes nodes and pods through kubectl |

Examples:

```bash
logicroot dashboard
logicroot battery health
logicroot sensors --json
logicroot disk health /dev/nvme0
logicroot boot analyze
logicroot packages updates
logicroot network diagnose --host example.com
logicroot history record --count 12 --interval 5
logicroot watch --once
logicroot doctor --json
logicroot env audit --path .
```

Metric history stays on the local machine under the XDG state directory or
`~/.local/state/logicroot/metrics.jsonl`. Secret auditing intentionally omits
secret values. Security and doctor output is advisory, not a full security
certification. Package update checks never perform an upgrade. The interactive TUI includes an additional System Health view (press `h`).

### Plugin contract

LOGICROOT discovers entry points in the `logicroot.plugins` group without importing their code. To execute one, use `logicroot plugins run NAME`; the selected entry point must be a callable accepting a context dictionary (`api_version=1`, `platform`, `hostname`, `metrics`, `read_only`) and returning a JSON-serializable result. **Plugins are third-party Python code and can perform arbitrary actions**; only run plugins you trust. Listing plugins never executes them.

### Optional local AI analysis

`logicroot analyze` always works with local rules. Add `--ollama --model MODEL` only when you want to ask an already-installed local Ollama model for additional suggestions. No external AI service is contacted by this command. For the full multi-provider system, see `logicroot ai` above; the TUI includes an AI Diagnostics view (press `a`).

# 🛡️ Safety First

LOGICROOT is designed around **least privilege**.

It does not require:

```bash
sudo logicroot
```

for normal monitoring.

Destructive or disruptive actions always require confirmation.

For example:

```text
⚠ WARNING

You are about to stop:

docker.service

This may stop running containers.

Continue? [y/N]
```

LOGICROOT never silently:

* deletes files
* kills processes
* stops services
* modifies configuration
* executes AI-generated commands

---

# 🔒 Privacy

LOGICROOT is **local-first**.

Core functionality does not require:

* accounts
* cloud services
* remote servers
* databases
* internet access

AI functionality is optional.

When AI mode is enabled, only the relevant system context required for the request is sent to the configured AI provider, sanitized to `[REDACTED]` first for hosted providers. Local mode sends nothing anywhere.

LOGICROOT must never intentionally send:

* passwords
* API keys
* SSH keys
* tokens
* environment secrets
* private file contents

---

# 🏗️ Architecture

```text
                         ┌─────────────────────┐
                         │        LOGICROOT         │
                         │       CLI/TUI       │
                         └──────────┬──────────┘
                                    │
                    ┌───────────────┴───────────────┐
                    │                               │
              CLI Interface                   TUI Interface
                    │                               │
                    └───────────────┬───────────────┘
                                    │
                              Core Services
                                    │
       ┌──────────────┬─────────────┼──────────────┬──────────────┐
       │              │             │              │              │
     System       Processes      Services        Storage       Network
       │              │             │              │              │
       └──────────────┴─────────────┼──────────────┴──────────────┘
                                    │
                              GPU / Hardware
                                    │
                              Diagnostics
                                    │
                              AI Assistant
                                    │
                             Linux Kernel / OS
```

---

# 📁 Project Structure

```text
logicroot/
│
├── src/
│   └── logicroot/
│       │
│       ├── cli.py
│       ├── config.py
│       ├── exceptions.py
│       │
│       ├── core/
│       │
│       ├── system/
│       │
│       ├── processes/
│       │
│       ├── services/
│       │
│       ├── storage/
│       │
│       ├── network/
│       │
│       ├── gpu/
│       │
│       ├── diagnostics/
│       │
│       ├── logs/
│       │
│       ├── cleanup/
│       │
│       ├── assistant/
│       │
│       ├── ui/
│       │
│       └── utils/
│
├── tests/
│
├── assets/
│   ├── demo.gif
│   ├── dashboard.gif
│   └── screenshots/
│
├── pyproject.toml
├── README.md
├── LICENSE
├── CONTRIBUTING.md
└── SECURITY.md
```

---

# 🧰 Technology Stack

<div align="center">

| Technology               | Purpose                   |
| ------------------------ | ------------------------- |
| 🐍 Python                | Core application          |
| ⚡ Typer                  | CLI framework             |
| 🎨 Rich                  | Terminal rendering        |
| 🖥️ Textual              | Interactive TUI           |
| 📊 psutil                | System metrics            |
| 🐧 `/proc`               | Linux process/system data |
| 🐧 `/sys`                | Hardware information      |
| ⚙️ systemd               | Service management        |
| 🎮 NVIDIA/AMD/Intel APIs | GPU monitoring            |

</div>

---

# 🐧 Linux Compatibility

LOGICROOT is designed with distribution portability in mind.

Target environments:

```text
Fedora
Ubuntu
Debian
Arch Linux
Nobara
openSUSE
```

The application should use portable Linux interfaces whenever possible.

Distribution-specific functionality is isolated behind adapters.

```text
PackageManager
│
├── Dnf
├── Apt
├── Pacman
└── Zypper
```

---

# 🧪 Testing

Run:

```bash
pytest
```

Run with coverage:

```bash
pytest --cov=logicroot
```

The test suite should not depend on the developer's actual hardware.

System interfaces are mocked where appropriate.

---

# 🛠️ Development

Clone:

```bash
git clone https://github.com/madhav-manchanda/LogicRoot.git

cd logicroot
```

Create environment:

```bash
python -m venv .venv
source .venv/bin/activate
```

Install development dependencies:

```bash
pip install -e ".[dev]"
```

Run LOGICROOT:

```bash
logicroot
```

Run tests:

```bash
pytest
```

---

# 🗺️ Roadmap

```text
LOGICROOT DEVELOPMENT ROADMAP

                    COMPLETE
                       │
                       ▼
              ┌─────────────────┐
              │ CLI Foundation  │
              └────────┬────────┘
                       │
                       ▼
              ┌─────────────────┐
              │ System Monitor  │
              └────────┬────────┘
                       │
                       ▼
              ┌─────────────────┐
              │ Process Manager │
              └────────┬────────┘
                       │
                       ▼
              ┌─────────────────┐
              │ Service Manager │
              └────────┬────────┘
                       │
                       ▼
              ┌─────────────────┐
              │ Storage Engine  │
              └────────┬────────┘
                       │
                       ▼
              ┌─────────────────┐
              │ Network Monitor │
              └────────┬────────┘
                       │
                       ▼
              ┌─────────────────┐
              │  GPU Monitor    │
              └────────┬────────┘
                       │
                       ▼
              ┌─────────────────┐
              │  Diagnostics    │
              └────────┬────────┘
                       │
                       ▼
              ┌─────────────────┐
              │   TUI Dashboard │
              └────────┬────────┘
                       │
                       ▼
              ┌─────────────────┐
              │  AI Assistant   │
              └────────┬────────┘
                       │
                       ▼
                     🚀
                  LOGICROOT 1.0
```

### Planned

* [ ] System dashboard
* [ ] Process manager
* [ ] systemd service manager
* [ ] Storage analyzer
* [ ] Network monitor
* [ ] GPU monitoring
* [ ] Log viewer
* [ ] Diagnostics engine
* [ ] Cleanup assistant
* [ ] Interactive TUI
* [ ] AI troubleshooting
* [ ] JSON output
* [ ] Plugin architecture
* [ ] Package manager integration
* [ ] Docker/Podman monitoring
* [ ] SMART disk health
* [ ] Battery health
* [ ] Remote Linux monitoring

---

# 🧩 Future Plugin Architecture

LOGICROOT is intended to become extensible.

Future versions may support:

```text
logicroot plugins
```

with modules such as:

```text
logicroot-docker
logicroot-podman
logicroot-smart
logicroot-battery
logicroot-firewall
logicroot-backup
logicroot-kubernetes
```

The core application should remain lightweight while optional functionality can be added independently.

---

# ⌨️ Keyboard Shortcuts

Inside the TUI:

```text
┌──────────────────────────────┐
│ LOGICROOT SHORTCUTS               │
├──────────────────────────────┤
│ 1    Dashboard               │
│ 2    Processes               │
│ 3    Services                │
│ 4    Storage                 │
│ 5    Network                 │
│ 6    GPU                     │
│ 7    Logs                    │
│ 8    Diagnostics             │
│ 9    Cleanup                 │
│ A    AI Assistant            │
│ R    Refresh                 │
│ /    Search                  │
│ ?    Help                    │
│ Q    Quit                    │
└──────────────────────────────┘
```

---

# 🎯 Design Philosophy

LOGICROOT follows five principles:

### 01 — Local First

Your system information belongs on your system.

### 02 — Safe by Default

Nothing destructive happens without explicit confirmation.

### 03 — Beautiful Terminal UX

The terminal doesn't have to look boring.

### 04 — Linux Native

Use Linux's actual interfaces instead of reinventing them.

### 05 — Explain, Don't Just Display

LOGICROOT should not merely say:

```text
RAM: 91%
```

It should eventually explain:

```text
RAM usage is high.

Chrome is consuming 5.8 GB,
VS Code is consuming 2.1 GB,
and available memory is 1.4 GB.

Here is what you can investigate.
```

---

# 🌟 Why LOGICROOT?

Linux already provides incredible tools.

The problem is that information is fragmented.

```text
          Linux System
               │
      ┌────────┼─────────┐
      │        │         │
     top    systemctl   df
      │        │         │
     ps      journalctl  du
      │        │         │
     ip     nvidia-smi  free
      │        │         │
      └────────┼─────────┘
               │
               ▼
          ┌──────────┐
          │   LOGICROOT   │
          └──────────┘
               │
               ▼
      One consistent interface
```

LOGICROOT doesn't try to replace Linux.

**It brings Linux's capabilities together.**

---

# 🤝 Contributing

Contributions are welcome.

Before opening a pull request:

```bash
pytest
```

Please keep contributions:

* modular
* tested
* documented
* Linux-compatible
* secure

For major architectural changes, open an issue first.

---

# 🔐 Security

If you discover a security vulnerability, please do not publicly disclose it immediately.

See:

[`SECURITY.md`](SECURITY.md)

for the responsible disclosure process.

---

# 📄 License

This project is licensed under the **MIT License**.

See [`LICENSE`](LICENSE).

---

<div align="center">

# ⚡ LOGICROOT

### **Monitor. Diagnose. Manage. Understand.**

```text
$ logicroot

Everything about your Linux system.
One terminal.
One command center.
```

<br />

**Built for Linux. Built in the terminal. Built to be useful.**

<br />

<img src="https://img.shields.io/github/stars/yourusername/logicroot?style=for-the-badge&logo=github" alt="GitHub Stars">
<img src="https://img.shields.io/github/forks/yourusername/logicroot?style=for-the-badge&logo=github" alt="GitHub Forks">
<img src="https://img.shields.io/github/issues/yourusername/logicroot?style=for-the-badge" alt="GitHub Issues">

</div>
