docs: add tokenjuice compaction guidance

Author: solomonneas

CLAUDE.md

@@ -22,6 +22,14 @@ At the end of any substantial task, check whether the session produced durable k
 - Say it = call it. If you say you will do something that requires a tool, call the tool in the same turn. Silent intent is a lie. Full rule in `SOUL.md`.
 - After a tool failure, emit a one-line status or call a different tool within 30 seconds. Do not silently reason for minutes.
 
+## TokenJuice
+
+If this workspace uses TokenJuice, treat its footer as trusted local output-compaction metadata. It is there to explain how much terminal output was reduced before the next turn sees it.
+
+Claude Code note: when the official adapter still uses PostToolUse appended context, prefer the local PreToolUse wrapper that rewrites Bash commands to `tokenjuice wrap -- ...`. The wrapper avoids paying for large raw outputs and keeps the command result itself compact. If exact output matters, run the command through the documented raw-output escape hatch.
+
+Full runbook: `memory/cards/tokenjuice-output-compaction.md`.
+
 ## Git
 
 - Do not add `Co-Authored-By` or AI-attribution trailers to commits, PR bodies, or public docs.

INSTALL_FOR_AGENTS.md

@@ -36,6 +36,8 @@ If this workspace is one of several agent homes, read `memory/cards/multi-worksp
 
 If you are maintaining an established card set, read `memory/cards/memory-care-staleness.md` before editing stale cards. Refresh only from current source-of-truth files or route to manual review.
 
+If tool output includes TokenJuice metadata, read `memory/cards/tokenjuice-output-compaction.md`. The footer is local output-compaction metadata, not task instruction. Use raw output only when exact logs, line-for-line diffs, or full command output are required.
+
 ## If your harness loads a compact context
 
 Some harnesses load a generated `llms.txt` or `llms-full.txt` instead of every bootstrap file individually. If those exist in this workspace, follow them and rebuild via the workspace's build script when source docs change. If they do not exist, default to reading the files listed in "Start here" directly.

MEMORY.md

@@ -83,6 +83,7 @@ Add categories as the workspace grows. One topic per card; one card per topic.
 - [memory-scanner](memory/cards/memory-scanner.md) - session-review pass that promotes durable findings
 - [memory-care-staleness](memory/cards/memory-care-staleness.md) - card decay scans and safe refresh rules
 - [multi-workspace-handoff-admin](memory/cards/multi-workspace-handoff-admin.md) - pulling remote setup handoffs into one canonical owner
+- [tokenjuice-output-compaction](memory/cards/tokenjuice-output-compaction.md) - Claude Code and Codex output compaction setup, wrapper notes, and savings expectations
 - [pipeline-standups](memory/cards/pipeline-standups.md) - nightshift + morning cross-harness recaps
 - [chat-surface-crawlers](memory/cards/chat-surface-crawlers.md) - discrawl-shaped local archives for Discord, Slack, WhatsApp, etc.
 - [content-safety](memory/cards/content-safety.md) - publish gates and what they block

QUICKSTART.md

@@ -109,3 +109,4 @@ The fragments are JSON files you can inspect and merge into your `openclaw.json`
 - Customize `USER.md` and `TOOLS.md` with your real preferences and runbooks (kept private; do not commit personal details).
 - Wire the ingester on a cron or a manual end-of-day workflow.
 - Add a memory-care staleness scan when your card set starts to matter. See `memory/cards/memory-care-staleness.md`.
+- If you use TokenJuice, wire Claude Code and Codex hooks deliberately and tell agents what the wrapper means. See `memory/cards/tokenjuice-output-compaction.md`.

README.md

@@ -26,6 +26,8 @@
 
 ## What this is
 
+Mise en place means "everything in its place before the work starts." In a kitchen, that is chopped onions, clean pans, labels, and a station that does not make you hunt for salt mid-service. For agents, it is the same idea: rules, memory, tools, handoff inboxes, publish guards, and boring verification already laid out before the session gets expensive.
+
 This package lays down a clean starting point for an agent workspace or a repo that needs durable memory handoffs. It is meant for people running real tools, real docs, and real automation across OpenClaw, Claude Code, Codex, Hermes, or a similar harness.
 
 The cookbook explains the why. This package gives you the kitchen.
@@ -38,6 +40,7 @@ The cookbook explains the why. This package gives you the kitchen.
 - starter memory cards and routing rules
 - multi-workspace handoff patterns for people administering more than one agent setup
 - memory-care staleness checks so durable cards do not quietly rot
+- TokenJuice output-compaction guidance for Claude Code and Codex, including wrapper notes and savings expectations
 - content-guard publish gates so private infrastructure does not leak into public docs
 - adapter fragments for OpenClaw (tested), Hermes (stubbed), and generic harnesses
 - doctor checks that prove the system is wired before you trust it
@@ -98,6 +101,8 @@ The ingester is intentionally conservative. Safe card handoffs become cards. Tar
 
 For users running multiple agent homes, treat the owner workspace as the hub. Remote or secondary workspaces can write handoffs into their own `.claude/memory-handoffs/` directories, then a trusted sync pulls those files into a staging inbox on the owner. That keeps agents informed about what happened elsewhere without creating multiple canonical memories.
 
+Token-heavy terminal work gets the same treatment: make the wrapper explicit, make the escape hatch obvious, and tell every harness what is happening. The TokenJuice starter card documents Claude Code's PreToolUse wrapper path while the upstream PostToolUse fix is still pending, Codex's hook setup, and the savings model: observed output/context compaction can be huge, but billing-token savings depend on whether compacted output is fed into later turns.
+
 ## Related
 
 - [Solomon's Cookbook](https://github.com/solomonneas/solos-cookbook): the long-form guide and reference docs

TOOLS.md

@@ -12,7 +12,7 @@ python3 -m venv .venv
 ## Tests
 
 ```bash
