locus-cli 0.1.0a1__tar.gz

locus_cli-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mattia Rizzo
+
+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.

locus_cli-0.1.0a1/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: locus-cli
+Version: 0.1.0a1
+Summary: Lightweight terminal app to quickly understand large codebases
+Author: Mattia Rizzo
+License: MIT
+Project-URL: Homepage, https://github.com/Tech-Matt/locus
+Project-URL: Repository, https://github.com/Tech-Matt/locus
+Keywords: cli,tui,llm,codebase,textual,rich
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: textual>=0.70.0
+Requires-Dist: rich>=13.0.0
+Dynamic: license-file
+
+<div align="center">
+
+# LOCUS 🗺️
+
+**The free, 100% private, local-LLM codebase cartographer for your terminal.**
+
+[![Python 3.x](https://img.shields.io/badge/python-3.x-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Status: Work in Progress](https://img.shields.io/badge/Status-WIP-orange.svg)]()
+
+*Stop paying for expensive API keys just to understand a codebase. Locus is a lightweight terminal tool that automatically downloads and runs architecture-optimized local LLMs to instantly map and summarize large codebases—for free, and 100% privately.*
+
+</div>
+
+---
+
+## Why Locus?
+I wanted a tool to explore new and large codebases (like the *Linux Kernel* source code 😄), with an intuitive and powerful UI. **Locus** provides instant visual overviews and directory trees right in your terminal, helping you map out the structure before you deep dive into the code.
+
+### Free, Open, Local Intelligence
+You shouldn't have to pay for expensive Gemini, Claude, or OpenAI API keys just to understand a codebase. **Locus dynamically profiles** your PC's hardware (Apple Silicon, NVIDIA, AMD GPU, or CPU-only) and automatically downloads and runs **architecture-optimized local LLMs**. You get instant and private folder summaries running entirely on your own machine—for free. *(Cloud APIs are still supported if you prefer them).*
+
+- **Zero-Friction:** Just do `pip install locus-cli` and run `locus`. No Docker, no manual model downloading. (Still to be packaged as of now)
+- **Fast & Native:** A fast TUI built with `Textual` and `Rich`.
+- **Private by Default:** Your proprietary code never leaves your machine unless you explicitly configure a cloud provider.
+
+### Current Platform Support
+- **macOS (Apple Silicon / arm64):** Supported
+- **macOS (Intel / x86_64):** Not supported yet
+- **Linux:** Supported
+- **Windows:** Supported
+
+---
+
+## Installation
+
+*Note: Locus is currently in active development. A v0.1 release is coming soon!*
+
+```bash
+git clone https://github.com/Tech-Matt/locus.git
+cd locus
+python -m venv myEnv
+source myEnv/bin/activate  # Windows: `myEnv\Scripts\activate`
+pip install -r requirements.txt
+python main.py
+```
+
+---
+
+## Usage
+
+Run `locus` in any directory you want to explore:
+
+```bash
+cd /path/to/massive/codebase
+locus
+```
+
+**Keybindings:**
+- `j` / `k` : Scroll Down / Up
+- `d` : Toggle Dark/Light Mode
+- `q` : Quit Locus
+- `A` : (Coming Soon) Generate a quick summary for the selected folder
+
+---
+
+## Roadmap
+
+- [x] **Phase 1: Visual Engine** (Recursive parsing, smart filtering, TUI scaffolding)
+- [x] **Phase 2: Hardware Profiling** (Native GPU/RAM detection, model mapping)
+- [ ] **Phase 3: Local Summaries** (Local inference engine, TUI integration)
+- [ ] **Phase 4: Testing & Hardening** (Unit tests, CI/CD pipeline)
+- [ ] **Phase 5: Packaging** (PyPI release, zero-dependency binaries)
+
+---
+
+<div align="center">
+Made with ❤️ by <a href="https://github.com/Tech-Matt">Tech-Matt</a>
+</div>

locus_cli-0.1.0a1/README.md

@@ -0,0 +1,79 @@
+<div align="center">
+
+# LOCUS 🗺️
+
+**The free, 100% private, local-LLM codebase cartographer for your terminal.**
+
+[![Python 3.x](https://img.shields.io/badge/python-3.x-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Status: Work in Progress](https://img.shields.io/badge/Status-WIP-orange.svg)]()
+
+*Stop paying for expensive API keys just to understand a codebase. Locus is a lightweight terminal tool that automatically downloads and runs architecture-optimized local LLMs to instantly map and summarize large codebases—for free, and 100% privately.*
+
+</div>
+
+---
+
+## Why Locus?
+I wanted a tool to explore new and large codebases (like the *Linux Kernel* source code 😄), with an intuitive and powerful UI. **Locus** provides instant visual overviews and directory trees right in your terminal, helping you map out the structure before you deep dive into the code.
+
+### Free, Open, Local Intelligence
+You shouldn't have to pay for expensive Gemini, Claude, or OpenAI API keys just to understand a codebase. **Locus dynamically profiles** your PC's hardware (Apple Silicon, NVIDIA, AMD GPU, or CPU-only) and automatically downloads and runs **architecture-optimized local LLMs**. You get instant and private folder summaries running entirely on your own machine—for free. *(Cloud APIs are still supported if you prefer them).*
+
+- **Zero-Friction:** Just do `pip install locus-cli` and run `locus`. No Docker, no manual model downloading. (Still to be packaged as of now)
+- **Fast & Native:** A fast TUI built with `Textual` and `Rich`.
+- **Private by Default:** Your proprietary code never leaves your machine unless you explicitly configure a cloud provider.
+
+### Current Platform Support
+- **macOS (Apple Silicon / arm64):** Supported
+- **macOS (Intel / x86_64):** Not supported yet
+- **Linux:** Supported
+- **Windows:** Supported
+
+---
+
+## Installation
+
+*Note: Locus is currently in active development. A v0.1 release is coming soon!*
+
+```bash
+git clone https://github.com/Tech-Matt/locus.git
+cd locus
+python -m venv myEnv
+source myEnv/bin/activate  # Windows: `myEnv\Scripts\activate`
+pip install -r requirements.txt
+python main.py
+```
+
+---
+
+## Usage
+
+Run `locus` in any directory you want to explore:
+
+```bash
+cd /path/to/massive/codebase
+locus
+```
+
+**Keybindings:**
+- `j` / `k` : Scroll Down / Up
+- `d` : Toggle Dark/Light Mode
+- `q` : Quit Locus
+- `A` : (Coming Soon) Generate a quick summary for the selected folder
+
+---
+
+## Roadmap
+
+- [x] **Phase 1: Visual Engine** (Recursive parsing, smart filtering, TUI scaffolding)
+- [x] **Phase 2: Hardware Profiling** (Native GPU/RAM detection, model mapping)
+- [ ] **Phase 3: Local Summaries** (Local inference engine, TUI integration)
+- [ ] **Phase 4: Testing & Hardening** (Unit tests, CI/CD pipeline)
+- [ ] **Phase 5: Packaging** (PyPI release, zero-dependency binaries)
+
+---
+
+<div align="center">
+Made with ❤️ by <a href="https://github.com/Tech-Matt">Tech-Matt</a>
+</div>

locus_cli-0.1.0a1/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "locus-cli"
+version = "0.1.0a1"
+description = "Lightweight terminal app to quickly understand large codebases"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{name = "Mattia Rizzo"}]
+keywords = ["cli", "tui", "llm", "codebase", "textual", "rich"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Documentation",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "textual>=0.70.0",
+    "rich>=13.0.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/Tech-Matt/locus"
+Repository = "https://github.com/Tech-Matt/locus"
+
+[project.scripts]
+locus = "locus_cli.main:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+exclude = ["*.tests", "*.tests.*", "tests.*", "tests"]
+
+[tool.setuptools.package-data]
+locus_cli = ["ui/*.tcss"]

locus_cli-0.1.0a1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

locus_cli-0.1.0a1/src/locus_cli/core/map.py

@@ -0,0 +1,133 @@
+# This files needs to take a folder address like 'src' or '.' and return a Tree
+# object which the UI can then render
+
+import os
+from pathlib import Path
+from rich.tree import Tree
+from rich.text import Text
+from rich.filesize import decimal
+from rich.markup import escape
+from ui.console import console
+
+class LocusMap:
+    # Default list of folders to ignore
+    IGNORE_FOLDERS = {
+        "__pycache__", 
+        "node_modules", 
+        "venv", 
+        "myEnv",
+        ".git", 
+        ".idea", 
+        ".vscode",
+        "dist",
+        "build",
+        "target", # Rust/Java
+        "bin",    # C#
+        "obj",    # C#
+        "vendor"  # PHP/Go
+    }
+    
+    # Maximum number of files to display per directory
+    # If there are more files, show "N more files..." instead
+    MAX_FILES_PER_DIR = 10
+
+    # The constructor gets called on the root folder of interest
+    def __init__(self, root_dir, max_depth):
+        self.root_dir = root_dir
+        self.max_depth = max_depth
+
+    def generate(self):
+        """
+        Starting from the root folder, it creates the tree and then returns it
+        """
+        # Get the folder name
+        # resolve() makes the Path absolute, resolving any symlink
+        # .name returns the last part, like "setup.py"
+        root_name = Path(self.root_dir).resolve().name
+
+        # Create the visual Root Node
+        tree = Tree(f"[bold blue]{root_name}[/]")
+
+        # Start walking in a recursive fashion
+        self._walk(self.root_dir, tree, current_depth=0)
+
+        return tree
+
+    # The walk is based on a DFS Search (Depth first search)
+    def _walk(self, directory, tree_node, current_depth):
+        """
+        It looks at 'directory' and adds items to 'tree_node'.
+        It calls itself if it finds a subfolder
+        """
+        # Get all the items in the directory
+        try:
+            # Sorting works in this way:
+            # - folders are showed first, then files. If same type, then order
+            # - by name.
+            paths = sorted(
+                Path(directory).iterdir(), # This is a list of PosixPathor WinwdowsPath
+                key=lambda p: (not p.is_dir(), p.name.lower())
+            )
+
+        except PermissionError:
+            # Handle folders we can't open
+            tree_node.add("[red]Access Denied[/]")
+            return
+        
+        # Separate directories and files for the heuristic
+        directories = []
+        files = []
+        
+        for path in paths:
+            # Filter: skip hidden files or folders
+            if path.name.startswith("."):
+                continue
+            # Filter: skip common dep/cache folders
+            if path.name in self.IGNORE_FOLDERS: 
+                continue
+
+            if path.is_dir():
+                directories.append(path)
+            else:
+                files.append(path)
+
+        # Always show all directories (no limit)
+        for path in directories:
+            # Create a new branch for this folder
+            # escape() here escapes the folder name to delete possible rich tags
+            branch = tree_node.add(f"[bold green]{escape(path.name)}[/]")
+
+            # Recursion, dive into the folder only if we haven't hit the depth limit
+            if current_depth < self.max_depth - 1:
+                self._walk(path, branch, current_depth + 1)
+        
+        # Limit the number of files shown
+        files_shown = 0
+        for path in files:
+            if files_shown >= self.MAX_FILES_PER_DIR:
+                break
+            
+            # Calculate size for display
+            file_size = decimal(path.stat().st_size)
+            # Add simple icons based on extension
+            icon = "🐍" if path.suffix == ".py" else "📄"
+            # Add the leaf node
+            tree_node.add(
+                f"{icon} {escape(path.name)} ([dim]{file_size}[/])"
+            )
+            files_shown += 1
+        
+        # If there are more files than shown, add a summary message
+        remaining_files = len(files) - files_shown
+        if remaining_files > 0:
+            tree_node.add(
+                f"[dim italic]... {remaining_files} more file{'s' if remaining_files > 1 else ''}[/]"
+            )
+
+# [REMOVE LATER] Just use this as temporary quick tests
+if __name__ == "__main__":
+    # Debug testing with console.print()
+    root_folder = Path("~/LinuxSource/.").expanduser()
+    map = LocusMap(root_folder, 3)
+    tree = map.generate()
+    console.print(tree)

locus_cli-0.1.0a1/src/locus_cli/core/profiler.py

@@ -0,0 +1,94 @@
+"""
+This module provides hardware profiling capabilities.
+It detects system RAM and available GPUs or AI accelerators.
+"""
+
+import psutil
+import subprocess
+import platform
+import shutil
+
+
+class HardwareProfiler:
+    def get_total_ram_gb(self) -> float:
+        """
+        Detects the total physical RAM of the system.
+        Returns the value in GB rounded to 2 decimal places
+        """
+        total_mem_bytes = psutil.virtual_memory().total
+        total_mem = total_mem_bytes / (1024 * 1024 * 1024) # Convert from Bytes to GigaBytes
+        return round(total_mem, 2)
+
+    def detect_gpu(self) -> dict:
+        """
+        Attempts to detect available AI accelerators (Apple Silicon, NVIDIA, AMD).
+        Returns a dictionary with 'type' and 'vram_gb' (if applicable).
+        """
+        # Default fallback
+        gpu_info = {"type": "CPU_ONLY", "vram_gb": 0.0}
+
+        # Get system infos
+        system = platform.system()
+        machine = platform.machine()
+
+        # 1. Apple Silicon Check
+        if system == "Darwin" and machine == "arm64":
+            # Apple uses unified memory, so its VRAM is just the system RAM!
+            vram = self.get_total_ram_gb()
+            gpu_info = {"type": "APPLE_SILICON", "vram_gb": vram}
+
+        # 2. Nvidia
+        # This checks whether the nvidia driver is installed. If so, the gpu vram
+        # is requested
+        if shutil.which("nvidia-smi") is not None:
+            result = subprocess.run(
+                ["nvidia-smi", "--query-gpu=memory.total", "--format=csv,noheader,nounits"],
+                capture_output=True, text=True
+                )
+            # The result.stdout will be a string like "8192\n" (in MB).
+            if result.returncode == 0 and result.stdout.strip():
+                # If there are multiple GPUs nvidia-smi might output more lines, so we use split()
+                vram_mb = float(result.stdout.strip().split('\n')[0])
+                vram_gb = round(vram_mb / 1024, 2) # Convert to GB
+                gpu_info = {"type": "NVIDIA", "vram_gb": vram_gb}
+
+
+        # 3. AMD Check. In this case we are not going to check VRAM since CUDA is unavailable
+        # but Vulkan may be used 
+        if gpu_info["type"] == "CPU_ONLY":
+            try:
+                if system == "Windows":
+                    result = subprocess.run(
+                        ["wmic", "path", "win32_VideoController", "get", "name"],
+                        capture_output=True, text=True
+                    )
+                    if "AMD" in result.stdout.upper() or "RADEON" in result.stdout.upper():
+                        gpu_info = {"type": "AMD", "vram_gb": 0.0}
+
+                elif system == "Linux":
+                    result = subprocess.run(
+                        ["lspci"],
+                        capture_output=True, text=True
+                    )
+                    if "AMD" in result.stdout.upper() or "RADEON" in result.stdout.upper():
+                        gpu_info = {"type": "AMD", "vram_gb": 0.0}
+
+            except FileNotFoundError:
+                # If the AMD GPU is not found we are simply ignoring the error
+                # and return the default CPU_ONLY Fallback 
+                pass 
+
+
+        return gpu_info
+
+
+
+# [REMOVE LATER]
+if __name__ == "__main__":
+    profiler = HardwareProfiler()
+    ram = profiler.get_total_ram_gb()
+    gpu_info = profiler.detect_gpu()
+    system = gpu_info.get("type")
+    vram = gpu_info.get("vram_gb")
+    print(f"System RAM detected: {ram} GB")
+    print(f"System type: {system}, VRAM detected {vram} GB")

locus_cli-0.1.0a1/src/locus_cli/core/provisioner.py

@@ -0,0 +1,92 @@
+import os
+import platform
+import urllib.request
+from pathlib import Path
+
+class Provisioner:
+    """
+    Maps Hardware profiles to specific AI models and inference binaries,
+    and handles downloading them to the local system.
+    """
+
+    # Model Matrix
+    # Format: {Tier: (Filename, HuggingFace Download URL)}
+    MODELS = {
+        1: ("qwen2.5-coder-7b-instruct-q4_k_m.gguf", "https://huggingface.co/Qwen/Qwen2.5-Coder-7B-Instruct-GGUF/resolve/main/qwen2.5-coder-7b-instruct-q4_k_m.gguf"),
+        2: ("qwen2.5-coder-3b-instruct-q4_k_m.gguf", "https://huggingface.co/Qwen/Qwen2.5-Coder-3B-Instruct-GGUF/resolve/main/qwen2.5-coder-3b-instruct-q4_k_m.gguf"),
+        3: ("qwen2.5-coder-1.5b-instruct-q4_k_m.gguf", "https://huggingface.co/Qwen/Qwen2.5-Coder-1.5B-Instruct-GGUF/resolve/main/qwen2.5-coder-1.5b-instruct-q4_k_m.gguf"),
+        4: ("qwen2.5-coder-0.5b-instruct-q4_k_m.gguf", "https://huggingface.co/Qwen/Qwen2.5-Coder-0.5B-Instruct-GGUF/resolve/main/qwen2.5-coder-0.5b-instruct-q4_k_m.gguf")
+    }
+
+
+    # The Binary Matrix (llama.cpp server releases)
+    # URLS will need to be updated to the latest release tag
+    # TODO: Port later to manifest.json
+    BINARIES = {
+        "Windows": {
+            "CUDA": "https://github.com/ggml-org/llama.cpp/releases/download/b8133/llama-b8133-bin-win-cuda-13.1-x64.zip",
+            "Vulkan": "https://github.com/ggml-org/llama.cpp/releases/download/b8133/llama-b8133-bin-win-vulkan-x64.zip",
+            "CPU": "https://github.com/ggml-org/llama.cpp/releases/download/b8133/llama-b8133-bin-win-cpu-x64.zip"
+        },
+        "Linux": {
+            "CUDA": "https://github.com/ggml-org/llama.cpp/releases/download/b8133/llama-b8133-bin-ubuntu-x64.tar.gz",
+            "Vulkan": "https://github.com/ggml-org/llama.cpp/releases/download/b8133/llama-b8133-bin-ubuntu-vulkan-x64.tar.gz",
+            "CPU": "https://github.com/ggml-org/llama.cpp/releases/download/b8133/llama-b8133-bin-ubuntu-x64.tar.gz"
+        },
+        "Darwin": {
+            "APPLE_SILICON": "https://github.com/ggml-org/llama.cpp/releases/download/b8133/llama-b8133-bin-macos-arm64.tar.gz"
+        }
+    }
+
+    def __init__(self):
+        # Define where Locus will store its data
+        self.locus_dir = Path.home() / ".locus"
+        self.models_dir = self.locus_dir / "models"
+        self.bin_dir = self.locus_dir / "bin"
+        # Handle directories already existing
+        self.locus_dir.mkdir(parents=True, exist_ok=True)
+        self.models_dir.mkdir(parents=True, exist_ok=True)
+        self.bin_dir.mkdir(parents=True, exist_ok=True)
+
+    def determine_tier(self, ram_gb: float, gpu_type: str, vram_gb: float) -> int:
+        """
+        Calculates the appropriate model tier based on hardware.
+        Tier 1: High-End (8GB+ VRAM or 16GB+ Apple Silicon)
+        Tier 2: Mid-Range (4-6GB VRAM or 16GB+ RAM CPU)
+        Tier 3: Low-End (8GB RAM CPU)
+        Tier 4: Potato PC (<8GB RAM CPU)
+        """
+        gpu = (gpu_type or "").upper()
+
+        # Apple Silicon
+        if gpu == "APPLE_SILICON":
+            if ram_gb >= 16:
+                return 1
+            if ram_gb >= 8:
+                return 3
+            return 4
+        
+        # Discrete GPU
+        if vram_gb >= 8:
+            return 1
+        if vram_gb >= 4:
+            return 2
+        
+        # CPU only
+        if ram_gb >= 16:
+            return 2
+        if ram_gb >= 8:
+            return 3
+        
+        # Default case - Tier 4
+        return 4
+    
+    def get_binary_preference(self, os_name: str, gpu_type: str, user_choice: str = "auto") -> str:
+        """
+        Determines which llama.cpp to download
+        user_choice can be 'CUDA', 'Vulkan', 'CPU' or 'auto'.
+        """
+        # TODO: Map the OS and GPU type to the correct key in self.BINARIES
+
+    def download_file():
+        pass

locus_cli-0.1.0a1/src/locus_cli/ui/app.py

@@ -0,0 +1,70 @@
+# This file will use the Textual library to create a UI
+
+from textual.app import App, ComposeResult
+from textual.widgets import Header, Footer, Static
+from textual.containers import ScrollableContainer, VerticalScroll
+from pathlib import Path
+
+from core.map import LocusMap
+
+class LocusApp(App):
+    """
+    The Textual UI for locus
+    """
+    def __init__(self, root_dir, max_depth):
+        # Let's call the textual.App constructor first (necessary)
+        super().__init__()
+        self.root_dir = root_dir
+        self.max_depth = max_depth # Maximum depth of subfolders
+
+    # Textual uses CSS for the UI
+    CSS_PATH = "style.tcss"
+
+    # Bindings: allow user to press keys to do things
+    BINDINGS = [
+        ("q", "quit", "Quit Locus"),
+        ("d", "toggle_dark", "Toggle Dark Mode"),
+        ("j", "scroll_down", "Scroll Down"),
+        ("k", "scroll_up", "Scroll Up")
+    ]
+
+    def compose(self) -> ComposeResult:
+        """
+        Create child widgets for the APP
+        """
+        yield Header()
+        yield VerticalScroll(Static(id="map-view"), id="main-scroll")
+        yield Footer() 
+
+
+    def on_mount(self) -> None:
+        """
+        This method runs exactly once, right after the app is
+        built and rendered. This is where data is fetched and
+        the UI updated
+        """
+        locus_map = LocusMap(self.root_dir, self.max_depth)
+        tree = locus_map.generate()
+        self.query_one("#map-view", Static).update(tree)
+        pass
+
+    def action_toggle_dark(self) -> None:
+        self.theme = (
+            "textual-dark" if self.theme == "textual-light" else "textual-light"
+        )
+    
+    def action_scroll_down(self) -> None:
+        scroll_view = self.query_one("#main-scroll", VerticalScroll)
+        scroll_view.scroll_down()
+
+    def action_scroll_up(self) -> None:
+        scroll_view = self.query_one("#main-scroll", VerticalScroll)
+        scroll_view.scroll_up()
+
+    def action_quit(self) -> None:
+        self.exit()
+
+# [REMOVE LATER] For testing the UI directly
+if __name__ == "__main__":
+    app = LocusApp(Path("~/LinuxSource/linux/").expanduser(), 3)
+    app.run()

locus_cli-0.1.0a1/src/locus_cli/ui/console.py

@@ -0,0 +1,4 @@
+# Rich will read the properties of the console being used and optimize the 
+# use of colors everywhere when it is used in other parts of the project
+from rich.console import Console
+console = Console()

locus_cli-0.1.0a1/src/locus_cli.egg-info/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: locus-cli
+Version: 0.1.0a1
+Summary: Lightweight terminal app to quickly understand large codebases
+Author: Mattia Rizzo
+License: MIT
+Project-URL: Homepage, https://github.com/Tech-Matt/locus
+Project-URL: Repository, https://github.com/Tech-Matt/locus
+Keywords: cli,tui,llm,codebase,textual,rich
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: textual>=0.70.0
+Requires-Dist: rich>=13.0.0
+Dynamic: license-file
+
+<div align="center">
+
+# LOCUS 🗺️
+
+**The free, 100% private, local-LLM codebase cartographer for your terminal.**
+
+[![Python 3.x](https://img.shields.io/badge/python-3.x-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Status: Work in Progress](https://img.shields.io/badge/Status-WIP-orange.svg)]()
+
+*Stop paying for expensive API keys just to understand a codebase. Locus is a lightweight terminal tool that automatically downloads and runs architecture-optimized local LLMs to instantly map and summarize large codebases—for free, and 100% privately.*
+
+</div>
+
+---
+
+## Why Locus?
+I wanted a tool to explore new and large codebases (like the *Linux Kernel* source code 😄), with an intuitive and powerful UI. **Locus** provides instant visual overviews and directory trees right in your terminal, helping you map out the structure before you deep dive into the code.
+
+### Free, Open, Local Intelligence
+You shouldn't have to pay for expensive Gemini, Claude, or OpenAI API keys just to understand a codebase. **Locus dynamically profiles** your PC's hardware (Apple Silicon, NVIDIA, AMD GPU, or CPU-only) and automatically downloads and runs **architecture-optimized local LLMs**. You get instant and private folder summaries running entirely on your own machine—for free. *(Cloud APIs are still supported if you prefer them).*
+
+- **Zero-Friction:** Just do `pip install locus-cli` and run `locus`. No Docker, no manual model downloading. (Still to be packaged as of now)
+- **Fast & Native:** A fast TUI built with `Textual` and `Rich`.
+- **Private by Default:** Your proprietary code never leaves your machine unless you explicitly configure a cloud provider.
+
+### Current Platform Support
+- **macOS (Apple Silicon / arm64):** Supported
+- **macOS (Intel / x86_64):** Not supported yet
+- **Linux:** Supported
+- **Windows:** Supported
+
+---
+
+## Installation
+
+*Note: Locus is currently in active development. A v0.1 release is coming soon!*
+
+```bash
+git clone https://github.com/Tech-Matt/locus.git
+cd locus
+python -m venv myEnv
+source myEnv/bin/activate  # Windows: `myEnv\Scripts\activate`
+pip install -r requirements.txt
+python main.py
+```
+
+---
+
+## Usage
+
+Run `locus` in any directory you want to explore:
+
+```bash
+cd /path/to/massive/codebase
+locus
+```
+
+**Keybindings:**
+- `j` / `k` : Scroll Down / Up
+- `d` : Toggle Dark/Light Mode
+- `q` : Quit Locus
+- `A` : (Coming Soon) Generate a quick summary for the selected folder
+
+---
+
+## Roadmap
+
+- [x] **Phase 1: Visual Engine** (Recursive parsing, smart filtering, TUI scaffolding)
+- [x] **Phase 2: Hardware Profiling** (Native GPU/RAM detection, model mapping)
+- [ ] **Phase 3: Local Summaries** (Local inference engine, TUI integration)
+- [ ] **Phase 4: Testing & Hardening** (Unit tests, CI/CD pipeline)
+- [ ] **Phase 5: Packaging** (PyPI release, zero-dependency binaries)
+
+---
+
+<div align="center">
+Made with ❤️ by <a href="https://github.com/Tech-Matt">Tech-Matt</a>
+</div>

locus_cli-0.1.0a1/src/locus_cli.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+src/locus_cli/__init__.py
+src/locus_cli/main.py
+src/locus_cli.egg-info/PKG-INFO
+src/locus_cli.egg-info/SOURCES.txt
+src/locus_cli.egg-info/dependency_links.txt
+src/locus_cli.egg-info/entry_points.txt
+src/locus_cli.egg-info/requires.txt
+src/locus_cli.egg-info/top_level.txt
+src/locus_cli/core/map.py
+src/locus_cli/core/profiler.py
+src/locus_cli/core/provisioner.py
+src/locus_cli/ui/app.py
+src/locus_cli/ui/console.py
+src/locus_cli/ui/style.tcss

locus_cli-0.1.0a1/src/locus_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

locus_cli-0.1.0a1/src/locus_cli.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+locus = locus_cli.main:main

locus_cli-0.1.0a1/src/locus_cli.egg-info/requires.txt

@@ -0,0 +1,2 @@
+textual>=0.70.0
+rich>=13.0.0

locus_cli-0.1.0a1/src/locus_cli.egg-info/top_level.txt

@@ -0,0 +1 @@
+locus_cli