PyPI - lcode-cli - Versions diffs - 0.1.1__tar.gz → 0.2.0__tar.gz - Mend

lcode-cli 0.1.1tar.gz → 0.2.0tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (69) hide show

lcode_cli-0.2.0/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,105 @@
+# Changelog
+All notable changes to lcode are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/).
+## [Unreleased]
+## [0.2.0] - 2026-09-29
+### Added
+- Web access for the model: `web_search` finds current information (latest releases, docs, error
+  messages) through Ollama web search, Brave Search, Tavily or a self-hosted SearXNG, and `web_fetch`
+  reads pages as clean text. On by default; `lcode config set web ask|off` or `lcode --no-web` limits
+  it. Search API keys are read from environment variables only. Closes #7.
+## [0.1.2] - 2026-09-29
+### Added
+- All eight catalog models are now tested end to end (`qwen3.8-27b`, `qwen3.6-27b`, `laguna-xs-2.1`,
+  `nemotron-3.5-lightning` and `gpt-oss-20b` joined the three tested before), with a results table
+  in the models guide. `laguna-xs-2.1`'s cache size is now measured rather than estimated.
+- When a model fails to load because its context doesn't fit in GPU memory, lcode retries with half the
+  context and remembers the size that worked for that model (`~/.local/state/lcode/limits.json`, shown
+  by `lcode doctor`), so later sessions don't fail first. Found with `nemotron-3.5-lightning`, whose 1M
+  context doesn't fit on a 12 GB GPU.
+- Named sessions and a session picker: `/rename <name>` names the current session, `/resume` lists
+  saved sessions and resumes the one you pick (by number, name, id or title), `/resume all` shows
+  every folder, and `lcode --resume [SESSION]` does the same from the shell. Resuming shows a short
+  recap of where you left off.
+### Changed
+- `lcode setup` recommends `gpt-oss-20b` at 64K (instead of `qwen3.5-4b`) for 8 GB GPUs with 16 GB of
+  RAM, and prefers `qwen3.5-9b` over `gpt-oss-20b` where both fit.
+- lcode is on PyPI as `lcode-cli`; the installer now installs the latest release from PyPI instead of
+  the `main` branch.
+### Fixed
+- `qwen3.6-35b` could crash Ollama with "CUDA error: an illegal memory access" on 12 GB GPUs: its
+  prompt batch of 1024 left too little VRAM for the model's speculative-decoding context. The default
+  is now Ollama's 512 (1024 remains available with `lcode config set num_batch 1024`), and when the GPU
+  runs out of memory before answering, lcode retries automatically with a batch of 512.
+- A tool call with invalid JSON arguments no longer aborts the request: lcode tells the model what
+  was wrong and lets it try again. Unknown or missing tool arguments are reported with the list of
+  valid arguments.
+- `lcode -c` continues the most recently *used* session in the folder, not the most recently created
+  one. Empty sessions are no longer saved.
+- `/rename` saves the session right away, so a session named before its first request shows up in
+  `/resume`.
+- Typing `exit` or `quit` (without a slash) quits instead of being sent to the model as a request.
+- Compacted sessions keep their original title instead of showing the summary header.
+## [0.1.1] - 2026-09-28
+### Added
+- `qwen3.5-9b` and `qwen3.5-4b` are now tested end to end, with measured speed and memory on a 12 GB
+  GPU in the docs. `lcode setup` now recommends only tested models on common machines.
+- Social preview image for the repository and link previews for the docs site.
+- Release workflow that publishes to PyPI with Trusted Publishing.
+### Changed
+- Memory estimates use ~1 GB of runtime overhead instead of 1.5 GB, matching measurements, so small
+  models get larger context windows (e.g. `qwen3.5-9b` at 128K on a 12 GB GPU).
+### Fixed
+- `lcode --model X` no longer reuses the context window saved for the default model; it picks the
+  largest window that fits X. `/model` does the same inside a session.
+- `lcode models` fits in 80-column terminals.
+## [0.1.0] - 2026-09-28
+First public release.
+### Added
+- Interactive terminal agent with streaming markdown output, reasoning display, `@file` attachments,
+  slash commands, a status bar and resumable sessions (`lcode -c`).
+- One-shot mode for scripts: `lcode -p "..."`.
+- Tools for the model: `read_file`, `write_file`, `edit_file` (with diff previews and a
+  whitespace-tolerant fallback), `list_dir`, `glob`, `grep` (ripgrep with a pure-Python fallback),
+  `bash` (live output, timeouts, persistent working directory) and `todo_write`.
+- Permission modes `ask`, `auto-edit` and `yolo` (Shift+Tab cycles), with a read-only command
+  allowlist and "always allow" per command.
+- Model catalog with eight open-weight models, hardware detection for Linux + NVIDIA and Apple
+  Silicon Macs, and memory-fit estimates that pick the largest context window that fits.
+- `lcode setup` (recommend, download and configure a model), `lcode models`, `lcode doctor` and
+  `lcode config`.
+- Choice of context window per run (`--context 128k`), per session (`/ctx`) or in the config file.
+- Text-only model variants that drop unused vision projectors to free GPU memory.
+- Automatic conversation compaction when the context window is 85% full, plus `/compact`.
+- `AGENTS.md` project instructions and `/init` to generate them.
+- One-line installer for Linux and macOS.
+[Unreleased]: https://github.com/nasser1941/lcode/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/nasser1941/lcode/compare/v0.1.2...v0.2.0
+[0.1.2]: https://github.com/nasser1941/lcode/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/nasser1941/lcode/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/nasser1941/lcode/releases/tag/v0.1.0

