Come usare SmallCode: la guida completa per sviluppatori

Cosa fa SmallCode

SmallCode è un agente di programmazione nativo per terminale che rende efficaci i piccoli modelli linguistici locali (8B–35B parametri) nei compiti di programmazione. Compensa i limiti dei modelli per hardware consumer grazie alla gestione del budget di contesto, al parsing indulgente delle chiamate agli strumenti (JSON, YAML, XML, testo semplice, auto-repair), alla modifica orientata alle patch con search‑and‑replace, alla pianificazione basata su TODO, alle sessioni shell persistenti, all’escalation opzionale al cloud e agli strumenti di osservabilità. L’agente funziona per impostazione predefinita completamente in locale.

Per iniziare

Installa via npm: npm install -g smallcode (richiede Node.js 18+). Sono disponibili binari precompilati per Linux, macOS e Windows tramite uno script shell. Verifica con smallcode --help. Hai bisogno di un server LLM locale con un endpoint compatibile OpenAI (LM Studio, Ollama). Opzionalmente better-sqlite3 attiva il grafo del codice e la memoria FTS5; se la compilazione fallisce viene usato un archivio JSON.

Crea un file .env con:

• SMALLCODE_MODEL=<nome-modello> (obbligatorio)
• SMALLCODE_BASE_URL=http://localhost:1234/v1 (obbligatorio)

Opzionalmente aggiungi chiavi API cloud (ANTHROPIC_API_KEY, ecc.) per l’escalation. Esegui smallcode per avviare.

TUI interattiva e comandi slash

Esegui smallcode all’interno di una directory di progetto. L’agente rileva automaticamente i comandi di esecuzione e di test, quindi presenta un’interfaccia conversazionale. I compiti complessi vengono scomposti in piani TODO; utilizza automaticamente gli strumenti e convalida ogni passaggio. I comandi slash offrono controllo:

/quit, /clear, /stats, /tokens, /budget (visualizzazione contesto), /trace, /eval, /memory, /plan, /model, /profile, /cognition, /mcp, /skill, /plugin, /sessions, /help.

Questi consentono monitoraggio, gestione delle sessioni e cambio di modello.

Uso programmatico e test

Integra SmallCode come libreria. Richiedi Smallcode, istanzialo con modello e URL base e chiama agent.run(). Sottoscriviti agli eventi come tool_start e error. Il RunResult restituito include file creati/modificati, chiamate agli strumenti, stato di successo e utilizzo dei token.

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

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

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

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));

Esegui i benchmark con npm run bench:smoke, bench:polyglot o bench:tools. I risultati vengono salvati in .smallcode/benchmarks/. Genera test di regressione dalle tracce utilizzando /trace test <id>.

Opzioni di configurazione

Configura tramite .env o il file legacy smallcode.toml. Variabili chiave:

• SMALLCODE_MODEL (obbligatorio) – nome del modello.
• SMALLCODE_BASE_URL (obbligatorio) – endpoint.
• ANTHROPIC_API_KEY, OPENAI_API_KEY, DEEPSEEK_API_KEY – chiavi di escalation cloud opzionali.
• SMALLCODE_THINKING_BUDGET – budget massimo di token per il ragionamento (predefinito 2000); disabilita con THINKING_DISABLE=true.
• SMALLCODE_SHELL_PERSIST – mantieni lo stato della shell tra i turni (predefinito true).
• SMALLCODE_WRITE_GUARD – rifiuta la prima scrittura su file non letto (predefinito true).
• SMALLCODE_SNAPSHOT/AUTO_ROLLBACK – snapshot pre-modifica e ripristino automatico in caso di fallimento grave.
• SMALLCODE_PLAN – forza la modalità pianifica-poi-esegui.
• SMALLCODE_TEST_RUNNER/TEST_DISABLE – sovrascrivi o disabilita l’iniezione del test runner.
• SMALLCODE_WEB_BROWSE – abilita gli strumenti web (richiede modello 20B+).
• SMALLCODE_MODEL_MEDIUM/STRONG – modelli per il routing adattivo.
• TEMP_ADAPT, TRUST_DECAY – flag per il retry adattivo e il punteggio di fiducia.

Vincoli e Limitazioni

• I modelli ≤4B faticano con l'uso di tool multi‑step; le prestazioni migliori si hanno con 8B–35B.
• I risultati dei tool sono troncati a 4k caratteri; i risultati più vecchi possono essere eliminati sotto pressione del budget.
• better-sqlite3 potrebbe richiedere la compilazione nativa per il code graph; altrimenti viene usata la memoria JSON.
• Il Web browsing è affidabile solo con modelli da 20B+.
• Si applicano costi di Cloud escalation; le chiamate sono limitate per sessione.
• Il Thinking budget può troncare il ragionamento su modelli come DeepSeek R1, influendo su compiti complessi.
• Il Write guard blocca la prima scrittura su un file non letto; è consentito un secondo tentativo.
• Lo Snapshot auto‑rollback può annullare tutte le modifiche del turno; i dati dello snapshot persistono in .smallcode/snapshots/.

Best Practices

• Consenti a SmallCode di rilevare automaticamente il runtime, il framework e i test del progetto al primo turno per risparmiare tool call.
• Usa la pianificazione euristica predefinita; abilita SMALLCODE_PLAN=true solo se il modello deraglia.
• Mantieni attivo l'evidence store per catturare gli esiti dei compiti per l'apprendimento futuro.
• Abilita il read‑before‑write guard e lo snapshot auto‑rollback per le modifiche rischiose.
• Imposta SMALLCODE_TEST_RUNNER se il rilevamento automatico fallisce, per evitare tool call sprecate.
• Usa sessioni shell persistenti (SHELL_PERSIST=true) per comandi multi‑step.
• Monitora il contesto con /budget e /tokens.
• Mantieni attiva la temperatura di retry adattiva in modo che le modifiche fallite varino.
• Il Web browsing è raccomandato solo per modelli da 20B+; disabilitalo per quelli più piccoli.
• Genera test di regressione dalle tracce dopo compiti complessi riusciti.

Funzionalità Avanzate

Snapshot & Rollback: Vengono creati checkpoint dei file pre‑turno. AUTO_ROLLBACK=true annulla tutte le modifiche di un turno in caso di fallimento della validazione. Gli snapshot persistono in .smallcode/snapshots/.

Sessioni & Memoria: Le sessioni si salvano automaticamente; usa /sessions list e resume. Un taccuino persistente funge da memoria di lavoro; l'evidence store cattura ciò che è stato provato e fallito, aiutando le esecuzioni future.

Competenze & Plugin: Sei competenze integrate (brainstorming, debugging, tdd, ecc.) vengono caricate da skills/. Gestiscile con /skill list, /skill use. I plugin possono essere installati tramite /plugin.

Instradamento Adattivo: Tiene traccia dei tassi di fallimento per modello; passa automaticamente a SMALLCODE_MODEL_MEDIUM/STRONG quando vengono superate le soglie (0.3/0.6).

Cognizione & Scaffolding: MarrowScript viene compilato in TypeScript per caching, retry e validazione. BoneScript genera un backend Node.js completo da un singolo file .bone.

Configurazione & Aggiornamenti: Supporto per .env e il legacy .smallcode.toml. I benchmark vengono eseguiti con npm run bench:smoke, bench:polyglot, bench:tools.