[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-77269":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":15,"forks30d":15,"starsTrendScore":19,"compositeScore":20,"rankGlobal":9,"rankLanguage":9,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":24,"hasPages":22,"topics":25,"createdAt":9,"pushedAt":9,"updatedAt":26,"readmeContent":27,"aiSummary":28,"trendingCount":15,"starSnapshotCount":15,"syncStatus":29,"lastSyncTime":30,"discoverSource":31},77269,"smallcode","Doorman11991\u002Fsmallcode","Doorman11991","AI coding agent optimized for small LLMs. 87% benchmark with 4B-active model.",null,"JavaScript",1829,138,12,10,0,3,65,1519,27,90.43,"MIT License",false,"master",true,[],"2026-06-12 04:01:21","# SmallCode\n\n[简体中文](README_zh-CN.md) | [English](README.md)\n\n---\n\n[![npm](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002Fsmallcode)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fsmallcode)\n\n**AI coding agent optimized for small LLMs (≤20B parameters)**\n\nSmallCode 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.\n\n## Why SmallCode?\n\n| | OpenCode | SmallCode |\n|---|----------|-----------|\n| **Target** | Frontier models (Claude, GPT-5) | 7B-20B local models |\n| **Context** | Dumps everything | Budget-managed, summarized |\n| **Tool calling** | Assumes reliable JSON | Forgiving multi-format parser |\n| **Planning** | Single-shot | TODO-file decomposed steps |\n| **Editing** | Full file write | Search-and-replace patch |\n| **Privacy** | API calls to cloud | Fully local, no network needed |\n\n## Quick Start\n\n```bash\n# Install globally\nnpm install -g smallcode\n\n# Or run directly with npx\nnpx smallcode\n\n# Start in your project directory\ncd my-project\nsmallcode\n```\n\nSmallCode includes [BoneScript](https:\u002F\u002Fgithub.com\u002FDoorman11991\u002FBoneScript) and [budget-aware-mcp](https:\u002F\u002Fgithub.com\u002FDoorman11991\u002Fbudget-aware-mcp) as dependencies — everything installs in one go.\n\n### Requirements\n\n- Node.js 18+ (LTS recommended — 20.x or 22.x have prebuilt binaries for SQLite)\n- A local LLM server (LM Studio, Ollama, or any OpenAI-compatible endpoint)\n\n**Optional** (for code graph + FTS5 memory search):\n- `better-sqlite3` needs native compilation if prebuilt binaries aren't available for your Node version\n- Prebuilt binaries exist for Node LTS (20.x, 22.x) on Linux\u002FmacOS\u002FWindows. no build tools needed\n- If you're on a non-LTS Node (23+, 25+), you'll need:\n  - **Linux**: `python3`, `make`, `gcc`\u002F`g++` (`sudo apt install build-essential python3` or `pacman -S base-devel python`)\n  - **macOS**: Xcode Command Line Tools (`xcode-select --install`)\n  - **Windows**: Visual Studio Build Tools with \"Desktop development with C++\" workload, or `npm install -g windows-build-tools`\n- **If build fails, SmallCode still works** — it falls back to JSON-based memory automatically\n\n### Configuration\n\nCreate a `.env` file in your project root:\n\n```bash\n# Required\nSMALLCODE_MODEL=your-model-name\nSMALLCODE_BASE_URL=http:\u002F\u002Flocalhost:1234\u002Fv1\n\n# Optional: escalation (auto-fallback to cloud on hard fail)\n# ANTHROPIC_API_KEY=sk-ant-...\n# OPENAI_API_KEY=sk-...\n# DEEPSEEK_API_KEY=sk-...\n```\n\nSee `.env.example` for all options. Also supports `smallcode.toml` for backwards compatibility.\n\n## Architecture\n\nSmallCode is built with a modular architecture:\n\n```\nbin\u002F\n├── smallcode.js        Entry point, agent loop, TUI orchestration (1570 lines)\n├── config.js           Config loading, endpoint detection, auth headers\n├── executor.js         Tool execution (all 18 tools)\n├── tools.js            Tool definitions + 2-stage routing\n├── mcp_bridge.js       Built-in code graph MCP communication\n├── model_client.js     LLM API calls, streaming, validation\n├── governor.js         Tool scoring, verification, decompose\n├── escalation.js       Cloud model fallback (Claude\u002FOpenAI\u002FDeepSeek)\n├── commands.js         TUI slash commands\n├── tui.js              Classic TUI renderer\n└── bonescript_guide.js BoneScript syntax reference\n\nsrc\u002F\n├── api\u002Findex.js        Programmatic API (require('smallcode'))\n├── tui\u002Ffullscreen.js   Fullscreen alternate-buffer TUI\n├── plugins\u002Floader.js   Plugin system\n├── plugins\u002Fskills.js   Skill system\n├── tools\u002F              Tool routing, MCP client, validators\n├── governor\u002F           Early-stop detection, verifier, tool scorer\n├── model\u002F              Multi-model profiles + routing\n└── session\u002F            Persistence, undo, sharing, references\n```\n\n## Key Features\n\n### MarrowScript Cognition Layer\nSmallCode's intelligence is declared in [MarrowScript](https:\u002F\u002Fgithub.com\u002FDoorman11991\u002FMarrowScript) and compiled to a production runtime. One 50-line `.marrow` declaration generates 1400+ lines of TypeScript with caching, retry, validation, traces, and budget enforcement — all for free.\n\n```marrow\nprompt classify_task_type(user_message: string) {\n  model: TinyClassifier\n  timeout: 3s\n  cache: { key: hash(user_message), ttl: 10m }\n  retry: { max_attempts: 2, backoff: fixed, interval: 100ms }\n  constraints: [output in [\"coding\", \"editing\", \"search\", ...]]\n}\n```\n\nThe compiled cognition layer provides:\n- **Prompt caching** — 0ms on cache hit, content-hash keys with TTL\n- **Structured traces** — trace_id\u002Fspan_id for every LLM call (enable with `SMALLCODE_COGNITION_LOG=stderr`)\n- **Tier-based routing** — trivial tasks → tiny model, complex tasks → medium model\n- **Token budgets** — per-cost-class enforcement, never overspend\n- **Validation + repair** — schema checks with auto-retry on malformed output\n\n### BoneScript Integration\nFor Node.js\u002FTypeScript 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.\n\n### Model Escalation\nWhen 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.\n\n**Escalation targets** (cloud, used only on hard fail):\n- Claude Sonnet 4.5 \u002F 4.6, Haiku 4.5\n- GPT-5.4 Mini \u002F Nano\n- DeepSeek V4 \u002F V4 Pro \u002F V4 Flash\n\n### Context Budget Engine\nNever exceeds your model's context window. Tool results capped at 4k chars, mid-turn eviction drops old results when context grows too large, and semantic compression summarizes history instead of dropping it.\n\n### 2-Stage Tool Routing\nHalves the schema context overhead. Model picks a category (read\u002Fwrite\u002Fsearch\u002Frun\u002Fplan) first, then gets only relevant tool schemas. Critical for models with 8-16k context.\n\n### Early-Stop Detection\nDetects repetition loops, patch spirals (stuck on corrupted file → forces rewrite), and greeting regression (model lost context → re-injects task). Saves tokens and time.\n\n### Forgiving Tool Call Parser\nSmall 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).\n\n### Patch-First Editing\nSearch-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.\n\n### TODO-Driven Planning\nComplex tasks get decomposed into atomic steps. The model reads a TODO file each turn to know where it is. Each step is validated (lint\u002Fcompile) before moving on.\n\n### Model Profiles\nPer-model configuration: context length, tool format (native\u002Fhermes\u002Fjson\u002Fxml\u002Ftext), chat template, strengths\u002Fweaknesses. Auto-adapts prompting strategy.\n\n### Working Memory\nPersistent scratchpad that survives across turns. Compensates for limited reasoning depth — the model can write notes to itself.\n\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `\u002Fquit`, `\u002Fq` | Exit SmallCode |\n| `\u002Fclear` | Reset conversation |\n| `\u002Fstats` | Show session statistics |\n| `\u002Ftokens` | Detailed token usage report |\n| `\u002Fbudget` | Context window budget + visual bar |\n| `\u002Ftrace` | List\u002Fshow\u002Fexport execution traces |\n| `\u002Feval` | Run prompt evaluation suites |\n| `\u002Fmemory` | Show working memory |\n| `\u002Fplan` | Show current task plan |\n| `\u002Fmodel` | Show\u002Fswitch model |\n| `\u002Fprofile` | Show detected model profile + routing mode |\n| `\u002Fcognition` | Show MarrowScript cognition layer status |\n| `\u002Fmcp` | Show connected external MCP servers |\n| `\u002Fskill` | Manage reusable skills |\n| `\u002Fplugin` | Install\u002Fmanage plugins |\n| `\u002Fsessions` | List\u002Fresume saved sessions |\n| `\u002Fhelp` | Show all commands |\n\n## Observability\n\nSmallCode tracks token usage and execution traces automatically:\n\n- **Token Monitor** — Every LLM call records prompt\u002Fcompletion tokens. View with `\u002Ftokens`.\n- **Context Budget** — Visual indicator of context window usage. View with `\u002Fbudget`.\n- **Execution Traces** — Every agent turn is recorded to `.smallcode\u002Ftraces\u002F`. View with `\u002Ftrace list`.\n- **Trace-to-Test** — Generate regression tests from traces: `\u002Ftrace test \u003Cid>`.\n- **Prompt Evaluations** — Measure classifier accuracy and tool selection: `\u002Feval classify_accuracy`.\n\n```bash\n# Run evaluations from CLI\nsmallcode --eval classify_accuracy\nsmallcode --eval tool_selection\n```\n\n## Programmatic API\n\nUse SmallCode as a library in your own tools, CI pipelines, or TypeScript frameworks:\n\n```javascript\nconst { SmallCode } = require('smallcode');\n\nconst agent = new SmallCode({\n  model: 'gemma-4-e4b',\n  baseUrl: 'http:\u002F\u002Flocalhost:1234\u002Fv1',\n});\n\n\u002F\u002F Run a task\nconst result = await agent.run(\"create hello.py that prints hello world\");\nconsole.log(result.filesCreated);  \u002F\u002F ['hello.py']\nconsole.log(result.toolCalls.length);  \u002F\u002F 1\nconsole.log(result.success);  \u002F\u002F true\n\n\u002F\u002F Subscribe to events\nagent.on('tool_start', ({ name, args }) => console.log(`Using: ${name}`));\nagent.on('tool_end', ({ name, ms }) => console.log(`Done: ${name} (${ms}ms)`));\nagent.on('error', (err) => console.error(err));\n```\n\nReturns a structured `RunResult` with: response text, tool call records, files created\u002Fedited, token usage, duration, and success status.\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `bone_compile` | Compile .bone to full backend project |\n| `bone_check` | Validate .bone file (type errors, constraints) |\n| `list_projects` | List all indexed projects with stats |\n| `graph_search` | Code graph symbol search |\n| `explain_symbol` | Full symbol explanation (callers, callees) |\n| `read_file` | Read file contents |\n| `write_file` | Create\u002Foverwrite files |\n| `patch` | Search-and-replace edit |\n| `bash` | Run shell commands |\n| `search` | Regex search (ripgrep) |\n| `find_files` | Glob file search |\n| `memory_load` | Load relevant project memory |\n| `memory_remember` | Save knowledge to memory |\n| `web_search` | Search the web via DuckDuckGo (requires `SMALLCODE_WEB_BROWSE=true`) |\n| `web_fetch` | Fetch and extract text from a URL (requires `SMALLCODE_WEB_BROWSE=true`) |\n\n### Web Browsing\n\nSmallCode includes Playwright with stealth mode for undetected web browsing. Disabled by default — enable for medium\u002Flarge models (20B+) that can synthesize web context effectively:\n\n```bash\n# In your .env\nSMALLCODE_WEB_BROWSE=true\n```\n\nWhen 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.\n\n## License\n\nMIT\n","SmallCode 是一个专为小型本地语言模型（参数量≤20B）优化的AI编码助手。该项目通过智能架构弥补了小模型在上下文管理、工具调用等方面的不足，实现了高效的代码生成与编辑功能，支持7B至20B参数范围内的本地模型运行于普通消费级硬件上。其核心特性包括预算控制下的上下文摘要、容错多格式解析器、基于TODO文件的任务分解等。适用于开发者希望利用本地部署的小型AI模型进行辅助编程而不依赖云服务的场景，特别适合追求数据隐私和离线工作的用户。使用JavaScript编写，并采用MIT许可证开放源码。",2,"2026-06-11 03:55:15","CREATED_QUERY"]