{lcode_cli-0.1.1 → lcode_cli-0.2.0}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lcode-cli
-Version: 0.1.1
+Version: 0.2.0
 Summary: A local-first terminal coding agent powered by open-weight models on your own GPU or Mac, via Ollama.
 Project-URL: Homepage, https://nasser1941.github.io/lcode/
 Project-URL: Documentation, https://nasser1941.github.io/lcode/
@@ -39,12 +39,13 @@ Description-Content-Type: text/markdown
 <p align="center">
   <b>A coding agent that runs entirely on your own machine.</b><br>
-  Open-weight models · up to 256K tokens of context · your NVIDIA GPU or Apple Silicon Mac · no API keys, no cloud
+  Open-weight models · up to 256K tokens of context · your NVIDIA GPU or Apple Silicon Mac · your code stays local
 </p>
 <p align="center">
   <a href="https://github.com/nasser1941/lcode/actions/workflows/ci.yml"><img src="https://github.com/nasser1941/lcode/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://nasser1941.github.io/lcode/"><img src="https://github.com/nasser1941/lcode/actions/workflows/docs.yml/badge.svg" alt="Docs"></a>
+  <a href="https://pypi.org/project/lcode-cli/"><img src="https://img.shields.io/pypi/v/lcode-cli.svg" alt="PyPI"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
   <img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10+">
   <img src="https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20(Apple%20Silicon)-lightgrey.svg" alt="Linux and macOS">
@@ -64,7 +65,7 @@ Description-Content-Type: text/markdown
 Point lcode at a repository and talk to it in your terminal. It explores the code, answers
 questions with `file:line` references, writes and edits files, runs your scripts and tests, and
 keeps going until the task is done, asking before it changes anything. The model runs locally
