Come usare Headroom con Codex: tutorial e differenza con Caveman

Cosa fa Headroom

Headroom si posiziona tra il coding agent e il provider del modello. Riconosce il tipo di contenuto e applica strategie diverse a JSON, codice e testo, cercando di inviare una versione più compatta del contesto.

Il progetto supporta l’uso come libreria Python o TypeScript, proxy locale, server MCP e wrapper per agenti come Codex, Claude Code, Cursor, Aider e Copilot CLI.

• Comprime output dei comandi, log, file, risultati di ricerca e cronologia.
• Mantiene una cache locale degli originali per recuperarli quando servono.
• Può condividere memoria compressa fra agenti diversi.
• Espone statistiche per confrontare token originali e token inviati.

• Headroom: benchmark e contesto delle percentuali ↗

Caveman e Headroom: qual è la differenza?

La distinzione storica era semplice: la skill Caveman accorciava le risposte, mentre Headroom comprimeva il contesto in ingresso. Il confronto attuale deve però specificare quale componente usi.

Caveman 4 include anche compressione degli input e selezione di modello e livello di ragionamento. Headroom offre compressione del contesto e opzioni per ridurre l’output. Confrontare le due installazioni complete come se una agisse soltanto sulle risposte e l’altra soltanto sugli input sarebbe quindi fuorviante.

• Skill Caveman da sola: modifica lo stile delle risposte, senza richiedere l’intera suite.
• Suite Caveman: comprende anche proxy e altre ottimizzazioni; controlla i componenti attivi.
• Headroom: libreria, proxy, server MCP e wrapper; le funzioni effettive dipendono dalla configurazione.
• Una risposta più breve non dimostra che accuratezza e ragionamento siano rimasti equivalenti: verifica il risultato del task.
• Prova una trasformazione alla volta e registra input, output e qualità prima di combinarle.

• Repository ufficiale di Caveman ↗
• Repository ufficiale di Headroom ↗

Come impostare un confronto tra i due

La differenza più importante è dove avviene il risparmio. Se stai spendendo token perché l’agente legge log enormi, file lunghi e output ripetitivi, il problema è soprattutto input/context. Se invece il costo è causato da risposte troppo prolisse, il problema è soprattutto output.

Per questo non conviene scegliere solo in base alla promessa di riduzione percentuale. Annota versione e componenti attivi: una skill di stile, un proxy di compressione e un selettore di modelli sono interventi diversi.

Confronto sugli input

Usa gli stessi dati, modello e vincoli. Confronta compressione, richieste di recupero e completamento del task.

Confronto sullo stile

Mantieni invariato il contesto e confronta una normale istruzione di brevità con la skill di stile.

Confronto sulle installazioni complete

Registra anche modello scelto e livello di ragionamento: se cambiano, il risultato non misura la sola compressione.

Quando vale la pena provarlo

Ha meno valore per sessioni brevi, prompt piccoli o provider che stanno già gestendo bene la compattazione. Non usarlo come soluzione automatica prima di avere una baseline.

• Usi coding agent ogni giorno su repository medi o grandi.
• Le sessioni leggono molti log, risultati di ricerca o file ripetitivi.
• Raggiungi spesso limiti di contesto o di utilizzo.
• Vuoi confrontare più agenti mantenendo una memoria locale condivisa.
• Puoi misurare risultato, token e regressioni su task ripetibili.

Prima dell’installazione: crea una baseline

1. Scegli un repository non sensibile e un task rappresentativo.
2. Esegui il task senza Headroom e annota modello, durata e token consumati.
3. Registra quante volte l’agente deve rileggere file o chiedere altro contesto.
4. Salva il risultato della build, dei test e della review finale.
5. Ripeti poi lo stesso tipo di task con Headroom, senza cambiare modello o istruzioni.

Installazione

Headroom richiede Python 3.10 o successivo. Per una prova isolata conviene usare pipx oppure un virtual environment, evitando di installare pacchetti nel Python di sistema.

• Repository ufficiale su GitHub ↗
• Documentazione ufficiale ↗
• Pacchetto headroom-ai su PyPI ↗

# Controlla la versione di Python
python3 --version

# Installa Headroom in un ambiente isolato
pipx install --python python3.13 "headroom-ai[all]"

# Controlla che il comando sia disponibile
headroom --help
headroom update --check

Usarlo con Codex

Il wrapper avvia o riutilizza il proxy locale e configura il processo dell’agente affinché le richieste passino attraverso Headroom.

# Entra nel progetto che vuoi testare
cd percorso/del/progetto

# Avvia Codex attraverso Headroom
headroom wrap codex

# Dentro la sessione esegui un task normale.
# Al termine, esci dall'agente e controlla i risultati:
headroom doctor
headroom perf

Claude Code, Cursor e altri agenti

La stessa CLI espone wrapper dedicati. Il comportamento preciso può cambiare tra versioni, quindi controlla sempre l’help del comando installato.

# Claude Code
headroom wrap claude

