Tokenjuice: Ottimizza i tuoi agenti AI per risparmiare token

Tokenjuice è un compatto deterministico per l'output del terminale, progettato per i flussi di lavoro degli agenti AI. Riceve il testo grezzo dopo l'esecuzione di comandi come git status, pnpm test o docker build e lo compatta in base a regole, riducendo lo spreco di token senza alterare il significato del comando. Il funzionamento è trasparente: l'output completo è disponibile solo se richiesto esplicitamente.

Cos'è tokenjuice?

Tokenjuice è un compatto deterministico per l'output del terminale, specifico per flussi di lavoro in cui gli agenti AI eseguono comandi e restituiscono il risultato a un modello linguistico. Quando un agente esegue comandi come git status, pnpm test, docker build, rg o pnpm --help, il terminale produce spesso trascrizioni lunghe e ridondanti. Tokenjuice intercetta l'output dopo l'esecuzione, lo elabora con regole programmabili e restituisce un payload più piccolo, mantenendo intatto il significato del comando.

Il vantaggio principale sta nel risparmio di token e nel miglioramento del contesto: meno testo inutile, meno riesecuzioni inutili e un passaggio più pulito tra strumenti diversi, senza introdurre magie nella shell. L'output grezzo resta disponibile solo se l'utente lo richiede esplicitamente con flag come --raw o --full, oppure se si attiva l'archiviazione degli artifact. Le regole sono ispezionabili in JSON, non dipendono da "vibrazioni" del LLM, e le integrazioni con gli host sono wrapper sottili attorno allo stesso core di riduzione, invece di logiche adapter monolitiche.

Integrazioni host

Tokenjuice si integra con decine di client e ambienti per agenti. L'installazione avviene tramite comandi specifici che scrivono hook o file di configurazione nella directory corretta. Di seguito le integrazioni supportate e quelle in beta.

Integrazioni supportate

Logo	Client	Installa	Hook file
	Claude Code	tokenjuice install claude-code	~/.claude/settings.json
	CodeBuddy	tokenjuice install codebuddy	~/.codebuddy/settings.json
	Codex CLI	tokenjuice install codex	~/.codex/hooks.json
	Cursor	tokenjuice install cursor	~/.cursor/hooks.json
	Droid (Factory CLI)	tokenjuice install droid	~/.factory/settings.json
	GitHub Copilot CLI	tokenjuice install copilot-cli	~/.copilot/hooks/tokenjuice-cli.json
	OpenClaw	openclaw config set plugins.entries.tokenjuice.enabled true	~/.openclaw/openclaw.json
	OpenCode	tokenjuice install opencode	~/.config/opencode/plugins/tokenjuice.js
	pi	tokenjuice install pi	~/.pi/agent/extensions/tokenjuice.js
	VS Code Copilot Chat	tokenjuice install vscode-copilot	~/.copilot/hooks/tokenjuice-vscode.json

Integrazioni beta

Logo	Client	Installa	Hook file
	AdaL CLI	tokenjuice install adal	AGENTS.md
	Aether	tokenjuice install aether	.aether/tokenjuice.md / .aether/settings.json
	aictl	tokenjuice install aictl	AICTL.md
	AI Memory Protocol	tokenjuice install ai-memory-protocol	.memories/memory/preferences.rst
	Aider	tokenjuice install aider	CONVENTIONS.tokenjuice.md
	Agent Layer	tokenjuice install agent-layer	.agent-layer/instructions/tokenjuice.md; eseguire al sync dopo installa/disinstalla
	AgentInit	tokenjuice install agentinit	AGENTS.md; eseguire agentinit sync dopo installa/disinstalla
	Agentlink	tokenjuice install agentlink	AGENTS.md; eseguire agentlink sync dopo installa/disinstalla
	Agentloom	tokenjuice install agentloom	.agents/rules/tokenjuice-agentloom.md; eseguire agentloom sync dopo installa/disinstalla

