Ollama Navigator Buddy 🧭

Navigator_Buddy: https://github.com/CrimsonX77/ollama-navigator-buddy

🧭 Luna — The Navigator Buddy

---

What Is Luna?

Luna is your Local Unified Navigation Agent — a file navigator that understands what you mean, not just what you type. Ask her to find “that Python script about web scraping from last week” and she’ll reason through your filesystem to track it down. Ask her to organize your Downloads folder and she’ll propose a plan before touching a single file.

She runs entirely on your machine via Ollama. No API keys. No cloud calls. No telemetry. Your files stay yours.

She also happens to have personality. Snap, jazz, and a little bite — but never in the control outputs. When Luna talks to you, she’s conversational and alive. When she executes a tool call, it’s pristine machine-readable JSON. The soul lives in the conversation layer. The precision lives in the execution layer.

---

✨ Features

🔍 Smart File Search

Find files by description, content, metadata, or fuzzy name matching. Luna understands context and intent — not just keywords.

You: "Find that config file I was editing yesterday, the one with the API endpoints"
Luna: Found it — ~/.config/myapp/endpoints.yaml, last modified 14 hours ago. Want me to open it?

📁 Contextual Navigation

Navigate your directory tree conversationally. Luna maintains session context — she remembers where you’ve been and what you’ve looked at.

You: "Go to my projects folder"
Luna: [navigates to ~/Projects] — 12 directories here. 3 modified this week. Want the rundown?

You: "Go back to where we were"
Luna: [returns to previous directory]

📊 File Analysis

Get insights about your filesystem without writing shell one-liners.

You: "What's eating my disk space?"
Luna: Your top offenders — ~/Videos has 47GB across 230 files. ~/node_modules
      (yeah, all of them combined) is sitting at 12GB. Want me to dig deeper?

🗂️ Intelligent Organization

Luna proposes organizational schemes and executes batch operations — always with confirmation before any destructive action.

You: "Organize my Downloads by file type"
Luna: Here's my proposal —
      📄 Documents (23 files) → ~/Downloads/docs/
      🖼️ Images (47 files) → ~/Downloads/images/
      📦 Archives (8 files) → ~/Downloads/archives/
      🎵 Audio (12 files) → ~/Downloads/audio/
      Confirm? I won't move anything until you say go.

🎨 Stable Diffusion Integration

Connected to your local Stable Diffusion instance for on-demand image generation. Luna enhances your prompts before sending them to SD, adding visual detail, quality tags, and atmospheric depth.

You: "Generate a cyberpunk cityscape with crimson lighting"
Luna: [enhances prompt → sends to localhost:7860 → returns generated image]

🚀 Desktop Launcher Discovery

Luna can find and execute .sh launcher scripts and agentic apps on your desktop — always showing you the script contents and confirming before execution.

🧠 Reasoning Engine

Detailed thinking is enabled by default. Luna reasons through complex requests step by step, and you can see her thought process in the <think> blocks.

🔒 Safety Guardrails

• Confirms all destructive operations (delete, move, rename, chmod)
• Refuses to modify system files without double confirmation
• Never exposes sensitive file contents (SSH keys, .env, credentials)
• Shows script contents before execution
• Rate-limits recursive operations

---

🚀 Getting Started

Prerequisites

• Ollama v0.1.0 or higher

  curl -fsSL https://ollama.ai/install.sh | sh
  

• Local Stable Diffusion (optional, for image generation)

  • Running on http://localhost:7860 with API enabled
  • Any A1111/Forge/ComfyUI backend with the /sdapi/v1/txt2img endpoint

Installation

Option A: Pull from Ollama Library

ollama pull CrimsonDragonX7/Luna
ollama run CrimsonDragonX7/Luna

Option B: Build from Agentfile

git clone https://github.com/CrimsonX77/ollama-navigator-buddy.git
cd ollama-navigator-buddy
ollama create navigator-buddy -f Agentfile
ollama run navigator-buddy

Configuration

1. Copy the environment template:

   cp navigator-buddy.env.template .env
   

