tokenjuice 🧃

lean output compaction for terminal-heavy agent workflows.

what is tokenjuice?

tokenjuice is a deterministic output compactor for terminal-heavy agent workflows. agents and harnesses run noisy commands like git status, pnpm test, docker build, rg, or pnpm --help; tokenjuice keeps the command semantics untouched, observes the output after execution, and returns a smaller payload built from rule-driven reducers instead of dumping the whole wall of terminal text back into context.

the point is leverage: less transcript waste, fewer useless reruns, and cleaner handoff between tools without making the shell magical. raw output stays available only when you explicitly ask for it through --raw / --full or opt-in artifact storage (one exception: the pi extension stores the raw bytes of every rewrite, so tokenjuice cat can always recover them; set TOKENJUICE_ARTIFACT_DIR to choose where), rules stay inspectable JSON instead of LLM vibes, and host integrations stay thin wrappers around the same core reducer instead of becoming one-off adapter logic.

host integrations

For provider-based front ends, see T3 Code configuration and verification. QClaw migration guidance covers its transition to WorkBuddy.

supported integrations:

| Logo | Client | Install | 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/hooks.json or legacy settings | | | GitHub Copilot CLI | tokenjuice install copilot-cli | ~/.copilot/hooks/tokenjuice-cli.json | | | OpenClaw | openclaw plugins install @openclaw/tokenjuice | ~/.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 |

beta integrations:

| Logo | Client | Install | 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; run al sync after install or uninstall | | | AgentInit | tokenjuice install agentinit | AGENTS.md; run agentinit sync after install or uninstall | | | Agentlink | tokenjuice install agentlink | AGENTS.md; run agentlink sync after install or uninstall | | | Agentloom | tokenjuice install agentloom | .agents/rules/tokenjuice-agentloom.md; run agentloom sync after install or uninstall | | | agents-cli | tokenjuice install agents-cli | ~/.agents/memory/AGENTS.md; run agents sync after install or uninstall | | | AGENTS.md | tokenjuice install agents-md | AGENTS.md | | | agents.ge | tokenjuice install agentsge | .agents/rules/tokenjuice-agentsge.md | | | AgentsMesh | tokenjuice install agentsmesh | .agentsmesh/rules/tokenjuice.md; run agentsmesh generate after install or uninstall | | | Amazon Q Developer CLI / Kiro compatibility | tokenjuice install amazon-q | .amazonq/rules/tokenjuice.md | | | Amp | tokenjuice install amp | AGENTS.md / AGENT.md / CLAUDE.md | | | Google Antigravity | tokenjuice install antigravity | .agents/rules/tokenjuice.md | | | anywhere-agents | tokenjuice install anywhere-agents | AGENTS.local.md; run anywhere-agents after install or uninstall | | | Augment | tokenjuice install augment | .augment/rules/tokenjuice.md | | | Avante.nvim | tokenjuice install avante | avante.md | | | Baz | tokenjuice install baz | .baz/skills/tokenjuice/SKILL.md | | | Bito | tokenjuice install bito | .bito.yaml / .bito/tokenjuice.md | | | Blackbox CLI | tokenjuice install blackbox | .blackbox/skills/tokenjuice/SKILL.md | | | Blocks | tokenjuice install blocks | .agents/skills/tokenjuice-blocks/SKILL.md | | | Clawdbot | tokenjuice install clawdbot | skills/tokenjuice/SKILL.md | | | IBM Bob Shell | tokenjuice install bob | AGENTS.md | | | Builder | tokenjuice install builder | .builder/rules/tokenjuice.mdc | | | Charlie | tokenjuice install charlie | AGENTS.md | | | Cline | tokenjuice install cline | ~/Documents/Cline/Hooks/tokenjuice-post-tool-use | | | CodeAnt | tokenjuice install codeant | .codeant/instructions.json | | | Codebuff | tokenjuice install codebuff | AGENTS.md | | | Codegen | tokenjuice install codegen | AGENTS.md | | | Coder Agents | tokenjuice install coder-agents | .agents/skills/tokenjuice/SKILL.md | | | CodeRabbit | tokenjuice install coderabbit | .coderabbit.yaml | | | Command Code | tokenjuice install command-code | ~/.commandcode/settings.json / .commandcode/settings.json | | | Continue | tokenjuice install continue | .continue/rules/tokenjuice.md | | | Crush | tokenjuice install crush | .crush/skills/tokenjuice/SKILL.md | | | Deep Agents Code | tokenjuice install deepagents | .deepagents/AGENTS.md | | | Devin for Terminal | tokenjuice install devin | .devin/hooks.v1.json | | | dot-agents | tokenjuice install dot-agents | ~/.agents/rules/global/rules.mdc; run dot-agents sync after install or uninstall | | | Docker Agent | tokenjuice install docker-agent | .docker-agent/tokenjuice.md | | | ECA | tokenjuice install eca | .eca/skills/tokenjuice/SKILL.md | | | Elyra | tokenjuice install elyra | .elyra/skills/tokenjuice/SKILL.md | | | Firebase Studio | tokenjuice install firebase-studio | .idx/airules.md | | | ForgeCode | tokenjuice install forgecode | AGENTS.md | | | Gemini CLI | tokenjuice install gemini-cli | ~/.gemini/settings.json | | | GitLab Duo Agent Platform | tokenjuice install gitlab-duo | .gitlab/duo/chat-rules.md | | | Goose | tokenjuice install goose | .goosehints | | | Greptile | tokenjuice install greptile | .greptile/rules.md | | | Grok Build | tokenjuice install grok-build | AGENTS.md | | | Grok Bot | tokenjuice install grok-bot | experimental local rule; cloud skill workflow | | | Community Grok CLI | tokenjuice install grok-cli | ~/.grok/user-settings.json | | | gptme | tokenjuice install gptme | AGENTS.md | | | GitHub Copilot coding agent | tokenjuice install copilot-agent | .github/hooks/tokenjuice-agent.json | | | Jean2 | tokenjuice install jean2 | AGENTS.md | | | JetBrains AI Assistant | tokenjuice install jetbrains-ai | .aiassistant/rules/tokenjuice.md | | | Junie | tokenjuice install junie | .junie/AGENTS.md | | | Jules | tokenjuice install jules | AGENTS.md | | | LeanCTL | tokenjuice install leanctl | .leanctl/instructions.md | | | Kimi Code CLI | tokenjuice install kimi | ~/.kimi/config.toml | | | Kiro | tokenjuice install kiro | .kiro/steering/tokenjuice.md | | | Kilo Code | tokenjuice install kilo | kilo.jsonc or .kilo/kilo.jsonc + .kilo/rules/tokenjuice.md | | | LocalCode | tokenjuice install localcode | ~/.localcode/plugins/tokenjuice/ | | | mcp-agent | tokenjuice install mcp-agent | .mcp-agent/agents/tokenjuice.md | | | mini-SWE-agent | tokenjuice install mini-swe-agent | .mini-swe-agent/tokenjuice.yaml | | | SWE-agent | tokenjuice install swe-agent | .swe-agent/tokenjuice.yaml | | | Stagewise | tokenjuice install stagewise | .stagewise/skills/tokenjuice/SKILL.md | | | Mistral Vibe | tokenjuice install mistral-vibe | AGENTS.md | | | Mux | tokenjuice install mux | .mux/tool_post | | | NovaKit CLI | tokenjuice install novakit | NOVAKIT.md | | | Knowns | tokenjuice install knowns | KNOWNS.md | | | Ona Agent | tokenjuice install ona | .ona/skills/tokenjuice/SKILL.md | | | OpenHands | tokenjuice install openhands | .openhands/hooks.json | | | Open Interpreter | tokenjuice install open-interpreter | AGENTS.md | | | Open WebUI | tokenjuice install openwebui | .openwebui/tools/tokenjuice_compact.py | | | pi-go | tokenjuice install pi-go | .pi/skills/tokenjuice/SKILL.md | | | Plandex | tokenjuice install plandex | PLANDEX.tokenjuice.md | | | Qodo Code Review | tokenjuice install qodo | .pr_agent.toml | | | OpenCode V2 | tokenjuice install opencode-v2 | foreground shell result replacement; v2.0.18 contract, live acceptance unqualified | | | Antigma Ante | tokenjuice install ante | project AGENTS.md or CLAUDE.md | | | Qoder CLI | tokenjuice install qoder-cli | native PostToolUse; qoder retains AGENTS.md guidance | | QoderWork | QoderWork skills | tokenjuice install qoderwork | guidance skill at ~/.qoderwork/skills/tokenjuice/SKILL.md | | QwenWork | QwenWork | tokenjuice install qwenwork | guidance skill at ~/.qwenwork/skills/tokenjuice/SKILL.md | | | Qwen Code | tokenjuice install qwen-code | .qwen/settings.json | | | Replit Agent | tokenjuice install replit | replit.md | | | Roo Code | tokenjuice install roo | .roo/rules/tokenjuice.md | | | Rovo Dev CLI | tokenjuice install rovo | AGENTS.md | | | Ruler | tokenjuice install ruler | .ruler/tokenjuice.md | | | Tabby | tokenjuice install tabby | ~/.tabby/config.toml | | | Tabnine CLI | tokenjuice install tabnine | TABNINE.md | | | Trae | tokenjuice install trae | .trae/rules/project_rules.md | | | UiPath for Coding Agents | tokenjuice install uipath | AGENTS.md | | | Warp | tokenjuice install warp | AGENTS.md / WARP.md | | | Windsurf | tokenjuice install windsurf | .windsurf/rules/tokenjuice.md | | | Zed | tokenjuice install zed | .rules | | | Zencoder | tokenjuice install zencoder | .zencoder/rules/tokenjuice.md |

