### Quick Start from GitHub Checkout

Source: https://github.com/doorman11991/smallcode/blob/master/README.md

Clone the repository, install dependencies, configure environment variables for your local model, and run SmallCode directly from the checkout.

```bash
cd smallcode
npm install

# Start your local model server first (LM Studio, llama.cpp, Ollama, etc.)
cat > .env <<'EOF'
SMALLCODE_MODEL=your-local-model-name
SMALLCODE_BASE_URL=http://localhost:1234/v1
EOF

node bin/smallcode.js
```

--------------------------------

### Install and Run SmallCode from Checkout

Source: https://github.com/doorman11991/smallcode/blob/master/docs/rag-harness.md

Install dependencies and run the SmallCode UI directly from a fresh GitHub clone. This is the initial setup for development.

```bash
cd smallcode
npm install
node bin/smallcode.js --help
```

--------------------------------

### Install SmallCode on Windows

Source: https://github.com/doorman11991/smallcode/blob/master/README.md

Install SmallCode on Windows using a one-line PowerShell command that downloads and executes an install script.

```powershell
iwr -Uri https://raw.githubusercontent.com/Doorman11991/smallcode/master/install.ps1 -UseBasicParsing | iex
```

--------------------------------

### Run SmallCode with Launch Modes

Source: https://github.com/doorman11991/smallcode/blob/master/docs/rag-harness.md

Examples of launching the SmallCode UI with different modes and options. These include alternative interfaces, one-shot prompts, and non-interactive execution.

```bash
smallcode --classic                    # readline UI instead of fullscreen UI
```

```bash
smallcode -P "fix the parser bug"      # one-shot prompt
```

```bash
smallcode --non-interactive "refactor" # stdin/script friendly mode
```

```bash
smallcode --resume                     # continue previous session
```

--------------------------------

### Install SmallCode on Linux/macOS

Source: https://github.com/doorman11991/smallcode/blob/master/README.md

Install SmallCode on Linux or macOS using a one-line curl command that downloads and executes an install script.

```bash
bash <(curl -fsSL https://raw.githubusercontent.com/Doorman11991/smallcode/master/install.sh)
```

--------------------------------

### Start SmallCode UI

Source: https://github.com/doorman11991/smallcode/blob/master/docs/rag-harness.md

Launch the SmallCode terminal UI from the project directory. This command assumes you are in the project's root.

```bash
node bin/smallcode.js
```

--------------------------------

### Install SmallCode Globally

Source: https://github.com/doorman11991/smallcode/blob/master/README.md

Install the smallcode package globally using npm for command-line access. Alternatively, use npx to run it without global installation.

```bash
npm install -g smallcode
```

```bash
npx smallcode
```

--------------------------------

### Run SmallCode with Classic UI

Source: https://github.com/doorman11991/smallcode/blob/master/README.md

Start SmallCode using the classic readline-based UI instead of the fullscreen TUI, useful if the fullscreen UI has display issues.

```bash
node bin/smallcode.js --classic
```

--------------------------------

### Start SmallCode UI with Local RAG Index

Source: https://github.com/doorman11991/smallcode/blob/master/docs/rag-harness.md

Run this command to start the SmallCode UI after the local RAG index (`.smallcode/rag/index.json`) has been created. This enables SmallCode to use the local index for code retrieval.

```bash
smallcode
```

--------------------------------

### Example Active Plan Format

Source: https://github.com/doorman11991/smallcode/blob/master/ARCHITECTURE.md

This is the format used to display the active plan for multi-step tasks. It shows the current step and the overall progress.

```text
ACTIVE PLAN (step 3 of 5):
✓ 1. Read the existing auth module
✓ 2. Identify the JWT validation function
→ 3. Add the refresh token handler
  4. Update the route middleware
  5. Run tests
```

--------------------------------

### Install Web Browsing Dependencies

Source: https://github.com/doorman11991/smallcode/blob/master/README.md

Install the necessary Playwright and Puppeteer packages, and download the Chromium browser for web browsing functionality.

```bash
npm install -g playwright-extra puppeteer-extra-plugin-stealth
npx playwright install chromium
```