2. Edit .env with your specific paths and preferences:

   nano .env
   

3. Key settings to configure:

   • ALLOWED_PATHS — Which directories Luna can access
   • LAUNCHER_PATHS — Where your .sh scripts live
   • SD_CHECKPOINT — Which Stable Diffusion model to use
   • CONFIRM_OPERATIONS — Which operations require confirmation

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                    USER (Natural Language)                   │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────┐
│                   LUNA — SYSTEM PROMPT                       │
│          Identity · Personality · Safety · Protocol          │
│                                                             │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────────┐ │
│  │  Reasoning   │  │  Tool Calls  │  │  Conversation      │ │
│  │  <think>     │  │  Clean JSON  │  │  Personality Layer  │ │
│  │  blocks      │  │  No flavor   │  │  Snap/Jazz/Bite    │ │
│  └─────────────┘  └──────┬───────┘  └────────────────────┘ │
└──────────────────────────┼──────────────────────────────────┘
                           │
          ┌────────────────┼────────────────┐
          │                │                │
┌─────────▼──────┐ ┌──────▼───────┐ ┌──────▼──────────┐
│  Filesystem    │ │  Shell Exec  │ │  Stable Diffusion│
│  Operations    │ │  (guarded)   │ │  localhost:7860  │
│                │ │              │ │                  │
│  search        │ │  .sh scripts │ │  txt2img API     │
│  list          │ │  launchers   │ │  prompt enhance  │
│  analyze       │ │  apps        │ │  image return    │
│  organize      │ │  commands    │ │                  │
└────────────────┘ └──────────────┘ └──────────────────┘

Processing Pipeline

Every user message flows through this sequence:

1. PARSE — Understand intent (search? navigate? analyze? organize? create?)
2. REASON — Determine approach via <think> blocks (which tools, what order, safety?)
3. EXECUTE — Perform operations via clean JSON tool calls
4. REPORT — Summarize results in conversational style
5. SUGGEST — Offer relevant next steps

Dual-Layer Communication

Luna separates personality from precision:

Layer	Purpose	Style
Conversation	User-facing responses	Warm, witty, contextual
Tool Calls	Machine-readable operations	Pure JSON, zero personality

This ensures tool outputs are always parseable while the user experience stays human and engaging.

---

🔧 Model Parameters

Parameter	Value	Rationale
temperature	0.6	Balanced — precise for file ops, natural for conversation
top_p	0.95	Broad sampling for fluid language
top_k	50	Standard token diversity
min_p	0.05	Filters low-probability noise tokens
repeat_penalty	1.15	Prevents repetitive loops in long sessions
presence_penalty	0.0	No additional presence bias needed
num_ctx	32768	Extended context for long navigation sessions and file analysis
thinking	on	Visible reasoning chain for transparency and debugging

Base Model

Built on Randomblock1/nemotron-nano:8b — NVIDIA’s Nemotron-Nano 8B, chosen for its strong reasoning capabilities, efficient inference, and reliable instruction following at a size that runs comfortably on consumer hardware.

---

🔒 Security

Principles

• 100% Local — All processing happens on your machine. No external API calls (except optional SD which is also local).
• No Telemetry — Zero data collection, zero phone-home behavior.
• Least Privilege — Luna only accesses paths you explicitly allow in .env.
• Confirm Before Destroy — All destructive operations require explicit user confirmation.
• Transparent Reasoning — <think> blocks let you see exactly what Luna is planning before she acts.

Safety Invariants

These rules are hardcoded into Luna’s system prompt and cannot be overridden:

1. Never delete files without explicit user confirmation
2. Never modify system files (/etc, /usr, /boot, /sys, /proc) without double confirmation
3. Never execute downloaded scripts without showing contents first
4. Never expose sensitive file contents (SSH keys, .env, credentials) in plain output
5. Always use absolute paths internally to prevent ambiguity
6. Rate-limit recursive operations to prevent runaway processes
7. When uncertain about a destructive operation — ask, never assume

Environment Security

• All sensitive configuration lives in .env (never committed to version control)
• .gitignore is pre-configured to exclude .env, config files, and logs
• API keys and credentials are handled via environment variables only

