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.

Caveman e Headroom: qual è la differenza?

Caveman e Headroom cercano entrambi di ridurre token superflui, ma intervengono principalmente in due punti diversi del flusso. Caveman nasce come skill o plugin che impone all’agente uno stile di risposta più breve; Headroom nasce come layer infrastrutturale che comprime il contesto prima che venga letto dal modello.

La distinzione non è più assoluta: Caveman include strumenti per comprimere file di memoria e descrizioni MCP, mentre Headroom può applicare anche regole di brevità all’output. Per scegliere, devi quindi capire dove si concentra il consumo nel tuo caso.

• Caveman: riduce soprattutto i token di output eliminando preamboli, ripetizioni e prosa non necessaria.
• Headroom: riduce soprattutto i token di input comprimendo output dei tool, log, file, risultati RAG e cronologia.
• Caveman è principalmente una regola di comportamento installata nell’agente; Headroom è disponibile come proxy, libreria, middleware, MCP e wrapper.
• Caveman mantiene invariato il ragionamento dichiarando di rendere più corta la risposta; Headroom trasforma il contesto e conserva gli originali per il recupero reversibile.
• Puoi combinarli, ma devi misurare separatamente input, output e qualità: sovrapporre ottimizzazioni rende più difficile capire quale abbia causato un errore.

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

Headroom vs Caveman in pratica

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. Devi guardare i token consumati nella tua sessione e capire quale parte pesa di più.

Scegli Headroom quando

Il contesto in ingresso è grande: log, tool output, file, ricerche nel repository, cronologia o risultati RAG.

Scegli Caveman quando

Le risposte dell’agente sono troppo lunghe e vuoi tagliare preamboli, ripetizioni e spiegazioni non necessarie.

Puoi usarli insieme?

Sì, ma misura separatamente input, output e qualità. Se qualcosa peggiora, devi poter capire quale ottimizzazione ha introdotto il problema.

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 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]

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

Per una prova reversibile, termina il proxy e avvia l’agente direttamente, senza il comando headroom wrap. Verifica poi che configurazioni MCP o istruzioni globali aggiunte durante il setup non restino attive.

• 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.

# Avvia nuovamente Codex senza Headroom
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.