--------------------------------

### Handle Startup Errors Gracefully

Source: https://github.com/doorman11991/smallcode/blob/master/CHANGELOG.md

The require statement for 'budget-aware-mcp' is now wrapped in a try/catch block to prevent startup crashes if the module fails to install. SmallCode will fall back to JSON-based memory.

```javascript
require('budget-aware-mcp')
```

--------------------------------

### Run RAG Indexer with Global Install

Source: https://github.com/doorman11991/smallcode/blob/master/docs/rag-harness.md

Execute the RAG indexer command after global installation. This command is equivalent to `npm run rag:index` but uses the globally linked executable.

```bash
smallcode-rag-index --preset broad
```

--------------------------------

### Install SmallCode without Optional Dependencies

Source: https://github.com/doorman11991/smallcode/blob/master/README.md

Install SmallCode globally while omitting optional dependencies, which disables FTS5 memory search but retains the JSON memory fallback.

```bash
npm install -g smallcode --omit=optional
```

--------------------------------

### Programmatic API Usage

Source: https://github.com/doorman11991/smallcode/blob/master/CHANGELOG.md

Import and use the SmallCode programmatic API to run prompts and subscribe to events. Requires 'smallcode' to be installed.

```javascript
const { SmallCode } = require('smallcode')
```

--------------------------------

### Initiate TDD Loop with Requirements

Source: https://github.com/doorman11991/smallcode/blob/master/skills/tdd.md

Call `tdd_loop` with a list of strings, where each string describes a behavior or requirement to be implemented. The harness will then guide you through the test-implement cycle for each requirement.

```python
tdd_loop(requirements=["add() returns the sum", "add() raises TypeError on bad input"])
```

--------------------------------

### TOML Configuration for Model Tiers

Source: https://github.com/doorman11991/smallcode/blob/master/README.md

Configure SmallCode model tiers using a TOML file for backwards compatibility. This example sets a primary model and a 'strong' tier model with its own base URL.

```toml
[model]
provider = "openai"
name = "qwen3:8b"
baseUrl = "http://localhost:11434/v1"

[models.strong]
name = "openai/gpt-4o-mini"
baseUrl = "https://openrouter.ai/api/v1"
```

--------------------------------

### Enable Web Fallback in SmallCode

Source: https://github.com/doorman11991/smallcode/blob/master/docs/rag-harness.md

Set the `SMALLCODE_WEB_BROWSE` environment variable to `true` to enable web search as a fallback when local RAG confidence is low. This allows the model to search externally on GitHub/code-example queries if it gets blocked.

```bash
SMALLCODE_WEB_BROWSE=true smallcode
```

--------------------------------

### Index RAG Database with Starter Preset

Source: https://github.com/doorman11991/smallcode/blob/master/docs/rag-harness.md

Build the RAG index using the default 'starter' preset, which includes a curated set of popular frameworks and libraries.

```bash
npm run rag:index
```

--------------------------------

### SmallCode Agent Initialization and Usage

Source: https://github.com/doorman11991/smallcode/blob/master/README.md

Demonstrates how to initialize a SmallCode agent with specific model and base URL, run a task, and access the results. It also shows how to subscribe to various agent events.

```APIDOC
## Programmatic API Usage

### Description
Use SmallCode as a library in your own tools, CI pipelines, or TypeScript frameworks.

### Initialization
```javascript
const { SmallCode } = require('smallcode');

const agent = new SmallCode({
  model: 'gemma-4-e4b',
  baseUrl: 'http://localhost:1234/v1',
});
```

### Running a Task
```javascript
// Run a task
const result = await agent.run("create hello.py that prints hello world");
console.log(result.filesCreated);  // ['hello.py']
console.log(result.toolCalls.length);  // 1
console.log(result.success);  // true
```

### Event Subscription
```javascript
// Subscribe to events
agent.on('tool_start', ({ name, args }) => console.log(`Using: ${name}`));
agent.on('tool_end', ({ name, ms }) => console.log(`Done: ${name} (${ms}ms)`));
agent.on('error', (err) => console.error(err));
```

### RunResult Structure
Returns a structured `RunResult` with: response text, tool call records, files created/edited, token usage, duration, and success status.
```