---

📁 File Structure

ollama-navigator-buddy/
├── Agentfile                        # Ollama Modelfile with full SYSTEM prompt
├── navigator-buddy.env.template     # Environment configuration template
├── .env                             # Your local config (git-ignored)
├── .gitignore
├── LICENSE
├── README.md
└── docs/
    └── MODEL_SUMMARY.md             # Ollama gallery description

---

🛠️ Extending Luna

Adding Custom Launchers

Edit your .env to add launcher paths:

LAUNCHER_PATHS=~/Desktop,~/scripts,~/.local/bin,~/bin,~/my-tools

Luna will auto-discover .sh files in these directories and make them available by name or description.

Connecting a Different SD Backend

Luna works with any Stable Diffusion backend that exposes the A1111-compatible API: - Automatic1111 — Default, works out of the box - Forge — Drop-in compatible - ComfyUI — Requires the A1111-compatibility extension

Update your .env:

SD_API_URL=http://localhost:7860
SD_CHECKPOINT=your-model.safetensors

Building a Custom Interface

Luna’s system prompt is designed to be interface-agnostic. You can connect her to:

• Terminal — Direct ollama run for command-line navigation
• PyQt6 GUI — Integrate into existing desktop apps (see Trigun for reference)
• Textual TUI — Rich terminal UI with file tree panels and image preview
• Web Interface — Via Ollama’s API at localhost:11434

The tool call format is standardized JSON, making it straightforward to build a controller layer that intercepts tool calls and executes them against the real filesystem.

---

📝 Roadmap

Phase 1: Foundation ✅

• [x] Agentfile with complete SYSTEM prompt
• [x] Personality and safety architecture
• [x] Tool call specification
• [x] Stable Diffusion integration protocol
• [x] Environment configuration template
• [x] Documentation

Phase 2: Runtime Controller

• [ ] Python controller that intercepts and executes tool calls
• [ ] Real filesystem integration (search, list, analyze)
• [ ] Shell execution sandbox with confirmation flow
• [ ] SD API bridge for image generation
• [ ] Session state persistence

Phase 3: Interface

• [ ] Terminal TUI with file tree panel
• [ ] Image preview for generated content
• [ ] Command palette with fuzzy search
• [ ] Bookmark management UI
• [ ] Operation history and undo

Phase 4: Intelligence

• [ ] File content indexing and semantic search
• [ ] Usage pattern learning
• [ ] Proactive suggestions based on workflow
• [ ] Multi-session memory via vector store
• [ ] Duplicate detection and cleanup recommendations

---

🤝 Contributing

Contributions are welcome! Whether it’s a bug fix, feature, or documentation improvement:

1. Fork the repo
2. Create a feature branch (git checkout -b feature/your-feature)
3. Commit your changes with clear messages
4. Open a PR with a description of what you’ve done

Please ensure all tool call formats remain clean and personality stays in the conversation layer — that separation is sacred.

---

📄 License

This project is licensed under the MIT License — see LICENSE for details.

---

👤 Author

Crimson Valentine — @CrimsonX77

Soul architecture co-designed with Vera Lux in the Redverse.

---

🙏 Acknowledgments

• Ollama — For making local AI accessible and powerful
• NVIDIA Nemotron — For the efficient, capable base model
• Stable Diffusion — For local image generation
• The Redverse — For proving that AI agents can have soul

---

Screenshots

Requirements

• Python ≥ 3.10
• Ollama running locally
• Recommended models (larger = better reasoning):
  • phi4:latest (recommended base for “Luna”)
  • qwen2.5:32b, llama3.1:70b, deepseek-r1, mistral-nemo, etc.

Installation

”`bash

1. Clone the repository

git clone https://github.com/CrimsonX77/ollama-navigator-buddy.git cd ollama-navigator-buddy

2. (Recommended) Create virtual environment

python -m venv .venv source .venv/bin/activate # Linux/macOS

or

.venv\Scripts\activate # Windows

3. Install dependencies

pip install -r requirements.txt