-through [Ollama](https://ollama.com), so your code never leaves your machine.
+through [Ollama](https://ollama.com), and when it needs current information it can search the web.
 ## Features
@@ -75,8 +76,12 @@ through [Ollama](https://ollama.com), so your code never leaves your machine.
   largest context that fits: `lcode setup` does it in one step.
 - **Safe by default.** Every edit is shown as a diff and every command that isn't read-only needs
   your approval. `auto-edit` and `yolo` modes when you want speed.
-- **Bring your own model.** Eight curated open-weight models, or any Ollama model with tool calling.
-- **Private.** No telemetry, no accounts, no API keys.
+- **Bring your own model.** Eight curated open-weight models, all tested end to end, or any Ollama model
+  with tool calling.
+- **Web search when needed.** Looks up the latest versions, docs and error messages with Ollama web
+  search, Brave, Tavily or your own SearXNG, and reads pages as clean text.
+- **Private.** The model runs on your machine, lcode never uploads your files and has no telemetry.
+  Web access is on by default and can be set to `ask` or `off`.
 ## Install
@@ -88,14 +93,16 @@ curl -fsSL https://nasser1941.github.io/lcode/install.sh | bash
 The installer sets up lcode with its own Python via [uv](https://docs.astral.sh/uv/), checks for
 [Ollama](https://ollama.com) (0.30+) and runs `lcode setup`, which picks a model for your hardware
-and downloads it. Prefer manual steps? See the
-[installation guide](https://nasser1941.github.io/lcode/installation/), or:
+and downloads it. Prefer manual steps? lcode is on [PyPI](https://pypi.org/project/lcode-cli/) as
+`lcode-cli`:
 ```bash
-uv tool install git+https://github.com/nasser1941/lcode
+uv tool install lcode-cli      # or: pipx install lcode-cli
 lcode setup
 ```
+See the [installation guide](https://nasser1941.github.io/lcode/installation/) for details.
 ## Quickstart
 ```bash
@@ -113,9 +120,10 @@ lcode
 | | |
 |---|---|
 | `lcode -p "…"` | one request, no interaction (scripts, hooks) |
-| `lcode -c` | continue the last session in this directory |
+| `lcode -c` / `lcode --resume` | continue the last session here / pick a saved session from a list |
 | `lcode --model qwen3.5-9b --context 128k` | pick a model and context window for this session |
 | `lcode models` / `lcode doctor` | what fits this machine / check the installation |
+| `/rename`, `/resume` | name the current session, resume a saved one |
 | `/model`, `/ctx 128k`, `/compact`, `/help` | switch model, resize context, summarize, list commands |
 ## Models
@@ -123,12 +131,12 @@ lcode
 | Key | Model | Download | Max context | |
 |---|---|---|---|---|
 | `qwen3.6-35b` | Qwen3.6 35B-A3B Coding (MoE, 3B active) | 22.6 GB | 256K | **default**, tested |
-| `qwen3.8-27b` | Qwen3.8 27B (dense) | 17.7 GB | 256K | |
-| `qwen3.6-27b` | Qwen3.6 27B Coding (dense) | 17.8 GB | 256K | |
-| `laguna-xs-2.1` | Poolside Laguna XS 2.1 (MoE, 3B active) | 20.3 GB | 256K | |
-| `nemotron-3.5-lightning` | NVIDIA Nemotron 3.5 Lightning (hybrid MoE) | 25.4 GB | 1M | |
-| `gpt-oss-20b` | OpenAI gpt-oss 20B (MoE) | 13.8 GB | 128K | |
+| `qwen3.8-27b` | Qwen3.8 27B (dense) | 17.7 GB | 256K | tested |
+| `qwen3.6-27b` | Qwen3.6 27B Coding (dense) | 17.8 GB | 256K | tested |
+| `laguna-xs-2.1` | Poolside Laguna XS 2.1 (MoE, 3B active) | 20.3 GB | 256K | tested |
+| `nemotron-3.5-lightning` | NVIDIA Nemotron 3.5 Lightning (hybrid MoE) | 25.4 GB | 1M | tested |
 | `qwen3.5-9b` | Qwen3.5 9B (dense) | 6.6 GB | 256K | tested |
+| `gpt-oss-20b` | OpenAI gpt-oss 20B (MoE) | 13.8 GB | 128K | tested |
 | `qwen3.5-4b` | Qwen3.5 4B (dense) | 3.4 GB | 256K | tested |
 What `lcode setup` picks for common machines:
@@ -140,7 +148,7 @@ What `lcode setup` picks for common machines:
 | Mac with M4 Pro / M4 Max, 36 GB | qwen3.6-35b | 64K |
 | Mac with M4 Pro, 48 GB · M4 Max, 64 GB+ | qwen3.6-35b | 256K |
 | NVIDIA 8–24 GB + 32 GB RAM | qwen3.6-35b | 256K |
-| NVIDIA 8 GB + 16 GB RAM | qwen3.5-4b | 64K |
+| NVIDIA 8 GB + 16 GB RAM | gpt-oss-20b | 64K |
 On an RTX 4080 Laptop GPU (12 GB) the default model generates 50–60 tokens/s at 256K context, and
 qwen3.5-9b 64 tokens/s at 128K. See

{lcode_cli-0.1.1 → lcode_cli-0.2.0}/README.md RENAMED Viewed

@@ -6,12 +6,13 @@
 <p align="center">
   <b>A coding agent that runs entirely on your own machine.</b><br>
-  Open-weight models · up to 256K tokens of context · your NVIDIA GPU or Apple Silicon Mac · no API keys, no cloud
+  Open-weight models · up to 256K tokens of context · your NVIDIA GPU or Apple Silicon Mac · your code stays local
 </p>
 <p align="center">
   <a href="https://github.com/nasser1941/lcode/actions/workflows/ci.yml"><img src="https://github.com/nasser1941/lcode/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://nasser1941.github.io/lcode/"><img src="https://github.com/nasser1941/lcode/actions/workflows/docs.yml/badge.svg" alt="Docs"></a>
+  <a href="https://pypi.org/project/lcode-cli/"><img src="https://img.shields.io/pypi/v/lcode-cli.svg" alt="PyPI"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
   <img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10+">
   <img src="https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20(Apple%20Silicon)-lightgrey.svg" alt="Linux and macOS">
@@ -31,7 +32,7 @@
 Point lcode at a repository and talk to it in your terminal. It explores the code, answers
 questions with `file:line` references, writes and edits files, runs your scripts and tests, and
 keeps going until the task is done, asking before it changes anything. The model runs locally
-through [Ollama](https://ollama.com), so your code never leaves your machine.
+through [Ollama](https://ollama.com), and when it needs current information it can search the web.
 ## Features
@@ -42,8 +43,12 @@ through [Ollama](https://ollama.com), so your code never leaves your machine.
   largest context that fits: `lcode setup` does it in one step.
 - **Safe by default.** Every edit is shown as a diff and every command that isn't read-only needs
   your approval. `auto-edit` and `yolo` modes when you want speed.
-- **Bring your own model.** Eight curated open-weight models, or any Ollama model with tool calling.
-- **Private.** No telemetry, no accounts, no API keys.
+- **Bring your own model.** Eight curated open-weight models, all tested end to end, or any Ollama model
+  with tool calling.
+- **Web search when needed.** Looks up the latest versions, docs and error messages with Ollama web
+  search, Brave, Tavily or your own SearXNG, and reads pages as clean text.
+- **Private.** The model runs on your machine, lcode never uploads your files and has no telemetry.
+  Web access is on by default and can be set to `ask` or `off`.
 ## Install
@@ -55,14 +60,16 @@ curl -fsSL https://nasser1941.github.io/lcode/install.sh | bash
 The installer sets up lcode with its own Python via [uv](https://docs.astral.sh/uv/), checks for
 [Ollama](https://ollama.com) (0.30+) and runs `lcode setup`, which picks a model for your hardware
-and downloads it. Prefer manual steps? See the
-[installation guide](https://nasser1941.github.io/lcode/installation/), or:
+and downloads it. Prefer manual steps? lcode is on [PyPI](https://pypi.org/project/lcode-cli/) as
+`lcode-cli`:
 ```bash
-uv tool install git+https://github.com/nasser1941/lcode
+uv tool install lcode-cli      # or: pipx install lcode-cli
 lcode setup
 ```
+See the [installation guide](https://nasser1941.github.io/lcode/installation/) for details.
 ## Quickstart
 ```bash
@@ -80,9 +87,10 @@ lcode
 | | |
 |---|---|
 | `lcode -p "…"` | one request, no interaction (scripts, hooks) |
-| `lcode -c` | continue the last session in this directory |
+| `lcode -c` / `lcode --resume` | continue the last session here / pick a saved session from a list |
 | `lcode --model qwen3.5-9b --context 128k` | pick a model and context window for this session |
 | `lcode models` / `lcode doctor` | what fits this machine / check the installation |
+| `/rename`, `/resume` | name the current session, resume a saved one |
 | `/model`, `/ctx 128k`, `/compact`, `/help` | switch model, resize context, summarize, list commands |
 ## Models
@@ -90,12 +98,12 @@ lcode
 | Key | Model | Download | Max context | |
 |---|---|---|---|---|
 | `qwen3.6-35b` | Qwen3.6 35B-A3B Coding (MoE, 3B active) | 22.6 GB | 256K | **default**, tested |
-| `qwen3.8-27b` | Qwen3.8 27B (dense) | 17.7 GB | 256K | |
-| `qwen3.6-27b` | Qwen3.6 27B Coding (dense) | 17.8 GB | 256K | |
-| `laguna-xs-2.1` | Poolside Laguna XS 2.1 (MoE, 3B active) | 20.3 GB | 256K | |
-| `nemotron-3.5-lightning` | NVIDIA Nemotron 3.5 Lightning (hybrid MoE) | 25.4 GB | 1M | |
-| `gpt-oss-20b` | OpenAI gpt-oss 20B (MoE) | 13.8 GB | 128K | |
+| `qwen3.8-27b` | Qwen3.8 27B (dense) | 17.7 GB | 256K | tested |
+| `qwen3.6-27b` | Qwen3.6 27B Coding (dense) | 17.8 GB | 256K | tested |
+| `laguna-xs-2.1` | Poolside Laguna XS 2.1 (MoE, 3B active) | 20.3 GB | 256K | tested |
+| `nemotron-3.5-lightning` | NVIDIA Nemotron 3.5 Lightning (hybrid MoE) | 25.4 GB | 1M | tested |
 | `qwen3.5-9b` | Qwen3.5 9B (dense) | 6.6 GB | 256K | tested |
+| `gpt-oss-20b` | OpenAI gpt-oss 20B (MoE) | 13.8 GB | 128K | tested |
 | `qwen3.5-4b` | Qwen3.5 4B (dense) | 3.4 GB | 256K | tested |
 What `lcode setup` picks for common machines:
@@ -107,7 +115,7 @@ What `lcode setup` picks for common machines:
 | Mac with M4 Pro / M4 Max, 36 GB | qwen3.6-35b | 64K |
 | Mac with M4 Pro, 48 GB · M4 Max, 64 GB+ | qwen3.6-35b | 256K |
 | NVIDIA 8–24 GB + 32 GB RAM | qwen3.6-35b | 256K |
-| NVIDIA 8 GB + 16 GB RAM | qwen3.5-4b | 64K |
+| NVIDIA 8 GB + 16 GB RAM | gpt-oss-20b | 64K |
 On an RTX 4080 Laptop GPU (12 GB) the default model generates 50–60 tokens/s at 256K context, and
 qwen3.5-9b 64 tokens/s at 128K. See

{lcode_cli-0.1.1 → lcode_cli-0.2.0}/SECURITY.md RENAMED Viewed

@@ -27,10 +27,15 @@ user, in your working directory**. It is not a sandbox. Keep in mind:
   allowlist (`ls`, `cat`, `grep`, `git status`, …) is shown to you and needs your approval.
   `auto-edit` skips approval for edits; `yolo` skips all approval — use it only in disposable
   environments (a container, a VM, a throwaway clone).
-- Content the model reads (files, command output, web pages fetched by commands) can contain prompt
-  injections that try to make it run harmful commands. Review commands before approving them.
-- lcode talks only to the Ollama server you configure (default `http://localhost:11434`). It sends no
-  telemetry. If you point `ollama_host` at a remote server, your prompts and code go to that server.
+- Content the model reads (files, command output, search results and web pages) can contain prompt
+  injections that try to make it run harmful commands. lcode marks web content as untrusted, but
+  review commands before approving them.
+- The model runs on the Ollama server you configure (default `http://localhost:11434`); if you point
+  `ollama_host` at a remote server, your prompts and code go to that server. lcode sends no telemetry.
+- With web access on (the default), search queries go to the configured search provider and fetched
+  pages are downloaded from their websites. The model writes the queries, so they can contain names or
+  snippets from your code. Use `web = ask` to approve each search, or `web = off` / `--no-web` to
+  keep everything local.
 - Sessions (including file contents the model read) are stored in `~/.local/state/lcode/sessions`.
 Reports about bypassing the permission prompts, the read-only allowlist, or data leaving the

{lcode_cli-0.1.1 → lcode_cli-0.2.0}/docs/configuration.md RENAMED Viewed

@@ -17,11 +17,14 @@ lcode config path                      # print the file location
 |---|---|---|
 | `model` | `qwen3.6-35b` | Catalog key (see `lcode models`) or any installed Ollama model tag |
 | `context` | largest that fits | Context window in tokens; accepts `128k`, `1m` |
-| `num_batch` | per model | Prompt batch size. Larger reads prompts faster but needs more GPU memory |
+| `num_batch` | 512 | Prompt batch size. Larger reads prompts faster but needs more GPU memory |
 | `keep_alive` | `30m` | How long Ollama keeps the model in memory after the last request |
 | `ollama_host` | `http://localhost:11434` | Ollama server URL |
 | `permission_mode` | `ask` | `ask`, `auto-edit` or `yolo` |
 | `think` | `true` | Let the model reason before answering |
+| `web` | `on` | Web search and page fetching: `on`, `ask` (before each search/website) or `off` |
+| `search_backend` | `auto` | `auto`, `ollama`, `brave`, `tavily` or `searxng`; `auto` uses the first one configured |
+| `searxng_url` | | Your SearXNG instance, e.g. `http://localhost:8888` |
 Example file:
@@ -44,6 +47,8 @@ Environment variables override the file, which is useful for one-off runs and CI
 | `LCODE_NUM_BATCH` | `num_batch` |
 | `LCODE_KEEP_ALIVE` | `keep_alive` |
 | `OLLAMA_HOST` | `ollama_host` (same variable the Ollama CLI uses) |
+| `LCODE_WEB` | `web` |
+| `OLLAMA_API_KEY`, `BRAVE_API_KEY`, `TAVILY_API_KEY` | API key for that [search provider](usage.md#web-search) (never stored in the config file) |
 | `LCODE_HOME` | where sessions and prompt history are stored |
 ## Files lcode creates
@@ -53,14 +58,17 @@ Environment variables override the file, which is useful for one-off runs and CI
 | `~/.config/lcode/config.toml` | Settings |
 | `~/.local/state/lcode/sessions/` | Saved conversations (for `lcode -c`) |
 | `~/.local/state/lcode/history` | Prompt history (++up++ in the prompt) |
+| `~/.local/state/lcode/limits.json` | Context sizes that ran out of GPU memory on this machine (safe to delete) |
 Sessions contain everything the model read, including file contents. Delete the folder to clear them.
 ## Tuning for speed and memory
-- **Out-of-memory errors:** lower the context (`/ctx 128k`) or the prompt batch
-  (`lcode config set num_batch 512`).
-- **Slow first answers on big files:** a larger `num_batch` (1024–2048) reads prompts faster if your
-  GPU has room. lcode uses 1024 for `qwen3.6-35b`, the most that fits a 12 GB GPU next to a 256K cache.
+- **Out-of-memory errors:** lower the context (`/ctx 128k`), close other programs using the GPU, or
+  pick a smaller model (`/models`).
+- **Slow first answers on big files:** a larger prompt batch reads prompts faster if your GPU has
+  room: `lcode config set num_batch 1024` makes `qwen3.6-35b` read prompts ~1.8x faster (~500 instead
+  of ~280 tokens/s on a 12 GB GPU). On a 12 GB GPU at 256K context it only fits when little else uses
+  VRAM; if the GPU runs out of memory before answering, lcode retries automatically with 512.
 - **Faster answers, less accuracy:** `--no-think` or `/think off`.
 - **Keep the model warm:** `keep_alive = "2h"` avoids reload delays between sessions but holds the memory.

{lcode_cli-0.1.1 → lcode_cli-0.2.0}/docs/how-it-works.md RENAMED Viewed

@@ -52,15 +52,19 @@ Two lessons from tuning the default model on a 12 GB GPU shaped the defaults:
   out-of-memory crashes at large batch sizes. lcode creates text-only variants (`lcode-<key>`) that
   reuse the downloaded weights.
 - **Prompt batch size dominates prompt-reading speed** when experts sit in system RAM: 512 → 280
-  tokens/s, 1024 → 500 tokens/s. 2048 (~700 tokens/s) doesn't fit next to a 256K cache on 12 GB.
+  tokens/s, 1024 → 500 tokens/s. But the model's speculative-decoding context grows with the batch
+  (0.8 GB at 512, 1.1 GB at 1024), and at 1024 it only fits next to a 256K cache on 12 GB when little
+  else uses VRAM; otherwise CUDA fails with "illegal memory access". lcode therefore uses Ollama's
+  default of 512 and, if a larger configured batch runs out of memory, retries with 512.
 ## Security model
 lcode runs with your user's permissions and is not a sandbox. The permission prompts, the read-only
 allowlist and the "read before edit" rule are guardrails against mistakes, not against a determined
 attacker. Files and command output can contain prompt injections, so review commands before
-approving them, and keep `yolo` mode for disposable environments. lcode sends no telemetry and
-talks only to the Ollama server you configure. See the [security policy](https://github.com/nasser1941/lcode/blob/main/SECURITY.md).
+approving them, and keep `yolo` mode for disposable environments. lcode sends no telemetry; besides
+the Ollama server you configure, it only contacts the web when the model searches or fetches a page
+(see [Web search](usage.md#web-search)). See the [security policy](https://github.com/nasser1941/lcode/blob/main/SECURITY.md).
 ## Code map

{lcode_cli-0.1.1 → lcode_cli-0.2.0}/docs/index.md RENAMED Viewed

@@ -12,7 +12,7 @@ hide:
 # lcode
 **A coding agent that runs entirely on your own machine.**
-Open-weight models · up to 256K tokens of context · your NVIDIA GPU or Apple Silicon Mac · no API keys, no cloud.
+Open-weight models · up to 256K tokens of context · your NVIDIA GPU or Apple Silicon Mac · your code stays local.
 [Get started](installation.md){ .md-button .md-button--primary }
 [View on GitHub](https://github.com/nasser1941/lcode){ .md-button }
@@ -37,8 +37,9 @@ until the task is done, asking before it changes anything.
     ---
-    Your code never leaves your machine. The model runs locally through [Ollama](https://ollama.com);
-    lcode sends no telemetry.
+    The model runs locally through [Ollama](https://ollama.com), lcode never uploads your files and
+    sends no telemetry. Web search is there when the model needs current information, and can be
+    turned off.
 -   :material-robot-outline:{ .lg .middle } **A real agent, not autocomplete**

{lcode_cli-0.1.1 → lcode_cli-0.2.0}/docs/installation.md RENAMED Viewed

@@ -52,21 +52,29 @@ curl -fsSL https://nasser1941.github.io/lcode/install.sh | bash
 ```
 The [installer](https://github.com/nasser1941/lcode/blob/main/install.sh) installs
-[uv](https://docs.astral.sh/uv/) if needed, installs lcode with its own Python into `~/.local/bin`,
-checks that Ollama is running, and starts `lcode setup`.
+[uv](https://docs.astral.sh/uv/) if needed, installs the latest release of lcode from
+[PyPI](https://pypi.org/project/lcode-cli/) with its own Python into `~/.local/bin`, checks that
+Ollama is running, and starts `lcode setup`.
 ??? note "Prefer to do it by hand?"
-    With [uv](https://docs.astral.sh/uv/getting-started/installation/):
+    lcode is published on PyPI as `lcode-cli` (the command is `lcode`). With
+    [uv](https://docs.astral.sh/uv/getting-started/installation/):
     ```bash
-    uv tool install git+https://github.com/nasser1941/lcode
+    uv tool install lcode-cli
     ```
     Or with [pipx](https://pipx.pypa.io):
     ```bash
-    pipx install git+https://github.com/nasser1941/lcode
+    pipx install lcode-cli
+    ```
+    To try the latest unreleased changes from `main`:
+    ```bash
+    uv tool install git+https://github.com/nasser1941/lcode
     ```
     lcode needs Python 3.10 or newer. The macOS system Python is too old, which is why uv (it
@@ -138,7 +146,7 @@ steps. NVIDIA GPUs work inside WSL2 with the regular Windows driver.
 ## Upgrade and uninstall
 ```bash
-uv tool upgrade lcode-cli        # upgrade
+uv tool upgrade lcode-cli        # upgrade (pipx: pipx upgrade lcode-cli)
 uv tool uninstall lcode-cli      # remove lcode
 rm -rf ~/.config/lcode ~/.local/state/lcode    # remove settings and saved sessions
 ollama rm lcode-qwen3.6-35b qwen3.6:35b-a3b-coding   # remove downloaded models

{lcode_cli-0.1.1 → lcode_cli-0.2.0}/docs/models.md RENAMED Viewed

@@ -8,17 +8,17 @@ size, and it works with any other Ollama model that supports tool calling.
 | Key | Model | Type | Download | Max context | Status |
 |---|---|---|---|---|---|
 | `qwen3.6-35b` | Qwen3.6 35B-A3B Coding | MoE, 3B active | 22.6 GB | 256K | **default**, tested |
-| `qwen3.8-27b` | Qwen3.8 27B | dense | 17.7 GB | 256K | untested |
-| `qwen3.6-27b` | Qwen3.6 27B Coding | dense | 17.8 GB | 256K | untested |
-| `laguna-xs-2.1` | Poolside Laguna XS 2.1 | MoE, 3B active | 20.3 GB | 256K | untested |
-| `nemotron-3.5-lightning` | NVIDIA Nemotron 3.5 Lightning | hybrid MoE, 3B active | 25.4 GB | 1M | untested |
-| `gpt-oss-20b` | OpenAI gpt-oss 20B | MoE, 3.6B active | 13.8 GB | 128K | untested |
+| `qwen3.8-27b` | Qwen3.8 27B | dense | 17.7 GB | 256K | tested |
+| `qwen3.6-27b` | Qwen3.6 27B Coding | dense | 17.8 GB | 256K | tested |
+| `laguna-xs-2.1` | Poolside Laguna XS 2.1 | MoE, 3B active | 20.3 GB | 256K | tested |
+| `nemotron-3.5-lightning` | NVIDIA Nemotron 3.5 Lightning | hybrid MoE, 3B active | 25.4 GB | 1M | tested |
 | `qwen3.5-9b` | Qwen3.5 9B | dense | 6.6 GB | 256K | tested |
+| `gpt-oss-20b` | OpenAI gpt-oss 20B | MoE, 3.6B active | 13.8 GB | 128K | tested |
 | `qwen3.5-4b` | Qwen3.5 4B | dense | 3.4 GB | 256K | tested |
-*Tested* means the maintainers verified multi-step tool use (exploring a repo, editing files,
-running commands) end to end. Untested models are expected to work; please
-[report how they do](https://github.com/nasser1941/lcode/issues/new?template=model_request.yml).
+*Tested* means the model passed lcode's two acceptance tasks end to end (see
+[test results](#test-results)). Results on other hardware are very welcome: please
+[report how a model does](https://github.com/nasser1941/lcode/issues/new?template=model_request.yml).
 Run `lcode models` to see the same list with what fits on **your** machine:
@@ -112,10 +112,10 @@ makes long windows affordable:
 | Model | KV cache per token | 32K | 128K | 256K |
 |---|---|---|---|---|
 | qwen3.6-35b | 22 KiB | 23 GB | 25 GB | 28 GB (measured: 26 GB) |
-| qwen3.8-27b / qwen3.6-27b | 68 KiB | 20 GB | 26 GB | 35 GB |
-| laguna-xs-2.1 | ~40 KiB (estimated) | 21 GB | 25 GB | 30 GB |
-| nemotron-3.5-lightning | 7 KiB | 25 GB | 26 GB | 26 GB (1M: 32 GB) |
-| gpt-oss-20b | 24 KiB | 15 GB | 17 GB | — |
+| qwen3.8-27b / qwen3.6-27b | 68 KiB | 20 GB | 26 GB (measured: 24 GB) | 35 GB |
+| laguna-xs-2.1 | 40 KiB | 21 GB | 25 GB | 30 GB (measured: 23 GB) |
+| nemotron-3.5-lightning | 7 KiB | 25 GB | 26 GB | 26 GB (measured: 26 GB; 1M: 32 GB) |
+| gpt-oss-20b | 24 KiB | 15 GB | 17 GB (measured: 14 GB) | — |
 | qwen3.5-9b | 32 KiB | 8 GB | 11 GB (measured: 9.8 GB) | 15 GB (measured: 16 GB) |
 | qwen3.5-4b | 32 KiB | 5 GB | 8 GB (measured: 8.0 GB) | 12 GB |
@@ -140,11 +140,44 @@ results on your machine are welcome in the
 | Mac with M4 Pro / M4 Max, 36 GB | ~24 GB | qwen3.6-35b | 64K | fast |
 | Mac with M4 Pro, 48 GB | ~36 GB | qwen3.6-35b | 256K | fast |
 | Mac with M4 Max, 64–128 GB | 48–96 GB | qwen3.6-35b | 256K | fast |
-| NVIDIA 8 GB + 16 GB RAM | ~16 GB | qwen3.5-4b | 64K | fast |
+| NVIDIA 8 GB + 16 GB RAM | ~16 GB | gpt-oss-20b | 64K | good (experts in RAM) |
 | NVIDIA 8–16 GB + 32 GB RAM | 32–40 GB | qwen3.6-35b | 256K | good (experts in RAM) |
 | NVIDIA 24 GB + 64 GB RAM | ~80 GB | qwen3.6-35b | 256K | good (experts in RAM) |
 | CPU only, 32 GB RAM | ~24 GB | qwen3.5-4b | 256K | slow |
+### Test results
+Every catalog model runs the same two tasks through lcode with its default settings for the machine
+(the context lcode picks, `yolo` mode, reasoning on):
+1. **Bug fix:** tests fail in a small project; the model must find the bug, fix it and re-run the tests.
+2. **Repo question + script:** in the `requests` source, say where the `Authorization` header is
+   stripped on redirects with `file:line` citations, then write and run an `ast`-based script.
+On an RTX 4080 Laptop GPU (12 GB), i9-13980HX, 32 GB RAM:
+| Model | Context | Memory | On GPU | Bug fix | Repo question + script | Speed |
+|---|---|---|---|---|---|---|
+| qwen3.6-35b | 256K | 23.0 GB | 25% | ✓ 30 s | ✓ 45 s | 50–55 tok/s |
+| qwen3.8-27b | 128K | 24.4 GB | 29% | ✓ 86 s | ✓ 284 s | 7–8 tok/s |
+| qwen3.6-27b | 128K | 24.3 GB | 29% | ✓ 78 s | ✓ 267 s | 7 tok/s |
+| laguna-xs-2.1 | 256K | 22.6 GB | 15% | ✓ 67 s | ✓ 195 s | 15–38 tok/s |
+| nemotron-3.5-lightning | 512K² | 27.2 GB | 25% | ✓ 62 s | ✓ 127 s | 44 tok/s |
+| qwen3.5-9b | 128K | 9.8 GB | 100% | ✓ 21 s | ✓ 37 s (2 of 3 runs)¹ | 61–64 tok/s |
+| gpt-oss-20b | 128K | 14.3 GB | 54% | ✓ 16 s | ✓ 36 s | 43 tok/s |
+| qwen3.5-4b | 128K | 8.0 GB | 100% | ✓ 21 s | ✓ 24 s | 93–97 tok/s |
+¹ In one run the 9B saved the script in the wrong folder. `gpt-oss-20b` and `nemotron-3.5-lightning`
+sometimes call tools with arguments that don't exist; they correct themselves from lcode's error
+messages.
+² At its full 1M context Nemotron's cache (7 GB) has to sit in VRAM next to the model and doesn't fit
+on a 12 GB GPU; 512K (3.5 GB) loads fine. lcode handles this by itself: when a model doesn't fit, it
+retries with half the context and remembers the size that worked (see
+[Troubleshooting](troubleshooting.md#out-of-memory-or-cuda-error-an-illegal-memory-access)).
+The dense 27B models are accurate but slow here because only ~30% of them fits in 12 GB of VRAM;
+on a 24 GB GPU or a Mac with enough unified memory they run fully accelerated.
 ### Measured performance
 On an RTX 4080 Laptop GPU (12 GB) with an i9-13980HX and 32 GB RAM, `qwen3.6-35b` at 256K context:
@@ -152,7 +185,7 @@ On an RTX 4080 Laptop GPU (12 GB) with an i9-13980HX and 32 GB RAM, `qwen3.6-35b
 | | |
 |---|---|
 | Generation | 50–60 tokens/s on code (speculative decoding with the model's multi-token prediction) |
-| Prompt reading | ~500 tokens/s: a 60K-token chunk of code takes about 2 minutes the first time |
+| Prompt reading | ~280 tokens/s (~500 with `num_batch 1024`): a 60K-token chunk of code takes 2–4 minutes the first time |
 | Follow-up turns | start in 1–2 s: Ollama reuses the cached prompt |
 | A real task | "explain X with file:line citations, then write and run a script" in about 2 minutes |
@@ -180,5 +213,5 @@ Apple Silicon numbers are not measured yet; please share yours.
 Some models (the Qwen3.6 family, for example) ship with a vision encoder that a coding agent doesn't
 use. `lcode setup` creates a text-only variant named `lcode-<key>` that reuses the downloaded
-weights, so it takes no extra disk space, and frees about 1 GB of GPU memory. On a 12 GB GPU that
-memory is what allows a larger prompt batch, which reads prompts ~1.8x faster.
+weights, so it takes no extra disk space, and frees about 1 GB of GPU memory for the context cache
+(and for a larger prompt batch, where it fits; see [tuning](configuration.md#tuning-for-speed-and-memory)).

{lcode_cli-0.1.1 → lcode_cli-0.2.0}/docs/quickstart.md RENAMED Viewed

@@ -12,7 +12,7 @@ lcode
 ```text
 ╭──────────────────────────────────────────────╮
-│ lcode v0.1.0 — local coding agent            │
+│ lcode v0.2.0 — local coding agent            │
 │                                              │
 │ model    lcode-qwen3.6-35b                   │
 │ context  256K tokens                         │
@@ -86,7 +86,8 @@ Read-only commands such as `ls`, `cat`, `grep` and `git status` run without aski
 - ++ctrl+c++ interrupts the model or a running command; you keep the conversation.
 - `/compact` summarizes a long conversation to free context (this also happens automatically at 85%).
-- `lcode -c` resumes the last session in the current directory.
+- `lcode -c` continues the last session in this folder; `/rename` names a session and `/resume`
+  picks one from a list.
 - `/help` lists everything else.
 Next: [everything lcode can do](usage.md), or [choosing models and context windows](models.md).

lcode-cli 0.1.1__tar.gz → 0.2.0__tar.gz

lcode-cli 0.1.1tar.gz → 0.2.0tar.gz