# Cursor
headroom wrap cursor

# Aider
headroom wrap aider

# GitHub Copilot CLI
headroom wrap copilot

# Opzioni aggiornate per il tuo ambiente
headroom wrap --help

Proxy manuale e integrazione MCP

Se vuoi separare il ciclo di vita del proxy da quello dell’agente, puoi avviarlo manualmente. L’integrazione MCP aggiunge strumenti per comprimere, recuperare gli originali e leggere le statistiche.

# Avvia il proxy locale
headroom proxy --port 8787

# In un altro terminale installa gli strumenti MCP
headroom mcp install

# Verifica stato e risparmi
headroom perf

Come capire se sta funzionando

1. Conferma che il proxy riceva richieste e che headroom perf mostri attività.
2. Confronta token prima e dopo sullo stesso tipo di workload.
3. Controlla quante volte l’agente recupera o rilegge il contenuto originale.
4. Esegui gli stessi test e la stessa review usati nella baseline.
5. Ripeti su almeno tre task: ricerca nel codice, debugging con log e modifica multi-file.
6. Mantienilo soltanto se il risparmio netto non riduce affidabilità e velocità.

Task:
Modello:

Senza Headroom:
- token:
- durata:
- test passati:
- riletture:
- errori trovati in review:

Con Headroom:
- token:
- durata:
- test passati:
- recuperi/riletture:
- errori trovati in review:

Decisione:
[mantieni / configura meglio / rimuovi]

Esempio: il 20% sul payload può diventare un aumento dei token

Questo è un esempio aritmetico sintetico, non un test di Headroom. Supponi che la baseline richieda in tutto 20.000 token di input. Nel secondo caso la compressione riduce lo stesso payload a 16.000 token: sul solo payload il taglio è del 20%.

Se però i recuperi degli originali e le richieste aggiuntive introducono altri 6.000 token fatturati, l’input complessivo sale a 22.000 token: il 10% in più rispetto alla baseline. Questi 6.000 devono provenire dai conteggi del provider; non coincidono automaticamente con la dimensione di un file letto.

Per valutare la spesa servono anche output, token in cache e tariffe del modello. Per valutare l’utilità servono test e risultato finale. Un contatore di compressione misura una parte del flusso, non dimostra da solo che l’intera sessione sia diventata più economica.

• Headroom: significato dei contatori di risparmio ↗

Baseline, input totale: 20.000 token
Payload compresso:       16.000 token
Input aggiuntivo:         6.000 token
Totale del secondo caso: 22.000 token

Taglio del payload: (20.000 - 16.000) / 20.000 = 20%
Variazione totale:  (22.000 - 20.000) / 20.000 = +10%

Output e token in cache: da confrontare separatamente

Privacy e sicurezza

• Il proxy locale può vedere prompt, file e output dei tool che transitano nella sessione.
• La modalità local-first non impedisce al provider LLM di ricevere il contesto compresso.
• Gli originali possono essere conservati localmente per il recupero reversibile.
• Credenziali presenti nei log o nei file restano dati sensibili anche dopo la compressione.
• In ambienti aziendali devi verificare policy, conservazione, dipendenze e configurazione di rete.

Come tornare indietro

Uscire dal wrapper non dimostra che tutte le modifiche persistenti siano state rimosse. Per Codex, il progetto documenta headroom unwrap codex; prima di eseguirlo controlla l’help della versione installata. Poi confronta configurazione, MCP e istruzioni con la copia salvata prima della prova.

Se hai usato un’installazione persistente tramite deploy o install, controlla anche il relativo profilo: la semplice disinstallazione del pacchetto non sostituisce la procedura di rimozione del servizio e delle sue configurazioni.

• Controlla configurazione globale e locale dell’agente.
• Rimuovi soltanto le sezioni chiaramente create da Headroom.
• Conserva i dati della baseline per rivalutare una versione futura.

• Headroom: profili persistenti e rimozione ↗

# Controlla e rimuovi l'integrazione del wrapper Codex
headroom unwrap --help
headroom unwrap codex

# Dopo aver verificato il ripristino, avvia Codex direttamente
codex

# Controlla eventuali processi ancora in ascolto sulla porta del proxy
lsof -nP -iTCP:8787 -sTCP:LISTEN

# Se hai deciso di rimuoverlo
pipx uninstall headroom-ai

FAQ su Headroom con Codex

Headroom riduce sempre i costi?

No. Può ridurre i token inviati al modello, ma il beneficio reale dipende da task, modello, quantità di contesto e qualità della compressione.

Headroom sostituisce una buona istruzione di sistema?

No. Se il problema è un prompt confuso o uno scope troppo largo, la compressione non risolve il problema principale.

È sicuro usarlo su repository sensibili?

Va valutato come qualsiasi proxy o middleware che vede prompt, file e output dei tool. Prima va provato su dati non sensibili.

Come capisco se conviene tenerlo?

Confronta almeno tre task simili con e senza Headroom, guardando token, durata, test passati, riletture e qualità della review finale.