--------------------------------

### List Available Benchmark Suites

Source: https://github.com/doorman11991/smallcode/blob/master/bench/README.md

Display a list of all available benchmark suites.

```bash
npm run bench:list
```

--------------------------------

### Run SmallCode from Project Directory

Source: https://github.com/doorman11991/smallcode/blob/master/README.md

Navigate to your project directory and run the smallcode command. A local alias 'smolv2' is also available.

```bash
cd my-project
smallcode
```

--------------------------------

### Configure Local Model Server (LM Studio)

Source: https://github.com/doorman11991/smallcode/blob/master/docs/rag-harness.md

Set environment variables to connect SmallCode to a local model server, typically LM Studio. Ensure the model name and base URL are correct.

```bash
cat > .env <<'ENV'
SMALLCODE_MODEL=your-loaded-model-name
SMALLCODE_BASE_URL=http://localhost:1234/v1
ENV
```

--------------------------------

### List and Use Skills

Source: https://github.com/doorman11991/smallcode/blob/master/skills/README.md

Use these commands to interact with SmallCode skills. The `/skill list` command shows available skills, and `/skill use <skill_name>` activates a specific skill.

```bash
/skill list
/skill use brainstorming
```

--------------------------------

### Liquid AI Tool Call Format

Source: https://github.com/doorman11991/smallcode/blob/master/bench/results/polyglot-mini.md

This is the format emitted by lfm2.5-8b-a1b-apex for tool calls, which requires a Python-literal-aware parser. It includes markers for the start and end of the tool call.

```text
<|tool_call_start|>[write_file(path='hello.py', content='def greet(name):\n    return f"Hello, {name}!"')]<|tool_call_end|>
```

--------------------------------

### Reset Trust Decay at Start of Agent Loop

Source: https://github.com/doorman11991/smallcode/blob/master/CHANGELOG.md

Resets trust decay at the beginning of each agent loop to prevent accumulation across unrelated user requests in TUI mode.

```javascript
getTrustDecay().reset()
```

--------------------------------

### Initialize and Run Agent with SmallCode API

Source: https://github.com/doorman11991/smallcode/blob/master/README.md

Use the SmallCode library to initialize an agent with a specific model and base URL, then run a task and access its results. Event listeners for tool usage and errors can also be set up.

```javascript
const { SmallCode } = require('smallcode');

const agent = new SmallCode({
  model: 'gemma-4-e4b',
  baseUrl: 'http://localhost:1234/v1',
});

// Run a task
const result = await agent.run("create hello.py that prints hello world");
console.log(result.filesCreated);  // ['hello.py']
console.log(result.toolCalls.length);  // 1
console.log(result.success);  // true

// Subscribe to events
agent.on('tool_start', ({ name, args }) => console.log(`Using: ${name}`));
agent.on('tool_end', ({ name, ms }) => console.log(`Done: ${name} (${ms}ms)`));
agent.on('error', (err) => console.error(err));
```

--------------------------------

### Run Benchmark with Custom Options

Source: https://github.com/doorman11991/smallcode/blob/master/bench/README.md

Execute a specific benchmark suite with custom options like timeout, model override, or base URL.

```bash
node bench/harness.js --suite polyglot-mini --timeout 120
```

```bash
node bench/harness.js --suite smoke --model my-model --base-url http://localhost:1234/v1
```

```bash
node bench/harness.js --suite tool-use --task fix-from-error   # single task
```

--------------------------------

### Terminal Restoration Controller

Source: https://github.com/doorman11991/smallcode/blob/master/CHANGELOG.md

Centralizes terminal setup and teardown for alternate-buffer, raw-mode, mouse, and bracketed-paste. Guarantees restoration on all exit paths, including suspend, termination, and crashes, preventing terminal state issues.

```javascript
import { TerminalController } from "src/tui/terminal.js";

const controller = new TerminalController();
controller.setup();

// ... application logic ...

// Teardown is guaranteed on exit, suspend, or crash.
// controller.teardown(); // This is called automatically on various exit signals.
```

