Guida Headroom AI
Guida Headroom AI
Headroom AI è un livello open source (Apache 2.0) di ottimizzazione del contesto per applicazioni LLM e agenti di coding: comprime output dei tool, letture di file, risultati di database e payload RAG prima che arrivino al modello. In questa guida vedi cos’è, come si installa, come lavorano i suoi compressori, come funziona la Reversible Compression (CCR) e come collegarlo a Claude Code e a GitHub Copilot, con comandi e snippet TypeScript pronti da provare.
Marco è un backend engineer. Venerdì pomeriggio chiede al suo agente di capire perché un job notturno fallisce. L’agente interroga i log, legge tre file, lancia la suite di test. In pochi minuti la finestra di contesto è piena di migliaia di righe “Success” e “PASSED”, e il vero indizio è una singola riga di errore sepolta nel mezzo. Il modello rallenta, risponde peggio, e il conto dei token cresce. Headroom nasce per questo problema.
Tutto ciò che leggi qui deriva dal sito e dalla documentazione ufficiali del progetto (elenco in fondo). I risparmi indicati sono quelli dichiarati da Headroom, misurati su dati di test generati e non su telemetria di produzione: considerali un ordine di grandezza, non una promessa.
Indice dei contenuti – Guida Headroom AI
1. Cos’è Headroom AI e perché interessa ora
2. Le caratteristiche principali
3. Installazione passo dopo passo
5. Reversible Compression (CCR): niente va perso
6. Esempio pratico: comprimere un output JSON da 1.000 eventi
7. Integrazione con Claude Code
8. Integrazione con GitHub Copilot in VS Code
9. Limiti, numeri reali e quando non serve
10. Conclusioni e formazione professionale
1. Cos’è Headroom AI e perché interessa ora
Headroom è definito dalla documentazione come il livello di ottimizzazione del contesto per applicazioni LLM. Si inserisce tra la tua applicazione (o il tuo agente) e il provider del modello e comprime tutto ciò che l’agente legge: tool output, risultati di database, letture di file, recupero RAG, risposte di API. Il modello vede meno rumore, risponde più in fretta e costa meno.
Un’analogia utile è il bagaglio a mano. La compagnia ti concede un volume fisso e tu devi decidere cosa portare. Headroom è come un assistente che toglie imballaggi e ridondanze, lascia in valigia ciò che serve davvero e, soprattutto, conserva in un deposito una copia di quello che ha tolto. Di questo deposito parliamo nel paragrafo 5.
Il flusso è semplice:
La tua app / il tuo agente
| tool output, log, letture di file, RAG, API
v
Headroom (proxy, libreria Python, SDK TypeScript, MCP)
|
v
Provider LLM (OpenAI, Anthropic, Google, Bedrock, 100+ via LiteLLM)
Il progetto è open source, “local-first” (la compressione avviene in locale, prima dell’inferenza) e, al momento in cui scriviamo, il sito ufficiale riporta circa 24,9 mila stelle su GitHub. Perché interessa proprio ora? Perché gli agenti di coding leggono tanto e male: grep enormi, log verbosi, JSON ripetitivi. Ogni token inutile costa denaro, latenza e attenzione del modello.
2. Le caratteristiche principali – Guida Headroom AI
Iniziamo subito la nostra Guida Headroom AI. Ecco cosa offre Headroom, secondo la documentazione ufficiale:
- Rilevamento automatico del contenuto. Riconosce JSON, codice, log, testo, diff e HTML e instrada ogni blocco al compressore più adatto, senza configurazione.
- Reversible Compression (CCR). Comprime in modo aggressivo, conserva gli originali in locale e fornisce al modello un tool per recuperarli.
- Cache optimization. Stabilizza i prefissi dei messaggi per sfruttare le KV cache dei provider e tiene traccia dei messaggi “congelati” per non perdere lo sconto sulle letture da cache.
- Compressione di immagini. Un router ML sceglie il compromesso resize/qualità; la documentazione dichiara riduzioni di token tra il 40% e il 90%.
- Memoria persistente e apprendimento dai fallimenti. Memoria gerarchica (utente, sessione, agente, turno) su SQLite, più un modulo che analizza le sessioni passate e scrive le lezioni apprese in CLAUDE.md.
- Osservabilità. Endpoint Prometheus, log per richiesta, tracking dei costi e una dashboard locale.
- Quattro modi d’uso. Wrapper da riga di comando, proxy trasparente, SDK (Python e TypeScript) oppure server MCP: stessa pipeline, superfici diverse.
- Integrazioni. LangChain, LangGraph, Agno, Strands, CrewAI, AutoGen, LiteLLM, Vercel AI SDK, oltre a strumenti come Claude Code, Codex, Cursor, Aider e Copilot.
3. Installazione passo dopo passo
Entriamo nel pratico della Guida Headroom AI. Prima di installare scegli la strada giusta. La CLI (wrap, proxy, mcp, doctor…) arriva solo dal pacchetto Python. L’SDK npm è una libreria da importare e non installa la CLI. Requisiti: Python 3.10 o superiore (wheel per CPython 3.10–3.13 su Linux, macOS e Windows x86_64) e Node.js 18+ per l’SDK TypeScript.
Opzione A: CLI globale con uv (consigliata dalla documentazione su macOS Apple Silicon e Linux):
uv tool install --python 3.13 "headroom-ai[all]"
headroom --version
# se la shell non trova il comando:
uv tool update-shell
Opzione B: pip. Il nome della distribuzione è sempre headroom-ai: su PyPI esiste un progetto diverso chiamato headroom, da non confondere.
# pacchetto base: compress(), SmartCrusher, ContentRouter
pip install headroom-ai
# bundle completo di runtime
pip install "headroom-ai[all]"
# oppure solo gli extra che ti servono
pip install "headroom-ai[proxy,code,mcp]"
python -c "import headroom; print(headroom.__version__)"
Gli extra più utili sono proxy (server e API HTTP), code (compressione AST con tree-sitter), mcp (tool MCP), image e memory. Attenzione: [all] non include integrazioni come langchain, agno, strands, autogen o bedrock, da richiedere esplicitamente.
Opzione C: npm per i progetti TypeScript/Node. Qui c’è un dettaglio che fa inciampare molti: l’SDK TypeScript invia i messaggi via HTTP al proxy Headroom, che esegue la pipeline in Python. Il proxy deve quindi essere in esecuzione.
npm install headroom-ai
# in un altro terminale: avvia il proxy
pip install "headroom-ai[proxy]"
headroom proxy --port 8787
Opzione D: Docker, se non vuoi installare né Python né Node:
docker pull ghcr.io/headroomlabs-ai/headroom:latest
docker run --rm -p 127.0.0.1:8787:8787 \
ghcr.io/headroomlabs-ai/headroom:latest --host 0.0.0.0
Esistono tag dedicati, per esempio code (include tree-sitter) e varianti slim basate su immagine distroless. Tra le variabili d’ambiente più utili ci sono HEADROOM_PORT (default 8787), HEADROOM_MODE (cache o token) e HEADROOM_BASE_URL per l’SDK TypeScript. Con il proxy attivo, headroom dashboard apre la dashboard dei risparmi su http://localhost:8787/dashboard.
4. I tipi di compressione – Guida Headroom AI
Headroom non applica un unico algoritmo a tutto. Il ContentRouter esamina ogni blocco, ne riconosce il tipo e lo passa al compressore specializzato. Prima di una pipeline ci sono regole di sicurezza: tool protetti, turni recenti, prefissi in cache e soglie minime di dimensione decidono cosa può essere modificato. Se non c’è un risparmio sicuro, il contenuto passa invariato.
| Contenuto | Compressore | Cosa conserva |
| Array JSON | SmartCrusher | Errori, anomalie, primi e ultimi elementi, elementi rilevanti |
| Codice sorgente | CodeAwareCompressor (tree-sitter) | Import, firme, classi, tipi, decoratori |
| Risultati grep/ripgrep | SearchCompressor | Match rilevanti, varietà di file |
| Log di build e test | LogCompressor | Errori, stack trace, righe di riepilogo |
| Diff unificati | DiffCompressor | Hunk modificati e contesto utile |
| Testo libero | Kompress / TextCrusher | Frasi rilevanti, token ad alta entropia (ID, hash) |
| HTML, config, tabelle | HTMLExtractor, ConfigCompressor, TabularCompressor | Contenuto principale e struttura |
| Immagini | Router ML | Compromesso resize/qualità per immagine |
| Output di git status | Passthrough lossless | Tutto, byte per byte |
SmartCrusher: il revisore dei registri. Immagina un revisore che riceve un registro da mille righe. Guarda l’inizio e la fine, si ferma su ogni errore e su ogni valore anomalo, campiona il resto. SmartCrusher fa lo stesso sugli array JSON, con un’avvertenza importante: per default prova prima una compattazione lossless. Se l’array è tabellare e il re-encoding in forma compatta (csv-schema) risparmia almeno il 30% dei byte, nessun elemento viene scartato. Solo altrimenti passa al criterio “tieni/scarta”, che valuta primo e ultimo elemento, errori (mai scartati), anomalie oltre due deviazioni standard, elementi rilevanti per la query e punti di cambio. Il limite predefinito è circa 15 elementi dopo la compressione.
CodeAwareCompressor: tagliare senza rompere. Troncare un file a metà produce sintassi invalida. Qui il codice viene analizzato con tree-sitter: restano import, firme, tipi e decoratori, mentre i corpi delle funzioni vengono ridotti. Python, JavaScript e TypeScript hanno analisi AST completa; Go, Rust, Java, C, C++, C# e PHP la compressione dei corpi. Va installato con pip install “headroom-ai[code]”. Un dettaglio da sapere: nel proxy il routing del codice è attivo di default, mentre con la funzione compress() della libreria è disattivato e il codice ricade su Kompress, a meno che tu non lo abiliti.
Log, ricerche, diff e testo. LogCompressor tiene errori, stack trace e riepiloghi e butta centinaia di righe PASSED. SearchCompressor privilegia i match esatti e la diversità dei file. DiffCompressor preserva le modifiche reali. Per il testo libero Kompress usa uno scoring appreso (ONNX), mentre TextCrusher seleziona frasi senza riscriverle. I compressori sono richiamabili direttamente anche da Python:
from headroom.transforms import LogCompressor
result = LogCompressor().compress(build_output) # build_output: stringa con il log
print(result.compressed)
print(f"Compressione: {result.compression_ratio:.1%}")
5. Reversible Compression (CCR): niente va perso
Continuiamo la Guida Headroom AI. Torniamo al bagaglio a mano. Il problema della compressione tradizionale è un compromesso scomodo: se comprimi troppo rischi di buttare il dato che serve, se comprimi poco non risparmi. CCR, acronimo di Compress-Cache-Retrieve, elimina il dilemma con l’idea del deposito bagagli: lasci il superfluo con un tagliando numerato e, se ti serve, torni a ritirarlo.
Il meccanismo, in quattro fasi:
- Compression Store. L’originale viene salvato con una chiave hash. Nel proxy lo store è di default un file SQLite (ccr_store.db), quindi sopravvive ai riavvii ed è condiviso tra i worker; con HEADROOM_CCR_BACKEND=memory passi a uno store solo in memoria. Nel testo compresso compare un marcatore.
- Iniezione del tool. Headroom aggiunge ai tool del modello headroom_retrieve, così l’LLM può chiedere i dati completi quando quelli compressi non bastano.
- Response Handler. Se il modello chiama il tool, l’handler intercetta la chiamata, legge dalla cache locale (circa 1 ms) e fa proseguire la richiesta in automatico. Sui percorsi proxy Anthropic e OpenAI questo vale per le risposte che contengono solo la chiamata di retrieval; le risposte miste e gli alias registrati via MCP sono inoltrati al client.
- Context Tracker. Tra un turno e l’altro ricorda cosa è stato compresso e, se una nuova domanda sembra legata a quei dati, li espande in anticipo.
Il marcatore che il modello vede ha questa forma:
[1000 items compressed to 20. Retrieve more: hash=abc123]
La documentazione sottolinea che CCR cambia il rischio, non il rapporto di compressione: ottieni i risparmi di una compressione aggressiva, con l’originale sempre a un retrieval di distanza. Un limite pratico però esiste: gli originali nel proxy restano disponibili per 1800 secondi (30 minuti) per default. Per sessioni autonome lunghe puoi allungare il periodo:
HEADROOM_CCR_TTL_SECONDS=7200 headroom proxy
Dall’SDK TypeScript la configurazione CCR è un oggetto tipizzato (i valori sono quelli di esempio della documentazione):
import type { CCRConfig } from 'headroom-ai';
const ccr: CCRConfig = {
enabled: true,
injectTool: true, // inietta il tool headroom_retrieve
injectRetrievalMarker: true, // aggiunge i marcatori nel testo compresso
feedbackEnabled: true, // impara dai pattern di retrieval
storeMaxEntries: 1000,
storeTtlSeconds: 3600,
};
6. Esempio pratico: comprimere un output JSON da 1.000 eventi – Guida Headroom AI
Rimettiamo Marco al lavoro. Il suo tool restituisce mille eventi, quasi tutti “ok”, con un solo errore all’indice 998. Vediamo cosa fa Headroom con l’SDK TypeScript. Gli snippet sono adattati dalla documentazione ufficiale: provali nel tuo ambiente prima di portarli in produzione.
Passo 1: avvia il proxy (serve all’SDK TypeScript).
pip install "headroom-ai[proxy]"
headroom proxy --port 8787
Passo 2: comprimi i messaggi. Salva lo script come demo.mjs (usa gli ES module, quindi await al livello principale).
import { compress } from 'headroom-ai';
// 1.000 eventi "ok" con un solo errore nascosto all'indice 998
const eventi = Array.from({ length: 1000 }, (_, i) => ({
id: i + 1, status: 'ok', message: 'Success',
}));
eventi[997] = { id: 998, status: 'error', message: 'Connection timeout' };
const messages = [
{ role: 'system', content: 'Sei un assistente SRE.' },
{ role: 'user', content: 'Trova gli errori delle ultime 24 ore' },
{ role: 'tool', content: JSON.stringify({ results: eventi }), tool_call_id: 'call_1' },
];
const result = await compress(messages, {
model: 'gpt-4o',
baseUrl: 'http://localhost:8787',
});
console.log('Token prima:', result.tokensBefore);
console.log('Token dopo :', result.tokensAfter);
console.log('Risparmio :', ((1 - result.compressionRatio) * 100).toFixed(0) + '%');
console.log('Trasformazioni:', result.transformsApplied.join(', '));
Passo 3: leggi il risultato con occhio critico. Un array di elementi quasi identici è esattamente il caso in cui SmartCrusher preferisce la compattazione lossless: potresti vedere tutti gli elementi ancora presenti, ma codificati in forma compatta, anziché una riduzione a circa 15 elementi. Entrambi i percorsi conservano l’errore. Se vuoi forzare il solo criterio “tieni/scarta” nella libreria Python, SmartCrusher accetta with_compaction=False.
Passo 4 (facoltativo): Vercel AI SDK. Se usi già questo SDK, il wrapping è una riga:
import { withHeadroom } from 'headroom-ai/vercel-ai';
import { openai } from '@ai-sdk/openai';
const model = withHeadroom(openai('gpt-4o'));
7. Integrazione con Claude Code
Usiamo Claude Code nella Guida Headroom AI.
Claude Code si collega a Headroom in tre modi, a seconda di quanto controllo vuoi.
Via wrapper (il più rapido). Un comando avvia Claude Code facendo passare ogni lettura attraverso la compressione:
pip install "headroom-ai[all]"
headroom wrap claude
Via proxy. Utile se vuoi gestire tu il processo e lo scope delle variabili d’ambiente:
# Terminale 1
headroom proxy
# Terminale 2
ANTHROPIC_BASE_URL=http://127.0.0.1:8787 claude
Via MCP. Registri tre tool (headroom_compress, headroom_retrieve, headroom_stats) che Claude può invocare a richiesta, senza proxy:
pip install "headroom-ai[mcp]"
headroom mcp install # registrazione una tantum
claude # verifica con /mcp, o con: headroom mcp status
Le due strade non si pestano i piedi: il proxy comprime il traffico HTTP prima che il modello veda il contenuto, i tool MCP lavorano dopo. Se la sezione /usage di Claude Code attribuisce una quota sorprendente al server MCP, la documentazione ricorda che sono le interazioni MCP rimaste nel contesto, non un costo di Headroom; per il traffico normale preferisci il proxy e usa /compact dopo investigazioni lunghe.
Estensione ufficiale in VS Code. Per l’estensione Claude Code (VS Code 1.98 o successivo, già autenticata) il comando è headroom wrap vscode-claude. Headroom aggiunge in ~/.claude/settings.json due voci sotto env, senza toccare credenziali e modello:
{
"env": {
"ANTHROPIC_BASE_URL": "http://127.0.0.1:8787/p/your-project",
"ENABLE_TOOL_SEARCH": "true"
}
}
Dopo la prima configurazione esegui Developer: Reload Window, lascia il terminale del wrapper aperto e controlla http://127.0.0.1:8787/health. Due note operative importanti: se fermi il proxy, le richieste falliscono invece di aggirare Headroom (comportamento “fail closed”), e per tornare indietro basta headroom unwrap vscode-claude. In Dev Container, SSH o WSL, 127.0.0.1 deve riferirsi all’ambiente in cui gira Claude Code.
8. Integrazione con GitHub Copilot in VS Code
Usiamo Copilot nella Guida Headroom AI. Con Copilot l’approccio è diverso e interessante: Headroom si inserisce sotto il selettore di modelli nativo di VS Code. Non sostituisce il modello e non compare nessun modello “Headroom” nel menu: sovrascrive l’endpoint proxy delle API Copilot, quindi il modello che scegli viaggia invariato verso GitHub. Headroom non modifica l’estensione, non termina il TLS e non tocca la configurazione di Codex.
Requisiti: VS Code stabile con GitHub Copilot attivo e autenticato, un account con accesso Copilot e pip install “headroom-ai[proxy]”.
Passo 1: autorizza Headroom una volta sola. VS Code custodisce il token Copilot in un archivio cifrato che Headroom non legge, quindi serve un’autorizzazione separata tramite device flow GitHub:
headroom copilot-auth login
headroom copilot-auth status # deve riportare "logged in"
Passo 2: avvia il wrapper dalla cartella del progetto a cui attribuire i risparmi:
headroom wrap vscode
Il comando verifica l’accesso a Copilot, avvia Headroom su 127.0.0.1:8787 e inserisce in settings.json un blocco delimitato da marcatori con due impostazioni: github.copilot.advanced.debug.overrideProxyUrl (completamenti inline) e github.copilot.advanced.debug.overrideCapiUrl (chat). I tuoi commenti JSONC e le altre impostazioni restano intatti; se trova file malformati o un override esistente non gestito, si rifiuta di sovrascrivere. Resta in esecuzione fino a Ctrl+C.
Cosa passa dal proxy: chat, agent e completamenti. Servizi accessori come telemetria, chiamate API GitHub, MCP, embedding, model discovery e cloud agent usano altri endpoint e non sono reindirizzati. Per profili VS Code con impostazioni proprie, Insiders, VSCodium o host remoti usa –settings-file; con –no-configure stampi le impostazioni senza scrivere nulla.
Per disattivare: headroom unwrap vscode rimuove solo il blocco di Headroom. Ricorda che, a proxy fermo ma impostazioni ancora presenti, le richieste Copilot falliscono invece di bypassare il proxy. In ambienti aziendali con Copilot Business o Enterprise, la documentazione descrive l’instradamento verso l’host advertised dal piano e le variabili per GitHub Enterprise Server.
9. Limiti, numeri reali e quando non serve
Un tool serio si riconosce anche da come dichiara i propri limiti, e la documentazione di Headroom lo fa. I risparmi dipendono dalla ripetitività dei dati. Questi sono i numeri misurati dal progetto su dati di test generati da formati reali di output MCP (conteggi con il tokenizer gpt-5.6):
| Scenario | Token prima | Token dopo | Risparmio |
| Ricerca nel codice (100 risultati) | 17.199 | 13.597 | 21% |
| Debug incidente SRE | 55.957 | 24.340 | 57% |
| Esplorazione del codebase | 58.801 | 33.895 | 42% |
| Triage issue GitHub | 46.067 | 32.429 | 30% |
Il progetto stesso invita a trattarli come una forma, non come una promessa, e a riprodurli sul tuo traffico con gli script nella cartella benchmarks/ del repository. Altri punti da tenere a mente:
- Headroom non elimina la cronologia. Comprime i tool output freschi e i nuovi turni, non scarta la conversazione precedente.
- L’SDK TypeScript non è autonomo. Dipende da un proxy raggiungibile.
- Gli originali scadono. Nel proxy dopo 30 minuti per default, nello store MCP locale dopo un’ora: regola il TTL per i lavori lunghi.
- Il proxy fermo blocca. Il comportamento “fail closed” è una scelta di sicurezza, ma va previsto nei runbook del team.
- Compatibilità Python. Con Python 3.14 e successivi alcuni backend ONNX (rilevamento ML, Kompress locale) non sono disponibili: la documentazione consiglia Python 3.13.
Quando non serve? Con contesti piccoli, output già concisi o poco ripetitivi il guadagno è marginale. Dove invece gli agenti leggono log, ricerche e payload JSON voluminosi, il rapporto costo/beneficio cambia parecchio.
10. Conclusioni e formazione professionale
Marco, alla fine, trova la riga di errore in meno tempo e con meno token. Ma la vera lezione non riguarda Headroom: riguarda il modo in cui lavoriamo. L’AI è ormai il pane quotidiano di chi sviluppa software. Agenti di coding, assistenti nell’IDE, MCP, proxy di contesto: il perimetro degli strumenti cambia ogni mese, e chi non li padroneggia semplicemente rischia di diventare un dinosauro, bravissimo in un ecosistema che nel frattempo si è spostato altrove.
Per questo la formazione continua del team non è un extra, è una parte del lavoro. Se sei responsabile di un gruppo di sviluppatori, ti consiglio con convinzione la formazione aziendale di Innovaformazione, pensata per tenere il tuo team al passo con gli aggiornamenti reali degli strumenti AI.
Tra i percorsi disponibili ti suggerisco i corsi di AI Generativa, e in particolare il Corso Claude Code per sviluppatori, che affronta proprio il tipo di workflow di cui abbiamo parlato in questa guida.
Corsi attivati su richiesta.
Modalità online, in classe virtuale, con calendario da concordare. Possibilità di personalizzare il corso, inserendo Headroom AI nel percorso didattico.
Per richieste di informazioni e preventivi: info@innovaformazione.net · tel. 3471012275 · Dario Carrassi.
Per altri articoli tecnici di settore ed aggiornati, consigliamo di navigare sul nostro blog QUI.
Articoli correlati
Claude Code con Arduino
Novità .Net 11
Backdoor nei modelli AI open-weight
Opportunità di lavoro Bari
Spieghiamo il Weight space programming