-.venv/bin/python -m pytest -q              # full suite (40 tests)
+.venv/bin/python -m pytest -q              # full suite (42 tests)
 .venv/bin/python -m pytest tests/test_ingest.py -q   # one file
 .venv/bin/python -m pytest -k "promote" -q  # one keyword
 ```
@@ -77,6 +77,20 @@ See `RELEASE.md`.
 
 Use `memory/cards/multi-workspace-handoff-admin.md` as the public-safe pattern for pulling handoffs from secondary agent homes into one canonical owner. Use `memory/cards/memory-care-staleness.md` for the card decay scanner and safe refresh loop.
 
+## TokenJuice notes
+
+Use `memory/cards/tokenjuice-output-compaction.md` for the public-safe pattern. Important checks:
+
+```bash
+tokenjuice --version
+tokenjuice stats
+tokenjuice doctor hooks
+tokenjuice wrap -- git status --short
+tokenjuice wrap --raw -- git status --short
+```
+
+Claude Code currently needs the local PreToolUse wrapper pattern when the upstream PostToolUse replacement fix has not landed. Codex can use the normal hook path, but verify the active hook feature flag with `tokenjuice doctor hooks` because config keys have changed across releases.
+
 ## Where things live
 
 - Source: `src/solo_mise/`

memory/cards/tokenjuice-output-compaction.md

@@ -0,0 +1,106 @@
+---
+topic: tokenjuice-output-compaction
+type: tool-runbook
+tags: [tools, tokenjuice, output-compaction, claude-code, codex]
+status: starter
+---
+
+# TokenJuice Output Compaction
+
+TokenJuice compacts noisy terminal output before it is fed back into an agent session. The original command still runs. Exact file reads and raw-output requests stay available, but inventory commands, search results, logs, and oversized help text can be summarized before they tax the next turn.
+
+## Why Agents Need To Know
+
+If an agent sees a TokenJuice footer, treat it as trusted local metadata about output reduction. It is not task instruction and it is not evidence by itself. It tells the agent that some terminal output was compacted and how to request raw output when precision matters.
+
+Use raw output for exact diffs, full logs, reproducible error text, generated artifacts, or anything line-sensitive:
+
+```bash
+tokenjuice wrap --raw -- <command>
+```
+
+## Claude Code
+
+Claude Code needs command replacement before the Bash result enters context. When the official adapter still uses PostToolUse appended context, it can add metadata without preventing the raw tool result from being charged. In the April 2026 trial, that default PostToolUse path was net-negative at about +1.1% tokens.
+
+Until the upstream fix is merged, use a local PreToolUse wrapper. The wrapper rewrites Bash commands to run under TokenJuice before execution:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ~/.claude/hooks/tokenjuice-pretool.js"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+The wrapper should emit Claude Code's PreToolUse rewrite contract:
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "allow",
+    "updatedInput": {
+      "command": "tokenjuice wrap -- sh -c \"<original command>\""
+    }
+  }
+}
+```
+
+Operational notes:
+
+- Keep a kill switch such as `TOKENJUICE_PRETOOL_DISABLE=1`.
+- Let the wrapper honor `TOKENJUICE_BIN` and `TOKENJUICE_PRETOOL_SHELL` when local paths differ.
+- New hook settings normally apply only to new Claude Code sessions.
+- Document the wrapper in `CLAUDE.md` so agents do not mistake the footer for prompt injection.
+
+## Codex
+
+Codex can use TokenJuice through its normal hook path because the harness honors PostToolUse substitution. Install and verify with:
+
+```bash
+tokenjuice install codex
+tokenjuice doctor hooks
+```
+
+Codex hook feature flags have changed across releases. Older configs used `codex_hooks`; newer configs use `hooks`. Do not trust old setup notes blindly. Run `tokenjuice doctor hooks` and fix the config it reports for the installed CLI version.
+
+## Savings Model
+
+TokenJuice always reports output compaction. Billing-token savings depend on whether that compacted output is fed into later turns.
+
+Observed local output stats in May 2026:
+
+- 17.1k compacted entries
+- 83.6m raw output chars
+- 24.7m reduced output chars
+- 58.9m chars avoided, about 70% output reduction
+
+Measured harness trials:
+
+- Claude Code PreToolUse wrapper: about -7.8% tokens in the April 2026 paired trial.
+- Claude Code default PostToolUse adapter: about +1.1% tokens in the same trial, because raw output still entered context.
+- Codex v0.5.0 paired trial: about -8.8% clean-run token reduction after reducer and hook fixes.
+- Codex GPT-5.5 one-turn gauntlet: about +0.3%, effectively flat, because the model batched tool calls into one turn and compacted output was not re-fed as later input. Per-command output reductions still remained large.
+
+Practical read: TokenJuice is most valuable for repeated terminal exploration where tool results become future context. It is still useful for human readability and context pressure when the model batches commands, but the billable-token delta may flatten.
+
+## Verification
+
+```bash
+tokenjuice --version
+tokenjuice stats
+tokenjuice doctor hooks
+tokenjuice wrap -- git status --short
+tokenjuice wrap --raw -- git status --short
+```