install

npm install -g tokenjuice
or
pnpm add -g tokenjuice
or
yarn global add tokenjuice
or (the vincentkoc/tap alias maps to github.com/vincentkoc/homebrew-tap)
brew tap vincentkoc/tap
brew install tokenjuice

Homebrew publication is owned by the Tokenjuice workflow in the canonical vincentkoc/homebrew-tap repository. Release maintainers dispatch it manually with the published tag until GitHub App automation lands.

then:

tokenjuice --help
tokenjuice --version
tokenjuice install [adal|aether|aictl|ai-memory-protocol|aider|agent-layer|agentinit|agentlink|agentloom|agents-cli|agents-md|agentsge|agentsmesh|amazon-q|amp|ante|antigravity|anywhere-agents|augment|avante|baz|bito|blackbox|blocks|clawdbot|bob|builder|charlie|codex|claude-code|cline|codeant|codebuff|codegen|coder-agents|coderabbit|codebuddy|command-code|continue|copilot-agent|crush|cursor|deepagents|devin|dot-agents|docker-agent|droid|eca|elyra|firebase-studio|forgecode|gemini-cli|gitlab-duo|goose|greptile|grok-build|grok-cli|gptme|jean2|jetbrains-ai|junie|jules|leanctl|kimi|kiro|kilo|localcode|mcp-agent|mini-swe-agent|swe-agent|stagewise|mistral-vibe|mux|novakit|knowns|ona|openhands|open-interpreter|openwebui|pi|pi-go|opencode|opencode-v2|plandex|qodo|qoder|qoder-cli|qoderwork|qwen-code|qwenwork|replit|roo|rovo|ruler|tabby|tabnine|trae|uipath|vscode-copilot|warp|windsurf|copilot-cli|zed|zencoder]
tokenjuice uninstall [adal|aether|aictl|ai-memory-protocol|aider|agent-layer|agentinit|agentlink|agentloom|agents-cli|agents-md|agentsge|agentsmesh|amazon-q|amp|ante|antigravity|anywhere-agents|augment|avante|baz|bito|blackbox|blocks|clawdbot|bob|builder|charlie|codex|claude-code|cline|codeant|codebuff|codegen|coder-agents|coderabbit|codebuddy|command-code|continue|copilot-agent|crush|cursor|deepagents|devin|dot-agents|docker-agent|droid|eca|elyra|firebase-studio|forgecode|gemini-cli|gitlab-duo|goose|greptile|grok-build|grok-cli|gptme|jean2|jetbrains-ai|junie|jules|leanctl|kimi|kiro|kilo|localcode|mcp-agent|mini-swe-agent|swe-agent|stagewise|mistral-vibe|mux|novakit|knowns|ona|openhands|open-interpreter|openwebui|pi|pi-go|opencode|opencode-v2|plandex|qodo|qoder|qoder-cli|qoderwork|qwen-code|qwenwork|replit|roo|rovo|ruler|tabby|tabnine|trae|uipath|vscode-copilot|warp|windsurf|copilot-cli|zed|zencoder]

Pi can leave output from selected commands untouched. Repeat --skip-command for each executable name:

tokenjuice install pi --skip-command rtk

OpenClaw loads the external @openclaw/tokenjuice plugin. Install and enable it with the OpenClaw CLI:

openclaw plugins install @openclaw/tokenjuice
openclaw config set plugins.entries.tokenjuice.enabled true
openclaw gateway restart

Do not run tokenjuice install openclaw. Match the plugin release to your OpenClaw version; the plugin declares its host compatibility requirements. See the OpenClaw Tokenjuice guide.

commands

tokenjuice --help
tokenjuice --version
tokenjuice reduce [file]
tokenjuice reduce-json [file]
tokenjuice wrap -- <command> [args...]
tokenjuice wrap --no-stats -- <command> [args...]
tokenjuice wrap --raw -- <command> [args...]
tokenjuice wrap --store -- <command> [args...]
tokenjuice install [adal|aether|aictl|ai-memory-protocol|aider|agent-layer|agentinit|agentlink|agentloom|agents-cli|agents-md|agentsge|agentsmesh|amazon-q|amp|ante|antigravity|anywhere-agents|augment|avante|baz|bito|blackbox|blocks|clawdbot|bob|builder|charlie|codex|claude-code|cline|codeant|codebuff|codegen|coder-agents|coderabbit|codebuddy|command-code|continue|copilot-agent|crush|cursor|deepagents|devin|dot-agents|docker-agent|droid|eca|elyra|firebase-studio|forgecode|gemini-cli|gitlab-duo|goose|greptile|grok-build|grok-cli|gptme|jean2|jetbrains-ai|junie|jules|leanctl|kimi|kiro|kilo|localcode|mcp-agent|mini-swe-agent|swe-agent|stagewise|mistral-vibe|mux|novakit|knowns|ona|openhands|open-interpreter|openwebui|pi|pi-go|opencode|opencode-v2|plandex|qodo|qoder|qoder-cli|qoderwork|qwen-code|qwenwork|replit|roo|rovo|ruler|tabby|tabnine|trae|uipath|vscode-copilot|warp|windsurf|copilot-cli|zed|zencoder]
tokenjuice install [adal|aether|aictl|ai-memory-protocol|aider|agent-layer|agentinit|agentlink|agentloom|agents-cli|agents-md|agentsge|agentsmesh|amazon-q|amp|ante|antigravity|anywhere-agents|augment|avante|baz|bito|blackbox|blocks|clawdbot|bob|builder|charlie|codex|claude-code|cline|codeant|codebuff|codegen|coder-agents|coderabbit|codebuddy|command-code|continue|copilot-agent|crush|cursor|deepagents|devin|dot-agents|docker-agent|droid|eca|elyra|firebase-studio|forgecode|gemini-cli|gitlab-duo|goose|greptile|grok-build|grok-cli|gptme|jean2|jetbrains-ai|junie|jules|leanctl|kimi|kiro|kilo|localcode|mcp-agent|mini-swe-agent|swe-agent|stagewise|mistral-vibe|mux|novakit|knowns|ona|openhands|open-interpreter|openwebui|pi|pi-go|opencode|opencode-v2|plandex|qodo|qoder|qoder-cli|qoderwork|qwen-code|qwenwork|replit|roo|rovo|ruler|tabby|tabnine|trae|uipath|vscode-copilot|warp|windsurf|copilot-cli|zed|zencoder] --local
tokenjuice uninstall [adal|aether|aictl|ai-memory-protocol|aider|agent-layer|agentinit|agentlink|agentloom|agents-cli|agents-md|agentsge|agentsmesh|amazon-q|amp|ante|antigravity|anywhere-agents|augment|avante|baz|bito|blackbox|blocks|clawdbot|bob|builder|charlie|codex|claude-code|cline|codeant|codebuff|codegen|coder-agents|coderabbit|codebuddy|command-code|continue|copilot-agent|crush|cursor|deepagents|devin|dot-agents|docker-agent|droid|eca|elyra|firebase-studio|forgecode|gemini-cli|gitlab-duo|goose|greptile|grok-build|grok-cli|gptme|jean2|jetbrains-ai|junie|jules|leanctl|kimi|kiro|kilo|localcode|mcp-agent|mini-swe-agent|swe-agent|stagewise|mistral-vibe|mux|novakit|knowns|ona|openhands|open-interpreter|openwebui|pi|pi-go|opencode|opencode-v2|plandex|qodo|qoder|qoder-cli|qoderwork|qwen-code|qwenwork|replit|roo|rovo|ruler|tabby|tabnine|trae|uipath|vscode-copilot|warp|windsurf|copilot-cli|zed|zencoder]
tokenjuice ls
tokenjuice cat <artifact-id>
tokenjuice verify
tokenjuice discover
tokenjuice doctor
tokenjuice doctor hooks
tokenjuice doctor pi
tokenjuice doctor opencode
tokenjuice stats
tokenjuice stats --timezone utc
tokenjuice stats --limit 1000

