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

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

beta integrations:

| Logo | Client | Install | Hook file | | --- | --- | --- | --- | | | Aider | tokenjuice install aider | CONVENTIONS.tokenjuice.md | | | Avante.nvim | tokenjuice install avante | avante.md | | | Cline | tokenjuice install cline | ~/Documents/Cline/Hooks/tokenjuice-post-tool-use | | | Continue | tokenjuice install continue | .continue/rules/tokenjuice.md | | | Gemini CLI | tokenjuice install gemini-cli | ~/.gemini/settings.json | | | Junie | tokenjuice install junie | .junie/AGENTS.md | | | OpenHands | tokenjuice install openhands | .openhands/hooks.json | | | Zed | tokenjuice install zed | .rules |

install

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

then:

tokenjuice --help
tokenjuice --version
tokenjuice install [aider|avante|codex|claude-code|cline|codebuddy|continue|cursor|droid|gemini-cli|junie|openhands|pi|opencode|vscode-copilot|copilot-cli|zed]
tokenjuice uninstall [aider|avante|codex|cline|continue|droid|gemini-cli|junie|openhands|opencode|vscode-copilot|copilot-cli|zed]

OpenClaw support is bundled on the OpenClaw side. Do not run tokenjuice install openclaw; enable the bundled plugin instead:

openclaw config set plugins.entries.tokenjuice.enabled true

this requires OpenClaw 2026.4.22 or newer.

commands

tokenjuice --help
tokenjuice --version
tokenjuice reduce [file]
tokenjuice reduce-json [file]
tokenjuice wrap -- <command> [args...]
tokenjuice wrap --raw -- <command> [args...]
tokenjuice wrap --store -- <command> [args...]
tokenjuice install [aider|avante|codex|claude-code|cline|codebuddy|continue|cursor|droid|gemini-cli|junie|openhands|pi|opencode|vscode-copilot|copilot-cli|zed]
tokenjuice install [aider|avante|codex|claude-code|cline|codebuddy|continue|cursor|droid|gemini-cli|junie|openhands|pi|opencode|vscode-copilot|copilot-cli|zed] --local
tokenjuice uninstall [aider|avante|codex|cline|continue|droid|gemini-cli|junie|openhands|opencode|vscode-copilot|copilot-cli|zed]
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

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 <host> for one integration, and tokenjuice install <host> --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.

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

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

• spec
• rules
• integration playbook
• Cursor integration
• CodeBuddy 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.