🧭 LocalPilot

LocalPilot is a local-first, safety-oriented coding assistant that helps you understand and refactor code using a local LLM — without risking repository corruption.

It is built around a strict safety pipeline:

• AST-based code understanding
• System-generated diffs (not LLM-generated)
• Git-validated patch application

LLMs suggest. Systems decide. Git enforces.

---

✨ Key Capabilities

• 🧠 Local LLM support (Qwen / DeepSeek / StarCoder)
• 🌳 AST-based function extraction (Tree-sitter)
• 🔍 Explain files and code structure
• 🔧 Safe function-level refactoring
• 🧪 Git-validated patch application
• 💻 CLI-first workflow (VS Code integration planned)

---

🛡️ Safety Rules (Core Design)

LocalPilot enforces three non-negotiable rules:

Rule 1 — Authoritative Diff Headers

Diff headers and file paths are generated by the system, never by the LLM.

Rule 2 — Validate Before Apply

All patches are validated using:

git apply --check

Rule 3 — Self-Generated Diffs

The LLM outputs refactored code only.
Unified diffs are generated programmatically.

These rules guarantee zero unsafe writes to your repo.

---

🏗️ Architecture Overview

Tree-sitter AST
   ↓
Function Extraction
   ↓
LLM → Refactored Function
   ↓
System → Rebuild File
   ↓
System → Unified Diff
   ↓
git apply --check
   ↓
Optional Apply

---

📁 Project Structure

localpilot/
├── app/
│   ├── assistant/
│   │   ├── llm.py
│   │   ├── prompts.py
│   │   ├── explain.py
│   │   ├── refactor.py
│   │   ├── apply.py
│   │   ├── apply_diff.py
│   │   ├── diff_utils.py
│   │   ├── diff_guard.py
│   │   └── diff_validator.py
│   │
│   ├── cli/
│   │   └── assistant.py
│   │
│   ├── indexer/
│   │   ├── parser.py
│   │   ├── extract.py
│   │   ├── chunker.py
│   │   ├── embed.py
│   │   ├── index_repo.py
│   │   └── summary.py
│   │
│   ├── utils/
│   │   └── diff_check.py
│   │
│   └── config.py
│
├── storage/
├── archive/
├── script-archive/
├── test_sample.py
├── test_run_extraction.py
├── setup.py
├── requirements.txt
└── README.md

---

🚀 Getting Started

1️⃣ Create virtual environment

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

---

2️⃣ Install dependencies

pip install -r requirements.txt
pip install -e .

---

3️⃣ Ensure Git repository

git status

---

🧪 Usage

Explain a file

assistant explain app/assistant/llm.py

Refactor a function

assistant refactor app/assistant/llm.py::generate

---

🗺️ Roadmap

• Qdrant-powered context retrieval
• Multi-function refactors
• VS Code extension
• Test-aware refactoring

---

📜 License

MIT

---

❤️ Philosophy

LLMs assist.
Systems constrain.
Git protects.

📐 Architecture: ARCHITECTURE.md
👩‍💻 Developer Workflow: DEVELOPER_WORKFLOW.md
🔐 Security: SECURITY.md
🤝 Contributing: CONTRIBUTING.md