Headroom: la compressione del contesto open-source per agenti AI

Chi lavora ogni giorno con Claude Code, Codex, Cursor o altre CLI di coding basate su AI conosce bene il problema: dopo un'ora di sessione il contesto è pieno di log, output di test, risultati di ricerche nel codice e frammenti RAG, e il budget di token — misurato in fattura API oppure in quota dell'abbonamento — si consuma rapidamente. Headroom è un progetto open-source che aggredisce esattamente questo collo di bottiglia: comprime tutto ciò che l'agente legge prima che arrivi al modello, con la promessa di ottenere le stesse risposte usando una frazione dei token.

Cos'è Headroom

Headroom è un livello di compressione del contesto per agenti AI, distribuito con licenza Apache-2.0 e pensato per girare in locale: i dati non lasciano la macchina di chi lo usa. Il repository — github.com/headroomlabs-ai/headroom, nato come progetto personale e poi spostato sotto l'organizzazione Headroom Labs — ha superato le 49.000 stelle su GitHub e viene aggiornato con cadenza quasi giornaliera. È scritto principalmente in Python (richiede Python 3.10 o superiore) con un core in Rust, e si installa con un solo comando: pip install "headroom-ai[all]" oppure uv tool install "headroom-ai[all]".

Il concetto di fondo è semplice: un agente di coding passa gran parte del tempo a leggere — output di comandi, stack trace, file sorgenti, risultati di grep, risposte di server MCP, chunk recuperati da una pipeline RAG. Buona parte di questo materiale è ridondante, ripetitiva o irrilevante ai fini della risposta. Headroom si frappone tra l'agente e il provider LLM e riduce quel materiale alla sua componente informativa, mantenendo però gli originali in una cache locale: la compressione è reversibile, non distruttiva.

A cosa serve

Gli scenari d'uso principali sono quattro.

Il primo è il coding assistito quotidiano. Durante il debugging un agente esegue test che falliscono, legge log di build, ispeziona errori di dipendenze: ogni passaggio aggiunge migliaia di token al contesto. Headroom comprime questi output intermedi conservando firme d'errore, timestamp e stack trace, così il modello ragiona sull'essenziale invece di affogare nel rumore.

Il secondo è la compressione dei chunk RAG: i sistemi di retrieval tendono a recuperare più testo del necessario e Headroom riduce i frammenti prima che entrino nella finestra del modello. Non è un framework RAG e non vuole esserlo: si colloca a valle del retrieval, non al suo posto.

Il terzo è l'analisi di log e l'incident response: i log di produzione sono il caso ideale, perché ad altissima ripetitività. Il quarto, più strategico, riguarda chi usa le CLI in abbonamento: i piani flat di Claude Code, Codex o Copilot CLI hanno quote d'uso, e riducendo i token inviati a ogni turno la stessa quota dura di più. Il progetto supporta esplicitamente questa modalità, con una procedura dedicata al traffico in abbonamento di Copilot CLI.

Come funziona

Headroom si adotta in quattro modi, a seconda di quanto si vuole intervenire sul proprio stack.

• Wrap di un agente esistente — il percorso più rapido: headroom wrap claude (oppure codex, aider, opencode, goose, cline e altri) avvia la CLI abituale instradando il traffico attraverso il proxy locale. Zero modifiche al codice, e si torna indietro con headroom unwrap.
• Proxy OpenAI-compatibile — headroom proxy --port 8787 espone un endpoint locale: basta puntare l'SDK o il client verso localhost:8787. Funziona con qualsiasi linguaggio e con qualunque client compatibile con l'API OpenAI.
• Libreria — in Python o TypeScript si chiama compress(messages) nel punto esatto della pipeline in cui serve; esistono integrazioni pronte per LangChain e Vercel AI SDK.
• Server MCP — espone tre strumenti (headroom_compress, headroom_retrieve, headroom_stats) a qualunque client Model Context Protocol, per una compressione su richiesta.

