Metadata-Version: 2.5
Name: logicroot
Version: 0.2.0
Summary: LOGICROOT - a hardware-aware, capability-driven, local-first Linux Command Center
Project-URL: Homepage, https://github.com/madhav-manchanda/linx
Project-URL: Documentation, https://github.com/madhav-manchanda/linx#readme
Project-URL: Issues, https://github.com/madhav-manchanda/linx/issues
Project-URL: Changelog, https://github.com/madhav-manchanda/linx/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/yourusername/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/yourusername/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

### Using pipx

```bash
pipx install logicroot
```

From source:

```bash
logicroot
```

---

### From source

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

cd logicroot

python -m venv .venv

source .venv/bin/activate

pip install -e .
```

With the interactive dashboard:

```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.

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.

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.
```

---

# 🛡️ 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 should be sent to the configured AI provider.

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/linx.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>
