Come Ispezionare le Interazioni API degli Agenti di Coding con ccglass

Cosa fa ccglass

ccglass è un reverse-proxy di logging locale e una dashboard web che ti permette di ispezionare ogni richiesta API che un coding agent invia a un provider di modelli linguistici. Molti strumenti (Claude Code, Codex, DeepSeek-TUI, ecc.) ignorano i proxy HTTP standard e non possono essere intercettati da mitmproxy o Charles senza patch delicate. ccglass funziona senza certificati CA o problemi di TLS pinning perché il client esegue comunque HTTPS verso l'API reale; viene intercettato solo un salto HTTP in chiaro verso localhost.

Puoi vedere il prompt di sistema completo, ogni schema degli strumenti, la cronologia completa dei messaggi, i dati di token/cache/costo e un diff turno per turno. È utile per capire cosa invia effettivamente il tuo agente al modello, per debuggare comportamenti legati ai prompt e per monitorare utilizzo e costi.

Per Iniziare

Requisiti: Node ≥ 18. Il proxy principale e la dashboard non hanno dipendenze runtime. Una funzionalità opzionale di auto-ispezione (MCP) include @modelcontextprotocol/sdk e zod quando si usa ccglass claude con strumenti MCP (disabilitala con --no-mcp).

Installa globalmente:

npm install -g ccglass

Esegui senza argomenti per scegliere un client in modo interattivo, oppure indica direttamente il client: ccglass claude, ccglass codex, ccglass deepseek, ecc. Lo strumento avvia un proxy, imposta la variabile d'ambiente appropriata per l'URL base, lancia il client e apre una dashboard nel tuo browser. L'output di esempio mostra gli URL del proxy e della dashboard.

Ispezionare Agenti e IDE

Avvia un'ispezione per un client specifico con argomenti opzionali da passare: ccglass claude [args...], ccglass codex [args...], e similmente per DeepSeek-TUI, Reasonix, Kimi e OpenCode.

Per strumenti arbitrari, usa il sottocomando generico run:

ccglass run --upstream https://my.custom.api/v1 --env-var MY_CUSTOM_BASE_URL -- my-tool

Puoi anche riutilizzare il formato di un provider con --provider. Per le estensioni IDE (Cursor, Cline, Continue) che permettono un URL base API personalizzato, usa ccglass proxy --provider openai o --provider claude. Questo avvia solo il proxy e la dashboard senza generare un processo figlio. L'output ti indica l'indirizzo del proxy da impostare nel tuo IDE e l'URL della dashboard.

Gestire le Catture

Rivisita le sessioni passate con ccglass view. Migra i vecchi log di progetto da ./.ccglass nell'archivio globale con ccglass migrate. Forza la migrazione delle catture esistenti al formato v2 content-addressed con ccglass repack [sessione] (ometti la sessione per riconfezionare tutto). Elimina una sessione e recupera i blob orfani con ccglass rm <sessione>.

Esporta una singola richiesta in formato raw, Markdown, JSON o HAR:

ccglass export <sessione>/<seq> --format raw|md|json|har

Le catture sono memorizzate in modo content-addressed: messaggi, strumenti e blocchi di sistema vengono scritti una sola volta in una directory blobs/ e referenziati tramite hash, mantenendo efficienti le sessioni lunghe.

Configurazione e Opzioni

Flag principali da linea di comando:

• --provider – forza il formato del provider per run
• --upstream – sovrascrive l'URL dell'API a monte
• --port, --proxy-port – porte per dashboard e proxy
• --dir – directory dei log (default ~/.ccglass/sessions/...)
• --no-open – non apre la dashboard nel browser
• --no-mcp – disabilita gli strumenti di auto-ispezione
• --no-settings-override – non forza Claude Code sul proxy
• --no-redact – mantiene i token di autenticazione non mascherati
• --env-var – sovrascrive la variabile d'ambiente utilizzata

Ogni provider imposta una variabile d'ambiente specifica: Claude usa ANTHROPIC_BASE_URL, Codex usa OPENAI_BASE_URL, DeepSeek-TUI usa DEEPSEEK_BASE_URL, ecc. Potrebbero essere richieste chiavi aggiuntive (es. ANTHROPIC_AUTH_TOKEN per Kimi). I token di autenticazione sono mascherati di default; usa --no-redact per mantenerli in chiaro. I log sono memorizzati in ~/.ccglass/sessions/<hash-percorso-progetto>/<sessione>/NNNN.json, con blob content-addressed.

Vincoli e limitazioni

• Codex in modalità login ChatGPT utilizza un trasporto WebSocket che aggira il proxy; passa alla modalità API‑key.
• I modelli di sottoscrizione integrati nell’IDE (ad es. api2.cursor.sh di Cursor) non possono essere intercettati; funziona solo la modalità BYOK con un URL base personalizzato.
• Gli endpoint diretti di AWS Bedrock falliscono perché SigV4 firma l’intestazione Host; ccglass stampa un avviso.
• OpenCode richiede che OPENAI_BASE_URL sia impostato in anticipo.
• Per Ollama o LM Studio su indirizzi diversi da quelli predefiniti, passa --upstream per puntare all’host:porta corretto.

Best Practices

• Esegui ccglass migrate quando ti viene richiesto per spostare i vecchi log nell’archivio globale.
• Mantieni --no-redact disattivato per evitare di esporre token di autenticazione.
• Usa ccglass view per rivedere sessioni passate senza rilanciare l’agente.
• Esporta le richieste per documentazione o debugging con --format.
• Quando utilizzi la funzionalità MCP di auto‑ispezione con Claude Code, tienila abilitata a meno che non ti serva.
• Se uno switcher di provider imposta già ANTHROPIC_BASE_URL, passa --no-settings-override per evitare sovrascritture duplicate.
• Tratta la directory dei log come sensibile indipendentemente dall’oscuramento.