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 · your code stays local

Documentation · Install · Models · Contributing

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, and when it needs current information it can search the web.

Features

• A real agent. Reads, searches, edits and runs commands in a loop, checks its own work, and plans multi-step tasks with a visible todo list.
• Long context. 256K tokens with the default model (1M with Nemotron). You choose the window.
• Hardware-aware. Detects your NVIDIA GPU or Apple Silicon Mac and picks the best model and the largest context that fits: lcode setup does it in one step. lcode bench compares models on real coding tasks on your machine.
• 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.
• Undo. lcode saves a checkpoint before the model changes files; /undo takes back the last request's edits, new files and shell-command changes, without touching your git history.
• 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

Ubuntu / Linux (NVIDIA GPU recommended) and macOS on Apple Silicon (M1–M4):

curl -fsSL https://nasser1941.github.io/lcode/install.sh | bash

The installer sets up lcode with its own Python via uv, checks for Ollama (0.30+) and runs lcode setup, which picks a model for your hardware and downloads it. Prefer manual steps? lcode is on PyPI as lcode-cli:

uv tool install lcode-cli      # or: pipx install lcode-cli
lcode setup

See the installation guide for details.

Quickstart

cd ~/code/your-project
lcode

❯ /init                                   # study the repo and write AGENTS.md for future sessions
❯ How does authentication work here? Cite files.
❯ Write scripts/dedupe.py that removes duplicate rows from @data/users.csv by email, and run it
❯ The tests in tests/test_parser.py fail. Find out why and fix it.

Models

What lcode setup picks for common machines:

At 256K context the default model generates 50–55 tokens/s on an RTX 4080 Laptop GPU (12 GB) and 45 tokens/s on an M4 Pro Mac with 48 GB. See Models & context windows for memory estimates and tuning.

How it works

lcode sends your request, the repository layout and a set of tool definitions to the model; runs the tools the model calls (read, edit, grep, glob, bash, todo); feeds the results back; and repeats until the model answers. It sizes models to your memory from each model's KV-cache footprint, uses text-only model variants to free GPU memory, and summarizes the conversation when the context window fills up. Details: How it works.

Roadmap

See the pinned Roadmap issue. Next up:

• MCP tool servers
• Homebrew formula and an optional sandbox for shell commands
• More models in the catalog, and test reports from your hardware (report one)

Contributing

Contributions are welcome: bug reports, model test results, docs and code. See CONTRIBUTING.md. Please follow the code of conduct, and report security issues privately as described in SECURITY.md.

Acknowledgements

lcode stands on Ollama and llama.cpp, the open-weight models from Qwen, Poolside, NVIDIA and OpenAI, Rich and prompt_toolkit.

License

MIT © 2026 Naser Derakhshan