Sotto il cofano, il flusso è orchestrato da pochi componenti. Un ContentRouter riconosce il tipo di contenuto e sceglie il compressore giusto: SmartCrusher per JSON e output strutturati, CodeCompressor con analisi AST per i sorgenti (Python, JavaScript, Go, Rust, Java, C++), Kompress-v2-base — un modello pubblicato su HuggingFace e addestrato su tracce agentiche — per la prosa. Il CacheAligner stabilizza i prefissi dei prompt in modo che le cache KV dei provider facciano effettivamente hit: un risparmio che si somma a quello della compressione. Infine il meccanismo CCR (Content-Compressed Retrieval) archivia gli originali in locale: se il modello ha bisogno del testo integrale, lo recupera con headroom_retrieve. Nulla viene buttato via.

A questi si aggiungono due funzioni accessorie: una memoria condivisa tra agenti diversi (con deduplica automatica, su SQLite) e headroom learn, che analizza le sessioni fallite e scrive correzioni nei file di istruzioni della CLI. Utili, ma da valutare caso per caso: chi dispone già di un sistema di memoria aziendale probabilmente le disattiverà. Da segnalare infine la riduzione dei token in uscita: Headroom lima le risposte verbose del modello e, con onestà rara, dichiara che quel risparmio è una stima controfattuale con intervallo di confidenza, non un numero inventato; chi vuole una misura vera può lasciare il 10% del traffico non compresso come gruppo di controllo.

Quanto si risparmia davvero

I numeri pubblicati dal progetto parlano di 60-95% di token in meno a parità di risposte, con benchmark su dataset come GSM8K e TruthfulQA a sostegno della qualità preservata. Le tabelle ufficiali offrono però un quadro più sfumato e credibile: 92% su ricerca nel codice e debugging di incident, 73% su triage di issue GitHub, 47% su esplorazione di codebase, dove quasi ogni riga è informativa e c'è poco da comprimere. La regola empirica è chiara: più il contenuto è ripetitivo (log, JSON, risultati di ricerca), maggiore il risparmio. Restano benchmark prodotti dal manutentore: la cosa giusta da fare è misurare sulle proprie sessioni reali con headroom stats, che mostra token risparmiati e stima del costo evitato.

Perché conta per founder, PMI e agenzie

Per una software house o un'agenzia italiana che ha adottato le CLI di coding, il costo del contesto è una voce concreta: si traduce in fatture API oppure in quota d'abbonamento bruciata a metà pomeriggio, con il team fermo ad aspettare il reset. Headroom è interessante perché tratta i token come un budget di sistema e non come un problema di prompt engineering: è infrastruttura trasversale, si installa in dieci minuti, non richiede account esterni e non sposta i dati fuori dalla macchina — un punto tutt'altro che banale in ottica GDPR e per il codice coperto da NDA. In più è agnostico rispetto al provider: funziona con Anthropic, OpenAI, Bedrock e con i modelli locali, quindi non vincola nessuna scelta futura.

Limiti e avvertenze

Tre caveat onesti. Primo: instradare il traffico di un abbonamento attraverso un proxy locale va verificato rispetto ai termini di servizio del provider. Secondo: su contenuti già densi il risparmio può essere modesto, e una compressione mal calibrata rischia di tagliare dettagli utili — il recupero degli originali mitiga il rischio, ma va testato sui propri task. Terzo: in ambienti aziendali con ispezione SSL o macchine offline servono accorgimenti (il download del modello di compressione da HuggingFace e del runtime ONNX è documentato, ma va pianificato).

Dove trovarlo

Il progetto vive su GitHub all'indirizzo github.com/headroomlabs-ai/headroom (il vecchio repository chopratejas/headroom reindirizza), con documentazione completa, model card di Kompress su HuggingFace e pacchetti su PyPI (headroom-ai) e npm. La prova consigliata è semplice: installarlo, fare wrap della propria CLI, svolgere un task reale e poi leggere headroom stats. Dieci minuti per scoprire quanto del proprio contesto fosse rumore.