@@ -1,56 +1,78 @@ |
| 1 | 1 | # Loader |
| 2 | 2 | |
| 3 | | -Loader is a local-first coding assistant that runs against Ollama and drives a small tool-using agent loop from the terminal or a Textual TUI. |
| 4 | | - |
| 5 | | -## Current state |
| 6 | | - |
| 7 | | -Loader is still early-stage. The project already has: |
| 8 | | - |
| 9 | | -- a working terminal and TUI interface |
| 10 | | -- a default tool set for file reads/writes, editing, search, globbing, and shell commands |
| 11 | | -- project-context detection |
| 12 | | -- runtime safeguards, recovery logic, and heuristic completion checks |
| 13 | | - |
| 14 | | -It does not yet have the stronger runtime architecture described in [`.docs/REPORT.md`](.docs/REPORT.md). The current implementation plan lives under [`.docs/sprints/`](.docs/sprints/index.md), and the Sprint 00 runtime baseline is tracked in [`.docs/PARITY.md`](.docs/PARITY.md). |
| 3 | +Loader is a local-first coding assistant that runs against Ollama and drives a tool-using agent loop from the terminal or a Textual TUI. |
| 15 | 4 | |
| 16 | 5 | ## Requirements |
| 17 | 6 | |
| 18 | 7 | - Python 3.11+ |
| 19 | | -- `uv` |
| 20 | | -- a running local Ollama server on `http://localhost:11434` |
| 21 | | -- at least one pulled Ollama model |
| 8 | +- [uv](https://docs.astral.sh/uv/) |
| 9 | +- a running Ollama server on `http://localhost:11434` |
| 10 | +- at least one pulled Ollama model (see [MODELS.md](MODELS.md)) |
| 22 | 11 | |
| 23 | | -## Setup |
| 12 | +## Install |
| 24 | 13 | |
| 25 | 14 | ```bash |
| 26 | | -uv sync |
| 27 | | -uv sync --extra dev |
| 15 | +# Global install — use loader from any directory |
| 16 | +uv tool install git+https://github.com/tenseleyFlow/loader |
| 17 | +loader "write a hello world program" |
| 18 | + |
| 19 | +# Or install from a local clone |
| 20 | +git clone https://github.com/tenseleyFlow/loader |
| 21 | +cd loader |
| 22 | +uv tool install -e . |
| 28 | 23 | ``` |
| 29 | 24 | |
| 30 | | -## Common commands |
| 25 | +## Development setup |
| 31 | 26 | |
| 32 | 27 | ```bash |
| 33 | | -uv run loader |
| 34 | | -uv run loader "write a hello world program" |
| 35 | | -uv run loader --no-tui |
| 36 | | -uv run loader --select-model |
| 37 | | - |
| 38 | | -uv run pytest |
| 39 | | -uv run pytest tests/test_runtime_harness.py -q |
| 40 | | -uv run ruff check src tests |
| 41 | | -uv run mypy src |
| 28 | +uv sync --extra dev |
| 29 | + |
| 30 | +uv run loader # TUI mode |
| 31 | +uv run loader --no-tui # terminal mode |
| 32 | +uv run loader --select-model # pick an Ollama model |
| 33 | + |
| 34 | +uv run pytest # run all tests |
| 35 | +uv run pytest tests/test_foo.py -q # single file |
| 36 | +uv run ruff check src tests # lint |
| 37 | +uv run mypy src # type check (strict) |
| 38 | +``` |
| 39 | + |
| 40 | +## How it works |
| 41 | + |
| 42 | +Loader sends your prompt to a local Ollama model with tool schemas attached. The model calls tools (read, write, edit, bash, glob, grep, git) to complete the task. A typed turn loop drives the agent cycle: |
| 43 | + |
| 44 | +1. **Prepare** — detect project context, build system prompt, set workflow mode |
| 45 | +2. **Assistant** — stream the model response, extract tool calls |
| 46 | +3. **Tools** — execute the tool batch, record results to session |
| 47 | +4. **Completion** — check definition-of-done, run verification if needed |
| 48 | +5. **Repeat** or **finalize** based on whether the task is complete |
| 49 | + |
| 50 | +The TUI shows tool calls with previews, an approval bar for writes outside the workspace, streaming output, and a status line with session state. |
| 51 | + |
| 52 | +## Key options |
| 53 | + |
| 54 | +``` |
| 55 | +--permission-mode read-only | workspace-write (default) | danger-full-access | prompt | allow |
| 56 | +--select-model choose from installed Ollama models |
| 57 | +--plan start in plan mode (outline before coding) |
| 58 | +--clarify start in clarify mode (ask questions first) |
| 59 | +--react force text-based tool calling (for models without native support) |
| 60 | +--ctx N context window size (default 8192) |
| 42 | 61 | ``` |
| 43 | 62 | |
| 44 | | -## Repository notes |
| 63 | +## Repository layout |
| 45 | 64 | |
| 46 | | -- Loader source lives under `src/loader/` |
| 47 | | -- tests live under `tests/` |
| 48 | | -- reference repos used for comparison live under `refs/` and are gitignored |
| 49 | | -- `uv run pytest` is scoped to Loader's own `tests/` directory |
| 65 | +- `src/loader/runtime/` — turn engine, tool execution, verification, workflow routing |
| 66 | +- `src/loader/tools/` — tool implementations (file, shell, search, git, workflow) |
| 67 | +- `src/loader/llm/` — Ollama backend with native tool calling and streaming |
| 68 | +- `src/loader/ui/` — Textual TUI with tool widgets, approval bar, status line |
| 69 | +- `src/loader/cli/` — Click CLI entry point |
| 70 | +- `tests/` — 416 deterministic tests with scripted backend harness |
| 71 | +- `.docs/` — sprint planning, parity checkpoints, architecture analysis |
| 50 | 72 | |
| 51 | | -## Known limitations |
| 73 | +## Documentation |
| 52 | 74 | |
| 53 | | -- the agent loop is still monolithic and heuristic-heavy |
| 54 | | -- there is a known tool-result contract regression captured by the runtime harness and left red for Sprint 01 |
| 55 | | -- permissions are still confirmation-based rather than mode-based |
| 56 | | -- session persistence, planning artifacts, and verification loops are not implemented yet |
| 75 | +- [MODELS.md](MODELS.md) — recommended Ollama models |
| 76 | +- [.docs/REPORT.md](.docs/REPORT.md) — deep analysis vs reference implementations |
| 77 | +- [.docs/PARITY.md](.docs/PARITY.md) — runtime feature inventory |
| 78 | +- [.docs/sprints/](.docs/sprints/index.md) — sprint planning |
