AI coding agent optimized for small LLMs (≤20B parameters)
SmallCode is a terminal-native coding agent designed from the ground up to extract useful work from local models (7B-20B) running on consumer hardware. While tools like OpenCode assume frontier models with 128k+ context and perfect tool calling, SmallCode compensates for the limitations of small models through intelligent architecture.
Why SmallCode?
| OpenCode | SmallCode | |
|---|---|---|
| Target | Frontier models (Claude, GPT-4) | 7B-20B local models |
| Context | Dumps everything | Budget-managed, summarized |
| Tool calling | Assumes reliable JSON | Forgiving multi-format parser |
| Planning | Single-shot | TODO-file decomposed steps |
| Editing | Full file write | Search-and-replace patch |
| Privacy | API calls to cloud | Fully local, no network needed |
Quick Start
# Install globally npm install -g smallcode # Or run directly with npx npx smallcode # Start in your project directory cd my-project smallcode
SmallCode includes BoneScript and budget-aware-mcp as dependencies — everything installs in one go.
Requirements
- Node.js 18+
- A local LLM server (LM Studio, Ollama, or any OpenAI-compatible endpoint)
Configuration
Create a .env file in your project root:
# Required SMALLCODE_MODEL=your-model-name SMALLCODE_BASE_URL=http://localhost:1234/v1 # Optional: escalation (auto-fallback to cloud on hard fail) # ANTHROPIC_API_KEY=sk-ant-... # OPENAI_API_KEY=sk-... # DEEPSEEK_API_KEY=sk-...
See .env.example for all options. Also supports smallcode.toml for backwards compatibility.
Architecture
SmallCode is built with a modular architecture:
bin/
├── smallcode.js Main entry point + agent loop
├── governor.js Tool scoring, verification, decompose
├── escalation.js Cloud model fallback (Claude/OpenAI)
├── commands.js TUI slash commands
├── tui.js Classic TUI renderer
└── bonescript_guide.js BoneScript syntax reference
src/
├── tui/fullscreen.js Fullscreen alternate-buffer TUI
├── plugins/loader.js Plugin system
├── plugins/skills.js Skill system
├── tools/builtin/ Tool implementations
├── governor/ Verifier, scorer, hard fail
└── core/ Config, events, session
Key Features
BoneScript Integration
For Node.js/TypeScript backends, SmallCode uses BoneScript — write ONE .bone file and compile it to a complete project (routes, auth, DB, events, migrations, SDK, admin panel, Docker, CI). Reduces 8-15 tool calls to 1-2, dramatically improving reliability with small models.
Model Escalation
When the local model hard fails after retry + decompose, SmallCode can optionally escalate to a stronger cloud model (Claude, OpenAI, DeepSeek). Fully opt-in — requires an API key. Session-limited to prevent runaway costs.
Escalation targets (cloud, used only on hard fail):
- Claude Sonnet 4.5 / 4.6, Haiku 4.5
- GPT-5.4 Mini / Nano
- DeepSeek V4 / V4 Pro / V4 Flash
Context Budget Engine
Never exceeds your model's context window. Automatically summarizes large files to signatures, evicts old messages, and tracks token usage in real time.
2-Stage Tool Routing
Halves the schema context overhead. Model picks a category (read/write/search/run/plan) first, then gets only relevant tool schemas. Critical for models with 8-16k context.
Forgiving Tool Call Parser
Small models produce messy output. SmallCode parses tool calls from JSON, YAML, XML, Hermes format, or plain text. Auto-repairs common mistakes (wrong param names, type mismatches).
TODO-Driven Planning
Complex tasks get decomposed into atomic steps. The model reads a TODO file each turn to know where it is. Each step is validated (lint/compile) before moving on.
Patch-First Editing
Search-and-replace as the primary edit primitive. Small models can't reliably reproduce entire files — they truncate, hallucinate, or drift. patch is safer and more context-efficient.
Early-Stop Detection
Detects repetition loops and runaway output. Saves tokens and time when a small model starts spinning.
Model Profiles
Per-model configuration: context length, tool format (native/hermes/json/xml/text), chat template, strengths/weaknesses. Auto-adapts prompting strategy.
Working Memory
Persistent scratchpad that survives across turns. Compensates for limited reasoning depth — the model can write notes to itself.
Commands
| Command | Description |
|---|---|
/quit, /q |
Exit SmallCode |
/clear |
Reset conversation |
/stats |
Show session statistics |
/memory |
Show working memory |
/plan |
Show current task plan |
/model |
Show/switch model |
/skill |
Manage reusable skills |
/plugin |
Install/manage plugins |
/sessions |
List/resume saved sessions |
/help |
Show all commands |
Tools
| Tool | Description |
|---|---|
bone_compile |
Compile .bone to full backend project |
bone_check |
Validate .bone file (type errors, constraints) |
list_projects |
List all indexed projects with stats |
graph_search |
Code graph symbol search |
explain_symbol |
Full symbol explanation (callers, callees) |
read_file |
Read file contents |
write_file |
Create/overwrite files |
patch |
Search-and-replace edit |
bash |
Run shell commands |
search |
Regex search (ripgrep) |
find_files |
Glob file search |
memory_load |
Load relevant project memory |
memory_remember |
Save knowledge to memory |
web_search |
Search the web via DuckDuckGo (requires SMALLCODE_WEB_BROWSE=true) |
web_fetch |
Fetch and extract text from a URL (requires SMALLCODE_WEB_BROWSE=true) |
Web Browsing
SmallCode includes Playwright with stealth mode for undetected web browsing. Disabled by default — enable for medium/large models (20B+) that can synthesize web context effectively:
# In your .env
SMALLCODE_WEB_BROWSE=trueWhen enabled, the model can search the web and fetch documentation during tasks. Uses headless Chromium with anti-detection to avoid CAPTCHAs and bot blocks. Falls back to simple HTTP fetch if Playwright isn't available.
License
MIT