How it works¶
lcode is a small Python program (about 2,000 lines) around one idea: let a local model call tools in a loop until the task is done.
flowchart LR
U[You] -->|request| A[lcode agent loop]
A -->|messages + tool schemas| O[Ollama<br/>local model]
O -->|text or tool calls| A
A -->|tool call| T[Tools<br/>read · edit · grep · bash …]
T -->|result| A
A -->|diffs, commands| P{Permission<br/>prompt}
P -->|approve / deny + reason| A
A -->|answer| U
The agent loop¶
- Your message goes to the model along with a system prompt (environment, repository layout,
AGENTS.md, the index of memory notes) and the JSON schemas of the tools. - The response streams back. Reasoning shows as a spinner (or text with
--show-thinking); the answer is rendered as markdown, block by block. - If the model called tools, lcode runs them, asking for permission where needed, and appends the results to the conversation.
- Back to step 2 until the model answers without calling a tool (with a safety cap of 150 steps).
All tools return text, and failures come back to the model as Error: … messages rather than
crashing the session, so the model can correct itself (for example re-read a file when an edit
didn't match).
Checking its own work¶
Small models like to call work done after a syntax check. The system prompt tells the model what counts as checked:
- run what it changed the way it will be used;
- reproduce a bug before fixing it, then show it's gone;
- check what it can't see (a GUI, a web page, a layout) without a screen: Qt's
offscreenplatform, a headless browser, or a script that prints sizes or renders an image it then looks at; - never mark a task done or call something tested without having run it, and tell you what to look at when it couldn't check.
When the model repeats itself¶
Small models sometimes fall into a loop: they make a call, get a result, and make the very same call again, and again. lcode counts, within a request, the calls that repeat an earlier one exactly: the same tool, the same arguments and the same result.
- At the third one (the second, when the call failed) the result gets a note: the call returned the same thing several times, so the model should use what it got, try something different, or tell you what's blocking it.
- Two more, and lcode ends the request with
Stopped: the model kept making the same call with the same result. The JSON output's status isloop.
A result that changes isn't a repeat, so a test that's run again after a fix, or a background job
that's checked while it runs, never adds up. Timings don't count as a change: 75 passed in 0.12s
and then in 0.14s is the same result. A call that may have changed something, like an edit or
a shell command that isn't read-only, starts the count again for the other calls: checking the build
after each edit is fine. Change the threshold with lcode config set repeat_limit 5, or turn it off
with 0 (that also turns off the checks for unreachable sites and for thinking in circles, below).
When a site can't be reached¶
A download that fails however its address is written usually means this machine can't reach the site: a firewall, a proxy, a regional block, or no internet. No address the model tries will fix that, and every attempt differs, so the repeat count above never fires. lcode keeps track, per site, of the calls that failed to reach it (an HTTP error, a name that doesn't resolve, a refused or timed-out connection) and of the ones that got an answer.
- When three different calls failed for a site and none worked, the result gets a note: check one address on that site that must exist, and if that fails too, stop and tell you what fails and what you could do (another network or a VPN, a proxy, a mirror, or running that step somewhere else, such as CI).
- Two more, and lcode ends the request with
Stopped: every request to dl.google.com failed (5 calls: HTTP 404)…. The JSON output's status isblocked.
A site that answered once in the request is never counted as out of reach, so a wrong address on a working site doesn't add up. Local addresses (localhost, private networks, names without a dot) aren't tracked.
When a reply goes nowhere¶
Small models sometimes think in circles: a few paragraphs, over and over, until the context is full.
That takes minutes behind the spinner and ends without an answer. lcode watches the thinking as it
streams, and when its sentences keep repeating, it stops the model, drops that reply and asks for a
short one: the next tool call, or what's blocking it. With Ollama, that reply runs with thinking off,
so the model acts instead of starting the same deliberation over. The dropped reply is saved, and the
message says where, so you can read what went round in circles. An empty reply, or one that filled the
context before it said anything, gets the same second chance. When two replies in a row go nowhere, or
four in one request, lcode stops it (status loop), offering the
stronger model first when one is set. An answer the context
cut off midway is kept, with a warning to /compact or use a larger /context.
A reply can also think for a long time without repeating itself: weighing one option after another,
never trying any. When a reply has thought for 7,000 tokens (think_budget) and hasn't yet written
anything or called a tool, lcode stops it the same way. The model gets back the last part of its
thinking, so it can act on where its reasoning got to, and the next reply runs with thinking off.
Once the model acts, thinking is back on. On the dev slice of the
public benchmarks, about 1 reply in 100 thought that long. They came from 42
of the 110 attempts that failed and 2 of the 102 that passed. Such a reply doesn't count towards the
four per request, so a long task with several hard steps carries on, but a reply that goes nowhere
right after one stops the request as before. Change the budget with
lcode config set think_budget 12000, or turn it off with 0.
Subagents¶
The agent tool starts a subagent: another agent loop with its own conversation, the
same model and context window (so Ollama doesn't reload anything), the session's permissions,
sandbox and checkpoints, and a filtered set of tools. Only its final report goes back into the main
conversation. Several subagents run in threads when max_parallel_agents allows; their permission
prompts are queued and asked in the main thread. Workers that edit files at the same time each work
in a temporary git worktree, and their changes come back as a diff.
Context management¶
Ollama keeps the processed conversation in its KV cache, so each turn only processes the new tokens.
lcode tracks how full the window is from Ollama's token counts. It makes room when the window is
85% full, or when the conversation reaches 64K tokens (compact_at), whichever comes first.
Small models lose track in long contexts well before a large window is full: in one long session,
Qwen3.6 35B started repeating itself and overlooking what it had read once the conversation passed
about 75K tokens. Most of a long session's
context is old tool output, so:
- lcode removes old tool output first. File contents, command output and search results from
before your last two requests become one-line notes that say what was there, such as
[lcode: read src/app.py earlier; its content was removed …. Read it again before answering anything about it.]. An earlier copy of a file that was read again later goes too, even in recent requests. Subagent reports, skill instructions and the approved plan stay. The files whose only copy went are also named next to the request the model is working on, since models tend to overlook a note deep in the conversation and answer from memory instead of reading the file again. - If that brings the conversation well under the limit (70% of the window, or about 53K
tokens with
compact_at), the work simply continues: nothing is summarized, and the conversation itself stays word for word. If it's not, lcode also removes the tool output of your previous request, keeping only the latest one's. (lcode config set prune falseskips this step.) - Otherwise lcode summarizes. It asks whether anything is worth remembering, since the summary leaves details out, then has the model write a summary of the conversation (goals, findings, files changed, next steps) and continues from it. Your latest requests (up to eight) are kept word for word under the summary, so the goal isn't lost in the retelling.
The task sheet. Next to the summary, and next to your request when old tool output is removed, lcode pins a short sheet, so the state of the work survives:
- the plan (the model's todo list);
- the notes the model keeps with it (decisions and why, findings, open questions);
- the files changed in the session;
- the last check.
It's saved with the session, so lcode -c brings it back, and /status shows it to you.
lcode config set compact_at 128k moves the ceiling, and 0 turns it off, leaving only the 85%
rule. /context shows where the current session makes room.
Long tool output (over 30,000 characters) keeps its beginning, its end and the lines in between
that look like errors. The full output is saved under ~/.local/state/lcode/outputs/ (for a week)
and the model is told where, so it can read the rest if it needs to. /context shows what's using
the window, by category: the system prompt and its parts, tool definitions, your messages, attached
files, the model's replies and each tool's results.
Memory sizing¶
lcode setup and lcode models estimate memory as weights + KV cache per token × context +
overhead. The per-token KV cost comes from each model's GGUF metadata (attention layers, KV heads
and head sizes); hybrid architectures such as Qwen3.5/3.6 (linear attention in 3 of 4 layers) and
Nemotron (Mamba layers) keep a cache in only a few layers, which is why they can offer 256K–1M
tokens on consumer hardware. The budget is GPU memory plus spare RAM on Linux, and the GPU share
of unified memory on Apple Silicon. See Models & context windows.
That budget says whether a model loads, not whether it keeps its speed. An MoE model's experts stay mapped
from its file, and Ollama's server keeps a prompt cache of up to 8 GB in RAM. When they don't fit in the RAM
that's available, Linux keeps dropping the experts and reading them back from disk, at a third of the speed.
lcode doctor and lcode setup compare the two with what's available now, and a session says so when replies
slow down that far. See RAM in a long session.
Two lessons from tuning the default model on a 12 GB GPU shaped the defaults:
- Vision projectors cost ~1 GB of VRAM that Ollama under-counts on small GPUs, causing
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. 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; besides
the Ollama server you configure, it only contacts the web when the model searches or fetches a page
(see Web search). See the security policy.
Code map¶
| Module | Responsibility |
|---|---|
cli.py, cli_args.py, doctor.py |
Entry point, subcommands, model and context resolution; the options; lcode doctor |
repl.py |
Prompt, key bindings, status bar, and slash commands, with the model, media, memory and checkpoint, and session commands in repl_models.py, repl_media.py, repl_history.py and repl_sessions.py |
agent.py |
The tool loop. Agent's state is in agent_base.py, and its system prompt and tools, model calls, context window, sessions and checks in agent_prompt.py, agent_model.py, agent_context.py, agent_sessions.py and agent_checks.py |
tools.py |
The tools and running them, with the schemas in tool_schemas.py, what they share in tool_helpers.py and tools_base.py, and the file and shell tools in tools_edit.py and tools_shell.py |
permissions.py |
Approval prompts and the read-only allowlist |
servers/ |
The MCP servers lcode ships for services without one: Encord, Valohai |
mcp/ |
MCP client: stdio and HTTP transports, OAuth sign-in, server settings, the catalog, lcode mcp |
bench.py |
lcode bench: running the tasks and the reports; the tasks are in bench_quick.py and the other bench_*.py, and what their checks share in bench_checks.py |
vision.py |
Looking at images with a model that can see |
subagents.py |
Subagents: agent types, running them (also in parallel), worktrees for workers |
hooks.py |
Hooks on lcode's events, and allow and deny rules for permissions |
repomap.py, codesearch.py |
The repository map, and semantic code search with an embedding model |
lsp.py |
Language servers: the lsp tool and errors after edits |
extensions.py |
Custom commands and skills, and approving a repository's own |
frontmatter.py |
The --- headers of notes, agents, commands and skills |
planning.py |
Plan mode: what it allows, presenting a plan and approving it |
memory.py |
Notes that carry over between sessions, and the optional end-of-session check |
sessions.py, repoid.py |
Saved conversations: listing them for this folder and elsewhere; which repository a folder is in, by its first commit |
sandbox.py |
The optional container for shell commands |
checkpoints.py |
Snapshots before the model changes files, for /undo and /rewind |
catalog.py, models.toml |
Model catalog and memory estimates |
hardware.py |
NVIDIA / Apple Silicon detection, and the RAM available now |
ollama.py |
Ollama HTTP client |
config.py |
Settings file and environment variables |
traces.py, trace_view.py, trace_export.py |
Recording requests; listing and showing traces; exporting them with secrets masked |
media.py, media_video.py, clips.py |
Image and video mode's jobs in ComfyUI; video jobs and long clips; video files |
screenshots.py, screenshots_web.py, qt_hook.py |
The screenshot tool: programs, web pages, and the hook it puts into Qt programs |