L'elenco completo include oltre 55 tool, tra cui Amazon Q Developer CLI, Amp, Avante.nvim, Baz, Bito, Blackbox CLI, Blocks, Coder Agents, Continue, Droid, gptme, JetBrains AI Assistant, Kimi, Kilo Code, OpenHands, Plandex, Qodo, Replit, Warp e molti altri. Per un elenco esaustivo consultare la documentazione ufficiale.

Installazione

Il pacchetto è disponibile tramite npm, pnpm, yarn o Homebrew:

shellCopia
npm install -g tokenjuice
# oppure
pnpm add -g tokenjuice
# oppure
yarn global add tokenjuice
# oppure
brew tap vincentkoc/tap
brew install tokenjuice

Dopo l'installazione, si possono esplorare i comandi disponibili:

shellCopia
tokenjuice --help
tokenjuice --version
tokenjuice install [client...]
tokenjuice uninstall [client...]
tokenjuice ls
tokenjuice cat <artifact-id>
tokenjuice verify
tokenjuice discover
tokenjuice doctor
tokenjuice doctor hooks
tokenjuice stats
tokenjuice stats --timezone utc

Per OpenClaw, il supporto è integrato nel prodotto stesso. Non eseguire tokenjuice install openclaw; abilitare invece il plugin incluso:

shellCopia
openclaw config set plugins.entries.tokenjuice.enabled true

Questa operazione richiede OpenClaw versione 2026.4.22 o successiva.

Comandi principali

Tokenjuice offre tre superfici operative:

• reduce: compatta testo già esistente, letto da file o stdin.
• wrap: esegue un comando, osserva l'output e lo compatta prima di restituirlo.
• reduce-json: interfaccia macchina per host adapter, con input/output sempre in JSON.

Esempio di utilizzo di wrap:

shellCopia
tokenjuice wrap -- pnpm test
tokenjuice wrap --raw -- pnpm --help   # output grezzo, senza compattazione
tokenjuice wrap --store -- git status  # salva l'artifact per uso successivo

Panoramica tecnica

Il motore di riduzione è basato su regole, definite in JSON. Le regole predefinite risiedono in src/rules del repository. Gli utenti possono sovrascriverle in ~/.config/tokenjuice/rules (livello utente) oppure a livello di progetto in .tokenjuice/rules. Gli strati successivi prevalgono sui precedenti in base all'ID della regola. Le regole classificano l'output, normalizzano le righe, mantengono o scartano pattern, contano fatti e trattengono porzioni iniziali/finali deterministiche.

Gli adapter host applicano anche una policy di "inventario sicuro": le letture esatte di contenuti di file restano grezze; i comandi di inventario del repository (come git status o rg) possono essere compattati; le sequenze di comandi miste o pericolose rimangono grezze.

Comandi utili per la manutenzione:

shellCopia
tokenjuice verify --fixtures
tokenjuice discover
tokenjuice doctor hooks
tokenjuice stats --timezone utc

Formato JSON per adapter

Il comando reduce-json è l'interfaccia per gli adapter host. Accetta JSON da stdin o da file e scrive sempre JSON su stdout. La specifica dettagliata è nel file spec.md del repository.

Esempio di payload atteso:

jsonCopia
{
  "toolName": "exec",
  "command": "pnpm test",
  "argv": ["pnpm", "test"],
  "combinedText": "RUN  v3.2.4 /repo\n...",
  "exitCode": 1
}

Documentazione

• Specifiche (spec.md)
• Regole di riduzione (rules.md)
• Playbook di integrazione
• Guide specifiche per ogni client (oltre 50) nel repository
• Sicurezza (SECURITY.md)

Stato del progetto

Tokenjuice è una base utilizzabile per la riduzione dei token, con diagnostica e un set crescente di riduttori. Attualmente il focus è sulla copertura più ampia e sulla messa a punto delle regole.

💙 Sviluppato da Vincent Koc.