LocalHero

A keyboard-driven, text-mode (TUI) coding assistant backed by local inference — Ollama by default, with an optional llama.cpp (llama-server) backend LocalHero can launch and supervise itself, or any other OpenAI-compatible server (LM Studio, vLLM, …). No cloud required, keyboard-driven — a fast terminal UI over your own models and your own git repo.

See docs/DEVELOPMENT.md for the full architecture.

Installation

From PyPI:

pipx install localhero     # recommended — isolated environment for a CLI tool
# or
uvx localhero               # run it without installing anything
# or
pip install localhero

From source (for development, or to track main):

# with uv (recommended)
git clone https://github.com/Bzoink/LocalHero.git
cd LocalHero
uv sync
uv run localhero [PATH]

# or with pip
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
localhero [PATH]

PATH defaults to the current directory; LocalHero roots itself at that folder's git repo if it's inside one (otherwise it works directly in PATH, just without git as an edit safety net — see Git integration).

Run localhero --version to check what's installed, or localhero --help for all flags.

Prerequisites

A modern terminal, and an Ollama server with gemma4 pulled:

ollama pull gemma4

Ollama is the default backend and is required for embeddings/RAG regardless of which backend serves chat. See docs/DEVELOPMENT.md for running chat against llama.cpp or another OpenAI-compatible server instead.

Screens

Key	Screen
F1	Files — tree with git status, pick what the AI sees, build a RAG index
F2	Ask AI — chat / request changes
F3	Editor — files as-on-disk, changes highlighted vs HEAD
F4	Review — accept/reject the AI's proposed edits, file by file
F9	Settings — backend, host, models, edit format, verify, tools
Ctrl+Q	Quit

Files (F1) — Space toggles a file into the AI's context, c clears the context set. For repos too large to hand-pick, i builds a local embeddings index (SQLite, cosine similarity) so Ask AI can retrieve relevant chunks automatically instead; I rebuilds it from scratch.

Ask AI (F2) renders finished replies as Markdown with highlighted code, and copies selected text to your OS clipboard as a fallback to OSC 52. Conversations autosave per-project to ~/.local/share/localhero/sessions/ and resume — Ctrl+N starts a fresh chat (the old one stays saved), Ctrl+O opens the session picker (load, delete, or clear all). A status line shows the active backend, model, context size, and whether context comes from manually selected files or the RAG index; Ctrl+T shows exactly what was sent on the last turn (files, chunks, token count), with a warning if anything was truncated or dropped for budget.

When a request implies edits, the model's proposed changes land on the Review screen (F4) as a per-file diff — a/x accept or reject the current file, A/Esc accept or reject everything. Accepted files are written to disk; if the folder is a git repo, a snapshot is taken before the first write of a batch as an undo safety net (r in the Editor reverts a file to HEAD).

The model always has a sandboxed calculator (### CALC: <expr>) for exact arithmetic. Further extras are optional and off by default, in F9:

• Reasoning — for thinking-capable Ollama models, streams the model's chain-of-thought into a separate dim block above the answer.
• Shell commands — lets the model request commands via ### RUN: <cmd>; each one is shown for approval (project directory as cwd) before it runs.
• Web search — lets the model look things up (docs, APIs, current info) via ### SEARCH: <query>. Two pluggable providers: Brave (needs an API key; search.api_key or $BRAVE_API_KEY) and a self-hosted SearXNG instance (most private). By default only the search provider is contacted (snippets only); turning on fetch also lets the model read a specific result page in full via ### FETCH: <url>.
• Verify — after edits are accepted (or on demand with Ctrl+R), runs a configured test/build command and, on failure, feeds the output back to the model for a bounded auto-fix attempt. Set the command to auto to have LocalHero guess one from the project's files (pytest, npm test, cargo test, go test, …).

The model can also request to see a file it wasn't given (<<<READ path>>>), bounded to a few rounds per turn, so edits aren't made on a guess.

Development

uv sync --all-extras                            # install dev dependencies
uv run pytest                                    # run tests
uv run textual run --dev localhero.app:LocalHeroApp   # hot-reload dev mode

CI (.github/workflows/ci.yml) runs the test suite on Python 3.11–3.13 for every push and pull request. Dependency versions are pinned in uv.lock for reproducible installs — commit changes to it alongside pyproject.toml.