overview

tokenjuice has three surfaces. reduce compacts text that already exists, wrap runs a command and compacts the observed output, and reduce-json gives host adapters a stable machine protocol. host integrations are intentionally thin: they install a hook, extension, rule, or guidance file; call the shared compactor; and return compacted context through the host's native surface. use tokenjuice doctor hooks to check installed wiring, tokenjuice doctor for one integration, and tokenjuice install --local when validating the current repo build before release.

the reduction engine is rule-driven. built-in JSON rules live in src/rules, user overrides live in ~/.config/tokenjuice/rules, and project overrides live in .tokenjuice/rules; later layers override earlier ones by rule id. rules classify command output, normalize lines, keep or drop patterns, count facts, and retain deterministic head/tail slices. host adapters also apply a narrow safe-inventory policy: exact file-content reads stay raw, standalone repository inventory commands can compact, and unsafe mixed command sequences stay raw. size and prose shape do not change that: a file read over 4,000 characters stays raw, while a command whose text contains package-lock.json is the exception and may be replaced by the package-lock summary.

when a reducer gets it wrong or the task needs untouched bytes, use the explicit bypass:

tokenjuice wrap --raw -- pnpm --help
tokenjuice wrap --full -- git status

statistics use bounded metadata segments and exclude pre-existing JSON sidecars. page with --limit and the returned --cursor; output reports when coverage is partial. set TOKENJUICE_STATS=off or pass --no-stats to stop metadata and hook-debug telemetry writes. --raw and --full return untouched bytes; artifact retention remains opt-in through --store.

useful maintenance commands:

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

adapter JSON

reduce-json is the machine-facing adapter command. it reads JSON from stdin or a file and always writes JSON to stdout; see the spec for envelope options and adapter behavior.

direct payload:

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

docs

• Adapter support and verification
• OpenCode V2 integration

• spec
• rules
• integration playbook
• AdaL CLI integration
• Aether integration
• Agent Layer integration
• AgentInit integration
• Agentlink integration
• Agentloom integration
• agents-cli integration
• AGENTS.md integration
• agents.ge integration
• AgentsMesh integration
• Amp integration
• Amazon Q integration
• aictl integration
• AI Memory Protocol integration
• Antigravity integration
• anywhere-agents integration
• Augment integration
• Baz integration
• Bito integration
• Blackbox integration
• Blocks integration
• Clawdbot integration
• IBM Bob integration
• Builder integration
• Charlie integration
• GitHub Copilot coding agent integration
• CodeAnt integration
• Codebuff integration
• Codegen integration
• Coder Agents integration
• CodeRabbit integration
• Command Code integration
• Crush integration
• Cursor integration
• CodeBuddy integration
• Deep Agents Code integration
• Devin integration
• dot-agents integration
• Docker Agent integration
• ECA integration
• Elyra integration
• ForgeCode integration
• Goose integration
• Greptile integration
• Grok Build integration
• Grok CLI integration
• gptme integration
• Jean2 integration
• JetBrains AI Assistant integration
• LeanCTL integration
• Kimi integration
• Kiro integration
• Kilo Code integration
• LocalCode integration
• mcp-agent integration
• mini-SWE-agent integration
• SWE-agent integration
• Stagewise integration
• Mistral Vibe integration
• Mux integration
• NovaKit integration
• Knowns integration
• Ona integration
• Open Interpreter integration
• Open WebUI integration
• pi-go integration
• Plandex integration
• Qodo integration
• WorkBuddy desktop skill
• Doubao Work skill
• AutoClaw workflow
• QoderWork integration
• QwenWork integration
• Qoder integration
• Qwen Code integration
• Replit integration
• Roo Code integration
• Rovo integration
• Ruler integration
• Tabby integration
• Tabnine integration
• Trae integration
• UiPath integration
• Warp integration
• Windsurf integration
• Zencoder integration
• security

status

usable foundation for token reduction with diagnostics and a growing reducer set, now focused on deeper coverage and tuning.

💙 built by Vincent Koc.