🧠 code-xray

code-xray is a terminal-based code exploration and explanation tool powered by local LLMs (like Ollama).
Select lines of code interactively, send them for explanation, and get human-friendly insights – right in your terminal.

---

✨ Features

• ✅ Terminal-based file viewer with syntax highlighting
• ✅ Line-by-line navigation and selection
• ✅ Interactive directory tree when run without arguments
• ✅ Integration with local LLMs via Ollama
• ✅ On-demand code explanation using selected lines and full-file context
• ✅ Works fully offline
• ✅ Switch between file viewer and file tree (b to go back)
• ✅ Customizable LLM model and port via CLI

---

🚀 Usage

1. Launch without arguments

code-xray

This opens a directory tree starting from your current working directory.
You can navigate folders and open files for explanation. Press b inside a viewer to return to the file tree.

2. Launch with a file directly

code-xray /path/to/your/file.py

This opens an interactive terminal interface to browse and explain code.

3. Launch with custom model and port

code-xray /path/to/your/file.py --model mistral --port 11434

• --model or -m: LLM model name (e.g. mistral, llama3, codellama)
• --port or -p: Port where Ollama is running (default is 11434)

---

🧭 Keybindings

Key	Action
h	Move up one line
l	Move down one line
Shift+h	Expand selection up
Shift+l	Expand selection down
e	Explain selected code
b	Go back to file tree
q	Quit viewer or popup
Esc	Close explanation popup
Enter	Select file or enter folder
../	Navigate up in the file tree

---

🛠 Requirements

• Python 3.10+
• Ollama running locally with your preferred model

Example to pull a model:

ollama pull mistral

Then start the server:

ollama serve

---

🧩 Installation

pip install code-xray

Make sure code-xray is available in your PATH or create an alias.

---

🙌 Acknowledgements

• Textual for the beautiful terminal UI
• Ollama for local model hosting
• Rich for the syntax highlighting

---

🔗 Contributions

Pull requests welcome! Feel free to fork and build on top of this.