--------------------------------

### Run Tool-Use Benchmark

Source: https://github.com/doorman11991/smallcode/blob/master/bench/README.md

Execute multi-step tasks that involve a persistent shell, environment variables, and file renames.

```bash
npm run bench:tools
```

--------------------------------

### Build Local RAG Database

Source: https://github.com/doorman11991/smallcode/blob/master/README.md

Index local GitHub repositories to build a RAG database for SmallCode. Use the 'broad' preset for a larger, multi-language corpus.

```bash
npm run rag:index
```

```bash
npm run rag:index -- --preset broad
```

```bash
smallcode-rag-index --preset broad
```

--------------------------------

### Basic SmallCode Configuration

Source: https://github.com/doorman11991/smallcode/blob/master/README.md

Configure required model name and base URL for SmallCode using environment variables. Supports optional keys for cloud model escalation.

```bash
# 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-...
# OPENROUTER_API_KEY=sk-or-v1-...
# DEEPSEEK_API_KEY=sk-...
```

--------------------------------

### Enable Web Browsing in .env

Source: https://github.com/doorman11991/smallcode/blob/master/README.md

Set the SMALLCODE_WEB_BROWSE environment variable to true to enable web browsing capabilities for the model.

```bash
# In your .env
SMALLCODE_WEB_BROWSE=true
```

--------------------------------

### Run Smoke Test Benchmark

Source: https://github.com/doorman11991/smallcode/blob/master/bench/README.md

Execute a quick sanity check with 5 trivial tasks. This should take approximately 30 seconds.

```bash
npm run bench:smoke
```

--------------------------------

### Set Environment Variables for Benchmarking

Source: https://github.com/doorman11991/smallcode/blob/master/skills/benchmark-driven-development.md

Ensure consistent model and base URL settings across baseline and feature runs by setting these environment variables.

```bash
export SMALLCODE_MODEL=<model_name>
export SMALLCODE_BASE_URL=<url>
```

--------------------------------

### Run Evaluations from CLI

Source: https://github.com/doorman11991/smallcode/blob/master/README.md

Execute classification accuracy and tool selection evaluations directly from the command line using the smallcode CLI.

```bash
smallcode --eval classify_accuracy
smallcode --eval tool_selection
```

--------------------------------

### Multi-Model Chaining Configuration

Source: https://github.com/doorman11991/smallcode/blob/master/CHANGELOG.md

Configure multi-model chaining by setting SMALLCODE_CHAIN to true. Specify planner and executor models and their optional URLs.

```bash
SMALLCODE_CHAIN=true
SMALLCODE_CHAIN_PLANNER=gemma-2b          # cheap planner model
SMALLCODE_CHAIN_EXECUTOR=qwen3-8b         # main executor
SMALLCODE_CHAIN_PLANNER_URL=http://...    # optional separate endpoint
SMALLCODE_CHAIN_EXECUTOR_URL=http://...
```

--------------------------------

### Compare Benchmark Harness Runs with Custom Threshold and JSON Output

Source: https://github.com/doorman11991/smallcode/blob/master/README.md

Compares two benchmark harness runs using a custom threshold for noise detection and outputs the results in JSON format.

```bash
node bench/diff.js bench/baselines/main bench/baselines/feature --threshold 0.05 --json
```

--------------------------------

### Knowledge Directory Layout

Source: https://github.com/doorman11991/smallcode/blob/master/knowledge/README.md

Illustrates the recommended directory structure for organizing knowledge notes within the 'knowledge' directory.

```text
knowledge/
  algorithms/
    binary-search.md
    quicksort.md
  syntax/
    python-fstrings.md
    typescript-generics.md
  conventions/
    git-commit-style.md
```

--------------------------------

### Compare Benchmark Harness Runs

Source: https://github.com/doorman11991/smallcode/blob/master/README.md

Compares two benchmark harness runs (e.g., a baseline against a fresh run) to determine improvements or regressions. Returns an exit code indicating the result.

```bash
npm run bench:diff bench/baselines/main bench/baselines/feature
```

--------------------------------

