locus-cli 0.1.0a2

Lightweight terminal app to quickly understand large codebases

LOCUS 🗺️

The free, 100% private, local-LLM codebase cartographer for your terminal.

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.

---

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

pip install locus-cli

Or to run from source:

git clone https://github.com/Tech-Matt/locus.git
cd locus
python -m venv .venv
source .venv/bin/activate  # Windows: `.venv\Scripts\activate`
pip install -e .

---

Usage

# Show a tree of the current directory
locus tree

# Show a tree of a specific path, with custom depth and ignore rules
locus tree /path/to/codebase --depth 3 --ignore build --ignore dist

# Print version
locus --version

---

Roadmap

• Recursive tree mapping with smart filtering and file caps
• Hardware profiling (Apple Silicon, NVIDIA, AMD, CPU-only detection)
• locus tree CLI command (depth, max-files, ignore flags)
• PyPI packaging (pip install locus-cli)
• locus overview — static codebase stats (file counts, languages, largest folders)
• Progressive rendering — stream tree output incrementally for large repos
• Local LLM summaries — auto-download and run architecture-optimized models
• TUI — full interactive terminal UI

---

Made with ❤️ by Tech-Matt