SmallCode: A Terminal Coding Agent Built Around the Limits of 8B-35B Local Models
AI coding agent optimized for small LLMs. 87% benchmark with 4B-active model.
At a glance
- What is it?
- SmallCode is an MIT-licensed JavaScript coding agent that trades frontier-model assumptions for context budgeting, forgiving tool-call parsing and patch-based editing. It targets people running 8B-35B models on their own hardware, and its own README warns that models at or below 4B will lose context across turns.
- Who is it for?
- Adopt SmallCode if you already run an 8B-35B model under LM Studio, llama.cpp or Ollama and want an agent that assumes unreliable tool calling and a small context window. Do not adopt it if you are on a frontier API model (its own comparison says those are better served by tools built for them) or on hardware that cannot hold a model in that size band.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 34 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The constraint SmallCode Is Designed Around
Most terminal coding agents are written for models with 128k or more tokens of context and dependable JSON tool calling. The README states this directly, naming OpenCode as the example: it "assume[s] frontier models with 128k+ context and perfect tool calling." SmallCode inverts the assumption. Its stated target is local models in the 8B-35B parameter range running on consumer hardware, and every architectural choice in the README follows from what those models cannot do.
The audience is therefore narrow and specific. You need a machine that can serve an 8B-35B model, a local inference server that speaks the OpenAI-compatible API, and a willingness to work in a terminal. The README is equally direct about who is excluded. Models at or below 4B "struggle with multi-step tool use and lose context across turns," and models above 35B "don't need SmallCode's adaptations" because frontier-oriented tools already fit them. That is an unusually honest scoping statement for a project README. It also means the 87% benchmark figure in the repository description should be read as a claim about one model configuration, not a general property of the tool. The README does not break that number down, so there is no way to check which benchmark, which model, or which task set produced it.
Context Budgeting, TODO Decomposition and Patch Editing
The README's comparison table lists five mechanisms. Context is "budget-managed, summarized" rather than dumped wholesale. Tool calling goes through a "forgiving multi-format parser" instead of assuming reliable JSON. Planning is decomposed into steps held in a TODO file rather than produced in a single shot. Editing is applied as search-and-replace patches rather than full file writes. And the whole loop is local, with no network required.
Those choices interlock. A small context window makes full-file rewrites expensive, so patch edits keep the token cost of a change proportional to the change itself. A model that emits malformed or partial tool calls needs a parser that recovers rather than aborts, otherwise a single bad turn ends the session. A model that cannot hold a long plan in context needs the plan externalized to a file it can re-read. The README does not describe the summarization policy, the parser's recovery rules, or how the TODO file is structured, so the internals of each mechanism are not verifiable from the supplied material. What is verifiable is that the design treats small-model failure modes as the normal case rather than the exception.
The privacy claim is the one that follows most cleanly from the architecture. Local inference means prompts and file contents do not leave the machine. That holds only while you stay local: the optional escalation keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, DEEPSEEK_API_KEY) exist precisely so that a hard failure can be handed to a cloud model, and the README describes that as "auto-fallback to cloud on hard fail." If you set one of those keys, the local-only property is conditional, not absolute.
Installing SmallCode and Pointing It at a Model
The README gives three installation paths. The npm route is `npm install -g smallcode`, or `npx smallcode` to run without installing. Prebuilt tarballs for Windows, macOS and Linux bundle Node.js and native addons, installed with `bash <(curl -fsSL https://raw.githubusercontent.com/Doorman11991/smallcode/master/install.sh)` on Linux and macOS, or an `iwr ... | iex` one-liner on Windows; the script extracts to `~/.smallcode` and edits PATH. From a fresh checkout the sequence is `npm install`, then `node bin/smallcode.js`.
Configuration lives in a `.env` file at the project root. Two keys are required: `SMALLCODE_MODEL` and `SMALLCODE_BASE_URL`, the latter defaulting in the examples to `http://localhost:1234/v1`, which is the usual LM Studio port. `SMALLCODE_MODEL_TIMEOUT` sets the per-turn response timeout in seconds and defaults to 300. The README recommends raising it for CPU-only llama.cpp servers, and notes the same value can be set in `smallcode.toml` under `[model]` as `timeout = <seconds>`. The failure message when a turn overruns is `timeout: no response after <N>s`, which tells you the fix is the timeout key rather than the model.
There are two UIs. The default is a fullscreen TUI that enables raw mode, mouse tracking and bracketed paste; `--classic` gives a readline fallback for terminals where the fullscreen mode misbehaves. The README states the terminal is restored on exit, including after `Ctrl+Z` and on crash, and that a `kill -9` may leave escape sequences echoing, in which case `reset` fixes the shell. The RAG harness is separate: `npm run rag:index` builds a local GitHub corpus, `--preset broad` widens it, and `smallcode-rag-index` is the installed equivalent. Custom corpora go in `.smallcode/rag/repos.json` with `preset`, `repos` and chunking limits.
Native SQLite, Optional Dependencies and the Node Version Trap
The code graph and FTS5 memory search depend on better-sqlite3, which needs native compilation unless a prebuilt binary exists for your Node version. The README is explicit that prebuilds cover Node LTS (20.x and 22.x) on Linux, macOS and Windows, and that non-LTS versions such as 23.x and 25.x require a toolchain: `build-essential` and `python3` on Linux, `xcode-select --install` on macOS, Visual Studio Build Tools with the C++ workload on Windows.
The important detail is the fallback. The README states that if the build fails, SmallCode still works and falls back to JSON-based memory automatically. That makes the native dependency an optimization rather than a hard requirement, and it gives you a clean escape hatch: `npm install -g smallcode --omit=optional` skips it entirely, at the cost of FTS5 memory search. The README also addresses a `prebuild-install@7.1.3: No longer maintained` warning, attributing it to the transitive chain budget-aware-mcp to better-sqlite3 to prebuild-install, and states plainly that no newer version exists to bump to and that the warning does not affect installation. That level of specificity about a cosmetic npm warning is a good sign for how the rest of the install path is documented.
The dependency layout is worth noting on its own. SmallCode pulls in BoneScript and budget-aware-mcp as dependencies, both from the same author. That keeps the install to one command, but it also means the project's behavior is partly defined by two other repositories rather than by this one.
Where SmallCode Is the Wrong Tool
The clearest limitation is one the README states itself: models at or below 4B parameters are out of scope. If your hardware tops out at a 3B or 4B model, SmallCode's adaptations do not rescue multi-step tool use, and the README says so rather than pretending otherwise. Similarly, if you already call a frontier model, the README concedes that such models "don't need SmallCode's adaptations and are better served by tools designed for frontier models." The tool is not positioned as a universal improvement over OpenCode; it is positioned as a different point on the same curve.
The second constraint is latency. A 300-second default per-turn timeout is generous by cloud standards and still not always enough: the README calls out CPU-only llama.cpp servers that need more than five minutes per turn, which is why `SMALLCODE_MODEL_TIMEOUT` exists and why the example sets it to 1800. If your workflow assumes sub-minute turns, a local 8B-35B model on consumer hardware will not deliver them, and no amount of context budgeting changes that. The timeout key manages the symptom; it does not remove the wait.
The third is the escalation path itself. Auto-fallback to cloud on hard fail is convenient, but it means the local-only privacy property is a function of your `.env`, not of the tool. Anyone who sets an API key for reliability has quietly reintroduced the network dependency SmallCode was built to avoid. The README does not describe what counts as a "hard fail" for escalation purposes, so the trigger condition is not verifiable from the supplied material.
SmallCode Versus OpenCode: Two Different Bets About the Model
The natural alternative is OpenCode, which SmallCode's own README names as the contrast case. The difference is not a feature list; it is a bet about what the model underneath can be trusted to do. OpenCode assumes a large context window and reliable structured tool calls, so it can send more context and expect a well-formed response. SmallCode assumes neither, so it spends engineering effort on budgeting, summarizing, parsing leniently and decomposing plans into a TODO file the model can re-read.
That trade has a cost in the other direction. A forgiving multi-format parser and a summarized context are compensations, and compensations can lose information that a capable model would have used correctly. On a 70B or frontier model, SmallCode's adaptations are overhead: extra machinery between the model and the task. On an 8B model, the same machinery is what makes the tool usable at all. Choosing between the two is therefore a question about your model, not about which project is better maintained.
A second axis is where inference happens. OpenCode's comparison row lists API calls to cloud against SmallCode's fully local operation. That is accurate as a default, but it is not a hard architectural boundary on either side, since SmallCode ships optional cloud escalation keys. The real distinction is which mode is the default and which is the fallback.
Licence, Upgrade Cost and What the Release History Suggests
SmallCode is MIT licensed. That permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. It is a permissive licence with no copyleft obligation, so embedding SmallCode in a proprietary internal toolchain does not by itself require publishing your source. This is a description of the licence text, not legal advice; if the tool becomes part of a product you ship, have counsel review the notices you are actually carrying, including those of the bundled BoneScript and budget-aware-mcp dependencies.
The release cadence visible in the supplied data is tight: v1.5.0 on 2026-05-30, v1.5.2 the next day, v1.6.0 on 2026-05-31, with the last repository push on 2026-08-12. Three releases in two days followed by roughly two and a half months of no tagged release suggests bursts of work around specific fixes rather than a steady train. For an operator that means two practical things. First, pin a version rather than tracking the default branch, since the gap between tags and pushes can be wide. Second, expect the upgrade cost to concentrate in the native dependency: a Node version change can move you from a prebuilt better-sqlite3 binary to a source build, which is the difference between a one-command upgrade and installing a C++ toolchain. Checking `node --version` against the LTS line before upgrading is the cheapest way to avoid that surprise. The README's own fallback to JSON memory means a failed native rebuild degrades the tool rather than breaking it, which softens the risk but also means a silent loss of FTS5 search if you do not check.
Editorial conclusion
Adopt SmallCode if you already run an 8B-35B model under LM Studio, llama.cpp or Ollama and want an agent that assumes unreliable tool calling and a small context window. Do not adopt it if you are on a frontier API model (its own comparison says those are better served by tools built for them) or on hardware that cannot hold a model in that size band. Before committing, verify three things on your own machine: that your Node version has a better-sqlite3 prebuilt binary, that your model server answers at SMALLCODE_BASE_URL, and that a single turn finishes inside your SMALLCODE_MODEL_TIMEOUT.
Community notes