### Link SmallCode for Global Command

Source: https://github.com/doorman11991/smallcode/blob/master/docs/rag-harness.md

Link the local checkout to make the `smallcode` command globally available. This avoids needing to use `node bin/smallcode.js`.

```bash
npm link
smallcode
```

--------------------------------

### Index RAG Database with Broad Preset

Source: https://github.com/doorman11991/smallcode/blob/master/docs/rag-harness.md

Build a larger RAG index using the 'broad' preset, which scrapes more codebases but requires more time and disk space.

```bash
npm run rag:index -- --preset broad
```

--------------------------------

### Run Full Polyglot Benchmark

Source: https://github.com/doorman11991/smallcode/blob/master/bench/README.md

Execute the complete suite of 19 tasks across multiple languages including Python, JS, TS, Shell, Markdown, and JSON.

```bash
npm run bench:polyglot
```

--------------------------------

### Available SmallCode Tools

Source: https://github.com/doorman11991/smallcode/blob/master/README.md

Lists and describes the various tools available within the SmallCode environment for tasks such as compilation, validation, searching, file manipulation, and web browsing.

```APIDOC
## 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`) |
| `contract_create` | Declare a Definition-of-Done with a list of testable assertions |
| `contract_status` | Show the active contract: assertions, state, blockers |
| `contract_assert_pass` | Mark an assertion passed (with command-line evidence) |
| `contract_assert_fail` | Mark an assertion failed (with evidence) |
| `contract_assert_skip` | Mark an assertion skipped (out of scope) |
```

--------------------------------

### Configuration for Per-Tier Endpoint Routing in smallcode.toml

Source: https://github.com/doorman11991/smallcode/blob/master/CHANGELOG.md

Define model tiers and their corresponding base URLs within the smallcode.toml configuration file. This provides a persistent way to manage endpoint routing for different model strengths.

```toml
[models.fast]
name = "..."
baseUrl = "..."

[models.default]
name = "..."
baseUrl = "..."

[models.medium]
name = "..."
baseUrl = "..."

[models.strong]
name = "..."
baseUrl = "..."
```

--------------------------------

### Configure llama.cpp Server

Source: https://github.com/doorman11991/smallcode/blob/master/docs/rag-harness.md

Configure SmallCode to use a llama.cpp server by setting the model name and base URL. The default port for llama.cpp is usually 8080.

```bash
SMALLCODE_MODEL=local-model
SMALLCODE_BASE_URL=http://localhost:8080/v1
```

--------------------------------

### Configure Fallback Models for Adaptive Routing

Source: https://github.com/doorman11991/smallcode/blob/master/README.md

Optional configuration for adaptive model routing. Sets fallback models and their base URLs when the primary model's failure rate exceeds thresholds.

```bash
# Optional: configure fallback models for adaptive routing
SMALLCODE_MODEL_MEDIUM=qwen2.5-coder:32b
SMALLCODE_MODEL_STRONG=gpt-4o
SMALLCODE_BASE_URL_STRONG=https://openrouter.ai/api/v1
```

--------------------------------

### Advanced SmallCode Configuration with Model Tiers

Source: https://github.com/doorman11991/smallcode/blob/master/README.md

Configure SmallCode to route different model tiers to distinct endpoints, allowing local processing for default tasks and cloud models for complex ones. Tier URLs are optional and fall back to the primary base URL if omitted.

```bash
SMALLCODE_MODEL=qwen3:8b
SMALLCODE_BASE_URL=http://localhost:11434/v1

SMALLCODE_MODEL_STRONG=openai/gpt-4o-mini
SMALLCODE_BASE_URL_STRONG=https://openrouter.ai/api/v1
OPENROUTER_API_KEY=sk-or-v1-...
```

--------------------------------

### Compare Benchmark Baselines

Source: https://github.com/doorman11991/smallcode/blob/master/skills/benchmark-driven-development.md

Compare the results of two benchmark runs using the provided diff script. This command helps identify improvements, regressions, or noise between a baseline and a feature branch.

```bash
node bench/diff.js bench/baselines/<base> bench/baselines/<feature>
```