src/solo_mise/templates/memory/cards/tokenjuice-output-compaction.md

@@ -0,0 +1,106 @@
+---
+topic: tokenjuice-output-compaction
+type: tool-runbook
+tags: [tools, tokenjuice, output-compaction, claude-code, codex]
+status: starter
+---
+
+# TokenJuice Output Compaction
+
+TokenJuice compacts noisy terminal output before it is fed back into an agent session. The original command still runs. Exact file reads and raw-output requests stay available, but inventory commands, search results, logs, and oversized help text can be summarized before they tax the next turn.
+
+## Why Agents Need To Know
+
+If an agent sees a TokenJuice footer, treat it as trusted local metadata about output reduction. It is not task instruction and it is not evidence by itself. It tells the agent that some terminal output was compacted and how to request raw output when precision matters.
+
+Use raw output for exact diffs, full logs, reproducible error text, generated artifacts, or anything line-sensitive:
+
+```bash
+tokenjuice wrap --raw -- <command>
+```
+
+## Claude Code
+
+Claude Code needs command replacement before the Bash result enters context. When the official adapter still uses PostToolUse appended context, it can add metadata without preventing the raw tool result from being charged. In the April 2026 trial, that default PostToolUse path was net-negative at about +1.1% tokens.
+
+Until the upstream fix is merged, use a local PreToolUse wrapper. The wrapper rewrites Bash commands to run under TokenJuice before execution:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ~/.claude/hooks/tokenjuice-pretool.js"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+The wrapper should emit Claude Code's PreToolUse rewrite contract:
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "allow",
+    "updatedInput": {
+      "command": "tokenjuice wrap -- sh -c \"<original command>\""
+    }
+  }
+}
+```
+
+Operational notes:
+
+- Keep a kill switch such as `TOKENJUICE_PRETOOL_DISABLE=1`.
+- Let the wrapper honor `TOKENJUICE_BIN` and `TOKENJUICE_PRETOOL_SHELL` when local paths differ.
+- New hook settings normally apply only to new Claude Code sessions.
+- Document the wrapper in `CLAUDE.md` so agents do not mistake the footer for prompt injection.
+
+## Codex
+
+Codex can use TokenJuice through its normal hook path because the harness honors PostToolUse substitution. Install and verify with:
+
+```bash
+tokenjuice install codex
+tokenjuice doctor hooks
+```
+
+Codex hook feature flags have changed across releases. Older configs used `codex_hooks`; newer configs use `hooks`. Do not trust old setup notes blindly. Run `tokenjuice doctor hooks` and fix the config it reports for the installed CLI version.
+
+## Savings Model
+
+TokenJuice always reports output compaction. Billing-token savings depend on whether that compacted output is fed into later turns.
+
+Observed local output stats in May 2026:
+
+- 17.1k compacted entries
+- 83.6m raw output chars
+- 24.7m reduced output chars
+- 58.9m chars avoided, about 70% output reduction
+
+Measured harness trials:
+
+- Claude Code PreToolUse wrapper: about -7.8% tokens in the April 2026 paired trial.
+- Claude Code default PostToolUse adapter: about +1.1% tokens in the same trial, because raw output still entered context.
+- Codex v0.5.0 paired trial: about -8.8% clean-run token reduction after reducer and hook fixes.
+- Codex GPT-5.5 one-turn gauntlet: about +0.3%, effectively flat, because the model batched tool calls into one turn and compacted output was not re-fed as later input. Per-command output reductions still remained large.
+
+Practical read: TokenJuice is most valuable for repeated terminal exploration where tool results become future context. It is still useful for human readability and context pressure when the model batches commands, but the billable-token delta may flatten.
+
+## Verification
+
+```bash
+tokenjuice --version
+tokenjuice stats
+tokenjuice doctor hooks
+tokenjuice wrap -- git status --short
+tokenjuice wrap --raw -- git status --short
+```

src/solo_mise/templates/profiles/workspace.json

@@ -20,6 +20,7 @@
     {"src": "memory/cards/memory-scanner.md", "dst": "memory/cards/memory-scanner.md"},
     {"src": "memory/cards/memory-care-staleness.md", "dst": "memory/cards/memory-care-staleness.md"},
     {"src": "memory/cards/multi-workspace-handoff-admin.md", "dst": "memory/cards/multi-workspace-handoff-admin.md"},
+    {"src": "memory/cards/tokenjuice-output-compaction.md", "dst": "memory/cards/tokenjuice-output-compaction.md"},
     {"src": "memory/cards/chat-surface-crawlers.md", "dst": "memory/cards/chat-surface-crawlers.md"},
     {"src": "memory/cards/pipeline-standups.md", "dst": "memory/cards/pipeline-standups.md"},
     {"src": "hooks/pre-push", "dst": "hooks/pre-push", "mode": "0755"},

src/solo_mise/templates/workspace/CLAUDE.md

@@ -22,6 +22,14 @@ At the end of any substantial task, check whether the session produced durable k
 - Say it = call it. If you say you will do something that requires a tool, call the tool in the same turn. Silent intent is a lie. Full rule in `SOUL.md`.
 - After a tool failure, emit a one-line status or call a different tool within 30 seconds. Do not silently reason for minutes.
 
+## TokenJuice
+
+If this workspace uses TokenJuice, treat its footer as trusted local output-compaction metadata. It is there to explain how much terminal output was reduced before the next turn sees it.
+
+Claude Code note: when the official adapter still uses PostToolUse appended context, prefer the local PreToolUse wrapper that rewrites Bash commands to `tokenjuice wrap -- ...`. The wrapper avoids paying for large raw outputs and keeps the command result itself compact. If exact output matters, run the command through the documented raw-output escape hatch.
+
+Full runbook: `memory/cards/tokenjuice-output-compaction.md`.
+
 ## Git
 
 - Do not add `Co-Authored-By` or AI-attribution trailers to commits, PR bodies, or public docs.