Metadata-Version: 2.4
Name: localhero
Version: 0.1.0
Summary: Keyboard-driven TUI coding assistant backed by local inference (Ollama, llama.cpp, or any OpenAI-compatible server)
Project-URL: Homepage, https://github.com/Bzoink/LocalHero
Project-URL: Repository, https://github.com/Bzoink/LocalHero
Project-URL: Issues, https://github.com/Bzoink/LocalHero/issues
Author: Tony Mattsson
License-Expression: MIT
License-File: LICENSE
Keywords: cli,coding-assistant,llama.cpp,llm,ollama,terminal,textual,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Terminals
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: numpy>=1.26
Requires-Dist: textual[syntax]>=0.80
Requires-Dist: tomli-w>=1.0
Requires-Dist: trafilatura>=1.8
Requires-Dist: tree-sitter-c>=0.23
Requires-Dist: tree-sitter-cpp>=0.23
Requires-Dist: tree-sitter-dockerfile>=0.2
Requires-Dist: tree-sitter-lua>=0.2
Requires-Dist: tree-sitter-make>=1.1
Requires-Dist: tree-sitter-php>=0.23
Requires-Dist: tree-sitter-ruby>=0.23
Requires-Dist: tree-sitter-swift>=0.7
Requires-Dist: tree-sitter-typescript>=0.23
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: textual-dev>=1.5; extra == 'dev'
Description-Content-Type: text/markdown

# LocalHero

[![CI](https://github.com/Bzoink/LocalHero/actions/workflows/ci.yml/badge.svg)](https://github.com/Bzoink/LocalHero/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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](docs/DEVELOPMENT.md) for the full architecture.

## Installation

**From PyPI:**

```bash
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`):

```bash
# 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](docs/DEVELOPMENT.md#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:

```bash
ollama pull gemma4
```

Ollama is the default backend and is required for embeddings/RAG regardless
of which backend serves chat. See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md#inference-backends)
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

```bash
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`.
