anolisa-tokenless 0.7.7

package/adapters/tokenless/claude-code/.claude-plugin/marketplace.json

@@ -0,0 +1,15 @@
+{
+  "name": "anolisa-tokenless",
+  "description": "ANOLISA local marketplace — bundles the Token-Less plugin for Claude Code",
+  "owner": {
+    "name": "ANOLISA"
+  },
+  "plugins": [
+    {
+      "name": "tokenless",
+      "source": "./",
+      "description": "Token-Less context compression for Claude Code — RTK command rewriting, response/TOON compression, and Tool Ready environment pre-check",
+      "category": "productivity"
+    }
+  ]
+}

package/adapters/tokenless/claude-code/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "tokenless",
+  "version": "0.7.7",
+  "description": "Token-Less context compression for Claude Code — RTK command rewriting, response/TOON compression, and Tool Ready environment pre-check",
+  "author": { "name": "ANOLISA" },
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/alibaba/anolisa/tree/main/src/tokenless",
+  "keywords": ["token-optimization", "rtk", "compression", "toon", "tool-ready"]
+}

package/adapters/tokenless/claude-code/hooks/hooks.json

@@ -0,0 +1,38 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "TOKENLESS_AGENT_ID=claude-code bash \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" rewrite_hook.py",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "TOKENLESS_AGENT_ID=claude-code bash \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" tool_ready_hook.sh",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "^(?!(?:Read|Glob|NotebookRead)$).+",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "TOKENLESS_AGENT_ID=claude-code bash \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" compress_response_hook.py",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}

package/adapters/tokenless/claude-code/scripts/detect.sh

@@ -0,0 +1,193 @@
+#!/usr/bin/env bash
+# detect.sh — Inspect Claude Code presence and the tokenless plugin state.
+# Read-only. Tri-state exit aligns with openclaw/hermes detect.sh:
+#   0 = installed and ready
+#   1 = not installed but installable (prereqs OK)
+#   2 = missing prerequisites
+set -euo pipefail
+
+COMPONENT="${ANOLISA_COMPONENT:-tokenless}"
+AGENT="${ANOLISA_TARGET:-claude-code}"
+ADAPTER_DIR="${ANOLISA_ADAPTER_DIR:-$(cd "$(dirname "$0")/../.." && pwd)}"
+
+PLUGIN_ID="${COMPONENT}@anolisa-${COMPONENT}"
+PLUGIN_SRC="$ADAPTER_DIR/claude-code"
+
+CLAUDE_BIN="${CLAUDE_BIN:-}"
+export PATH="$HOME/.local/bin:/usr/local/bin:$PATH"
+
+# First-run settling retries: right after provisioning, the claude binary or
+# the plugin registry may be transiently invisible on the very first detect.sh
+# execution (filesystem/PATH init timing race). settle() only retries checks
+# that report a retryable failure (exit status 1); checks that succeed or
+# report a definitive result return immediately, so steady-state runs stay
+# fast.
+DETECT_RETRIES="${TOKENLESS_DETECT_RETRIES:-3}"
+DETECT_RETRY_DELAY="${TOKENLESS_DETECT_RETRY_DELAY:-1}"
+
+# settle <cmd...> — run cmd once; if it reports a retryable failure (exit
+# status 1), sleep DETECT_RETRY_DELAY and retry, up to DETECT_RETRIES retries
+# (that is, at most 1 + DETECT_RETRIES attempts in total). Exit status 0 is
+# success. Any other exit status is a definitive result and is returned
+# immediately without further retries. Returns the final exit status.
+# Callers must therefore reserve exit status 1 for conditions that a retry
+# may still resolve.
+settle() {
+    local retry=0 rc=0
+    "$@"; rc=$?
+    while [ "$rc" -eq 1 ] && [ "$retry" -lt "$DETECT_RETRIES" ]; do
+        retry=$((retry + 1))
+        sleep "$DETECT_RETRY_DELAY"
+        "$@"; rc=$?
+    done
+    return "$rc"
+}
+
+line()  { printf '[%s] %s\n' "$COMPONENT" "$*"; }
+field() { printf '[%s]   %-26s %s\n' "$COMPONENT" "$1" "$2"; }
+
+PREREQ_MISSING=()
+INSTALL_MISSING=()
+note_prereq_missing()  { PREREQ_MISSING+=("$1"); }
+note_install_missing() { INSTALL_MISSING+=("$1"); }
+
+find_claude_bin() {
+    CLAUDE_BIN="$(command -v claude 2>/dev/null || true)"
+    [ -n "$CLAUDE_BIN" ]
+}
+
+if [ -z "$CLAUDE_BIN" ]; then
+    # PATH/filesystem may still be settling right after install; re-check
+    # briefly before declaring the CLI missing. A genuinely absent CLI cannot
+    # be distinguished from that settling race, so it spends one retry budget
+    # (set TOKENLESS_DETECT_RETRIES=0 to opt out).
+    settle find_claude_bin || true
+fi
+
+line "${AGENT} detect"
+if [ -n "$CLAUDE_BIN" ] && [ -x "$CLAUDE_BIN" ]; then
+    CLAUDE_VER="$("$CLAUDE_BIN" --version 2>/dev/null | awk '{print $1}' || echo unknown)"
+    field "claude CLI"        "present (${CLAUDE_BIN}, v${CLAUDE_VER})"
+else
+    field "claude CLI"        "missing"
+    note_prereq_missing "claude CLI"
+fi
+
+# Informational only: claude creates ~/.claude on first run; absence is
+# not a prerequisite failure. Check once, without settling retries: nothing in
+# this script creates the directory before `claude plugin list` runs, and that
+# call carries its own retry budget and initializes ~/.claude itself, so
+# retrying this probe would only delay the report.
+if [ -d "$HOME/.claude" ]; then
+    field "claude config dir" "present ($HOME/.claude)"
+else
+    field "claude config dir" "missing (created on first claude run)"
+fi
+
+if [ -f "$PLUGIN_SRC/.claude-plugin/marketplace.json" ]; then
+    field "marketplace.json"  "present"
+else
+    field "marketplace.json"  "missing"
+    note_prereq_missing "marketplace.json"
+fi
+
+if [ -f "$PLUGIN_SRC/.claude-plugin/plugin.json" ]; then
+    field "plugin.json"       "present"
+else
+    field "plugin.json"       "missing (run: make stamp-adapter-templates)"
+fi
+
+# claude_plugin_listed — probe the plugin registry, using the settle()
+# exit-status contract: 0 = plugin listed; 1 = `claude plugin list` itself
+# failed (the CLI may still be initializing ~/.claude on first run, so a
+# retry may still succeed); 2 = `plugin list` ran successfully but did not
+# list the plugin. That is a definitive absent result — no retry can change
+# it — so settle() must return immediately instead of sleeping out the
+# retry budget and invoking the CLI DETECT_RETRIES + 1 times.
+claude_plugin_listed() {
+    local listing
+    if ! listing="$("$CLAUDE_BIN" plugin list 2>&1)"; then
+        return 1
+    fi
+    if printf '%s\n' "$listing" | grep -qF "$PLUGIN_ID"; then
+        return 0
+    fi
+    return 2
+}
+
+if [ -n "$CLAUDE_BIN" ] && [ -x "$CLAUDE_BIN" ]; then
+    # First-run race: `claude plugin list` may transiently fail while the CLI
+    # initializes ~/.claude; settle() retries while that failure (status 1)
+    # persists. A successful list that simply omits the plugin is definitive
+    # (status 2) and is reported as "not installed" without further retries.
+    if settle claude_plugin_listed; then
+        field "plugin install"    "installed ($PLUGIN_ID)"
+    else
+        field "plugin install"    "not installed"
+        note_install_missing "$PLUGIN_ID"
+    fi
+fi
+
+if [ -f "$PLUGIN_SRC/hooks/run-hook.sh" ]; then
+    field "hook dispatcher"   "present"
+else
+    field "hook dispatcher"   "missing (hooks/run-hook.sh)"
+    note_prereq_missing "hook dispatcher"
+fi
+
+if command -v python3 &>/dev/null; then
+    field "python3"           "present ($(command -v python3))"
+else
+    field "python3"           "missing"
+    note_prereq_missing "python3"
+fi
+
+# jq is required by tool_ready_hook.sh; absence disables that hook only
+# (rewrite + compress-response still work). Treat as informational.
+if command -v jq &>/dev/null; then
+    field "jq"                "present ($(command -v jq))"
+else
+    field "jq"                "missing (tool-ready hook disabled)"
+fi
+
+runtime_bin="$(command -v tokenless 2>/dev/null || true)"
+if [ -n "$runtime_bin" ]; then
+    field "tokenless binary"  "present (${runtime_bin})"
+else
+    field "tokenless binary"  "missing"
+    note_prereq_missing "tokenless binary"
+fi
+
+rtk_bin="$(command -v rtk 2>/dev/null || true)"
+if [ -n "$rtk_bin" ]; then
+    field "rtk binary"        "present (${rtk_bin})"
+else
+    field "rtk binary"        "missing"
+    note_prereq_missing "rtk binary"
+fi
+
+# Shared hook scripts live under FHS; warn when missing so user knows to run
+# `make install` (or install the RPM) before adapter actually fires.
+SHARED_HOOKS_DIR=""
+for d in /usr/local/share/anolisa/adapters/tokenless/common/hooks \
+         /usr/share/anolisa/adapters/tokenless/common/hooks \
+         "$HOME/.local/share/anolisa/adapters/tokenless/common/hooks"; do
+    if [ -d "$d" ]; then SHARED_HOOKS_DIR="$d"; break; fi
+done
+if [ -n "$SHARED_HOOKS_DIR" ]; then
+    field "shared hooks dir"  "present ($SHARED_HOOKS_DIR)"
+else
+    field "shared hooks dir"  "missing (run: make -C src/tokenless install)"
+    note_prereq_missing "shared hooks dir"
+fi
+
+if [ ${#PREREQ_MISSING[@]} -gt 0 ]; then
+    line "${AGENT}: missing prerequisites (${PREREQ_MISSING[*]})"
+    exit 2
+fi
+if [ ${#INSTALL_MISSING[@]} -gt 0 ]; then
+    line "${AGENT}: not installed (ready to install)"
+    exit 1
+fi
+line "${AGENT}: ready"
+exit 0

package/adapters/tokenless/claude-code/scripts/install.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# install.sh — Register tokenless as a local Claude Code marketplace and
+# install the plugin via the official `claude plugin` CLI.
+#
+# Responsibility boundary (mirrors openclaw/scripts/install.sh):
+#   - This script ONLY deploys an already-stamped plugin manifest.
+#   - Manifest stamping (plugin.json.in -> plugin.json) is the Makefile's job:
+#       make -C src/tokenless stamp-adapter-templates
+#     which `make install` runs automatically before `install-adapter-resources`
+#     copies the result into $SHARE_DIR/claude-code.
+#   - A dev-only fallback stamps the manifest in place when called outside the
+#     RPM/Makefile flow, so adapter-install works on a freshly checked-out tree.
+#
+# Claude Code v2 requires plugins to be sourced from a registered marketplace.
+# We expose the adapter's claude-code/ directory itself as a single-plugin
+# marketplace ("anolisa-tokenless"), then install tokenless@anolisa-tokenless
+# from it. The marketplace name is component-scoped so multiple ANOLISA
+# components can each register their own without colliding.
+set -euo pipefail
+
+AGENT="${ANOLISA_TARGET:-claude-code}"
+COMPONENT="${ANOLISA_COMPONENT:-tokenless}"
+ADAPTER_DIR="${ANOLISA_ADAPTER_DIR:-$(cd "$(dirname "$0")/../.." && pwd)}"
+
+PLUGIN_SRC="$ADAPTER_DIR/claude-code"
+MARKETPLACE_NAME="anolisa-${COMPONENT}"
+PLUGIN_ID="${COMPONENT}@${MARKETPLACE_NAME}"
+
+CLAUDE_BIN="${CLAUDE_BIN:-claude}"
+export PATH="$HOME/.local/bin:/usr/local/bin:$PATH"
+
+echo "[${COMPONENT}] Installing ${AGENT} plugin..."
+
+if ! command -v "$CLAUDE_BIN" &>/dev/null; then
+    echo "[${COMPONENT}] claude CLI not found (CLAUDE_BIN=${CLAUDE_BIN}) — skipping plugin installation."
+    echo "[${COMPONENT}] Install Claude Code first, then run this script again."
+    exit 0
+fi
+
+if [ ! -d "$PLUGIN_SRC" ]; then
+    echo "[${COMPONENT}] Plugin source not found: $PLUGIN_SRC" >&2
+    exit 1
+fi
+
+if [ ! -f "$PLUGIN_SRC/.claude-plugin/marketplace.json" ]; then
+    echo "[${COMPONENT}] ERROR: $PLUGIN_SRC/.claude-plugin/marketplace.json missing." >&2
+    exit 1
+fi
+
+# Dev-only fallback: stamp plugin.json from .in template when Makefile hasn't
+# run yet. Production installs (RPM, `make install`) ship a stamped manifest
+# inside SHARE_DIR, so this branch is a no-op in those flows.
+PLUGIN_MANIFEST="$PLUGIN_SRC/.claude-plugin/plugin.json"
+PLUGIN_TEMPLATE="$PLUGIN_SRC/.claude-plugin/plugin.json.in"
+if [ ! -f "$PLUGIN_MANIFEST" ] && [ -f "$PLUGIN_TEMPLATE" ]; then
+    VERSION="${TOKENLESS_VERSION:-${ANOLISA_VERSION:-0.0.0-dev}}"
+    sed "s/@VERSION@/${VERSION}/g" "$PLUGIN_TEMPLATE" > "$PLUGIN_MANIFEST"
+    echo "[${COMPONENT}] dev-fallback: stamped plugin.json (version=${VERSION}) — production builds should stamp via Makefile"
+fi
+
+if [ ! -f "$PLUGIN_MANIFEST" ] ; then
+    echo "[${COMPONENT}] ERROR: $PLUGIN_MANIFEST missing." >&2
+    echo "[${COMPONENT}]        Stamp the manifest first:" >&2
+    echo "[${COMPONENT}]            make -C src/tokenless stamp-adapter-templates" >&2
+    exit 1
+fi
+
+# Validate the stamped plugin via the official CLI — same gate the install
+# call would hit; surfacing the error here gives a cleaner failure message.
+"$CLAUDE_BIN" plugin validate "$PLUGIN_SRC" >/dev/null \
+    || { echo "[${COMPONENT}] plugin validation failed" >&2; exit 1; }
+
+# Idempotent marketplace add. We probe `marketplace list` first so that a
+# `marketplace add` failure surfaces its real cause (bad path, malformed
+# manifest, settings.json write error) instead of being swallowed as
+# "already registered".
+echo "[${COMPONENT}] registering marketplace '${MARKETPLACE_NAME}' from ${PLUGIN_SRC}..."
+if "$CLAUDE_BIN" plugin marketplace list 2>/dev/null \
+       | grep -qE "(^|[[:space:]])${MARKETPLACE_NAME}([[:space:]]|$)"; then
+    echo "[${COMPONENT}] marketplace '${MARKETPLACE_NAME}' already registered"
+else
+    "$CLAUDE_BIN" plugin marketplace add "$PLUGIN_SRC" \
+        || { echo "[${COMPONENT}] marketplace add failed" >&2; exit 1; }
+fi
+
+# Idempotent plugin install.
+echo "[${COMPONENT}] installing ${PLUGIN_ID}..."
+"$CLAUDE_BIN" plugin install "$PLUGIN_ID" 2>&1 \
+    || { echo "[${COMPONENT}] plugin install failed" >&2; exit 1; }
+
+echo "[${COMPONENT}] ${AGENT} plugin installed via claude CLI."
+echo "[${COMPONENT}] Restart claude (or run /plugin) to activate."

package/adapters/tokenless/claude-code/scripts/uninstall.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# uninstall.sh — Remove the tokenless plugin and the anolisa marketplace via
+# the official `claude plugin` CLI. Falls back to manual cleanup of the
+# settings.json + plugin cache when claude is unavailable (e.g. RPM %preun
+# running after the user uninstalled claude themselves).
+set -euo pipefail
+
+AGENT="${ANOLISA_TARGET:-claude-code}"
+COMPONENT="${ANOLISA_COMPONENT:-tokenless}"
+
+MARKETPLACE_NAME="anolisa-${COMPONENT}"
+PLUGIN_ID="${COMPONENT}@${MARKETPLACE_NAME}"
+
+CLAUDE_BIN="${CLAUDE_BIN:-claude}"
+export PATH="$HOME/.local/bin:/usr/local/bin:$PATH"
+
+echo "[${COMPONENT}] Uninstalling ${AGENT} plugin..."
+
+if command -v "$CLAUDE_BIN" &>/dev/null; then
+    "$CLAUDE_BIN" plugin uninstall "$PLUGIN_ID" 2>&1 || true
+    "$CLAUDE_BIN" plugin marketplace remove "$MARKETPLACE_NAME" 2>&1 || true
+    echo "[${COMPONENT}] ${AGENT} plugin removed via claude CLI."
+    exit 0
+fi
+
+echo "[${COMPONENT}] claude CLI not found — falling back to manual cleanup."
+SETTINGS="$HOME/.claude/settings.json"
+if command -v jq &>/dev/null && [ -f "$SETTINGS" ]; then
+    # del(.[$key]) silently no-ops on non-object values. Verify shape up-front
+    # so a schema change in a future Claude Code release surfaces as a clear
+    # warning instead of a silent "cleaned" message that left residue behind.
+    EP_TYPE=$(jq -r '.enabledPlugins | type' "$SETTINGS" 2>/dev/null || echo "missing")
+    MK_TYPE=$(jq -r '.extraKnownMarketplaces | type' "$SETTINGS" 2>/dev/null || echo "missing")
+    if [ "$EP_TYPE" != "object" ] && [ "$EP_TYPE" != "null" ] && [ "$EP_TYPE" != "missing" ]; then
+        echo "[${COMPONENT}] WARN: .enabledPlugins is ${EP_TYPE}, expected object — skipping jq cleanup." >&2
+        echo "[${COMPONENT}] WARN: remove '${PLUGIN_ID}' from $SETTINGS manually." >&2
+    elif [ "$MK_TYPE" != "object" ] && [ "$MK_TYPE" != "null" ] && [ "$MK_TYPE" != "missing" ]; then
+        echo "[${COMPONENT}] WARN: .extraKnownMarketplaces is ${MK_TYPE}, expected object — skipping jq cleanup." >&2
+        echo "[${COMPONENT}] WARN: remove '${MARKETPLACE_NAME}' from $SETTINGS manually." >&2
+    else
+        tmp="$(mktemp "${SETTINGS}.XXXXXX")"
+        jq --arg id "$PLUGIN_ID" --arg mkt "$MARKETPLACE_NAME" '
+            if .enabledPlugins then .enabledPlugins |= del(.[$id]) else . end
+            | if .extraKnownMarketplaces then .extraKnownMarketplaces |= del(.[$mkt]) else . end
+        ' "$SETTINGS" > "$tmp" && mv "$tmp" "$SETTINGS"
+        echo "[${COMPONENT}] cleaned $SETTINGS"
+    fi
+fi
+rm -rf "$HOME/.claude/plugins/cache/${MARKETPLACE_NAME}" 2>/dev/null || true
+echo "[${COMPONENT}] manual cleanup complete."

package/adapters/tokenless/codex/.codex-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "tokenless",
+  "version": "0.7.7",
+  "description": "Intelligent tool response compression, environment error detection, and token optimization. Strips noise (debug fields, nulls, empty values), truncates long strings/arrays, applies TOON encoding for JSON responses, and classifies environment errors with actionable fix hints.",
+  "keywords": [
+    "compression",
+    "token",
+    "context",
+    "optimization",
+    "environment",
+    "diagnostics"
+  ],
+  "hooks": "./hooks/hooks.json",
+  "interface": {
+    "displayName": "Tokenless",
+    "shortDescription": "Compress tool responses and detect environment errors to save tokens",
+    "category": "developer-tools",
+    "capabilities": ["hook"]
+  }
+}

package/adapters/tokenless/codex/README.md

@@ -0,0 +1,160 @@
+# Tokenless Plugin for Codex
+
+Intelligent tool response compression and environment error detection plugin for
+[Codex](https://github.com/openai/codex). Reduces token consumption by stripping
+noise, truncating verbose output, and classifying environment errors with
+actionable fix hints.
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Response Compression** | Strips debug fields, nulls, empty values; truncates long strings (512 chars) and arrays (16 items); limits depth to 8 levels |
+| **TOON Encoding** | Further compresses valid JSON responses (15-40% additional savings vs. compressed JSON) |
+| **Environment Error Detection** | Classifies tool failures as dependency/permission/file/network/package issues; injects fix hints to prevent retry loops |
+| **Statistics Tracking** | Records every compression operation to SQLite for auditing and optimization |
+
+## How It Works
+
+The plugin registers four hooks with Codex:
+
+1. **`SessionStart`** — verifies the `tokenless` CLI is installed and functional (non-blocking)
+2. **`PreToolUse` (tool-ready, hard-disabled)** — remains registered but is a
+   silent pass-through. `tokenless env-check` returns `UNKNOWN` with
+   `enabled:false`, so the hook emits no context, performs no repair, and never
+   blocks a tool. Re-enabling the retained legacy pipeline requires a source
+   change and a new release.
+3. **`PreToolUse` (rewrite)** — runs before shell command execution:
+   - Rewrites commands via `rtk rewrite` for token optimization
+   - Only applies to Bash/Shell/terminal/programmatic tools
+4. **`PostToolUse`** — runs after every tool execution:
+   - Skips content-reading tools (Read, Glob) and small responses (< 500 chars)
+   - Classifies environment errors and injects fix hints
+   - Compresses large JSON responses via `tokenless compress-response`
+   - Applies TOON encoding for additional savings
+   - Injects a compressed summary as `additionalContext`
+
+> **Codex Protocol Constraint**: PostToolUse hooks cannot suppress the original
+> tool output (`suppressOutput` is rejected). The plugin therefore injects a
+> compressed *summary* as `additionalContext` — the model sees both the original
+> output and the compressed summary, and can use the summary for efficient
+> processing of large outputs.
+
+## Installation
+
+### Prerequisites
+
+- Rust toolchain ≥ 1.89.0
+- The `anolisa` source tree (this repository)
+
+### Install
+
+```bash
+cd src/tokenless/adapters/tokenless/codex
+./scripts/install.sh
+```
+
+This builds the `tokenless` Rust CLI in release mode and installs it to
+`~/.local/bin/`. Add `~/.local/bin` to your `PATH` if not already present.
+
+### Configure Codex
+
+Add the plugin to your Codex `config.toml`:
+
+```toml
+[plugins]
+tokenless = { enabled = true }
+```
+
+Or install from the marketplace (once published).
+
+### Verify
+
+```bash
+./scripts/detect.sh
+# {"installed": true, "version": "1.0.0", "path": "/home/user/.local/bin/tokenless"}
+```
+
+## Hook Output Format
+
+The plugin injects `additionalContext` in the following format:
+
+```
+[tokenless:compressed] Bash: 45,230 → 2,100 chars (95% reduction)
+[tokenless:env:ENV_DEPENDENCY_MISSING] Missing dependency detected. ...
+Do NOT retry the same command — fix the environment first.
+--- compressed content ---
+{... compressed JSON or TOON content ...}
+--- end compressed content ---
+```
+
+## Configuration
+
+Configuration is managed through the `tokenless` CLI's environment and config file:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `TOKENLESS_AGENT_ID` | `codex` | Agent identifier for statistics |
+| `TOKENLESS_BIN` | (auto-detected) | Path to tokenless binary |
+| `TOKENLESS_STATS_ENABLED` | `1` | Enable statistics recording |
+| `TOKENLESS_DATA_DIR` | `~/.tokenless` | Directory for `stats.db` and `stash.db` |
+| `TOKENLESS_STATS_DB` | `~/.tokenless/stats.db` | Statistics database path |
+| `TOKENLESS_STASH_DB` | `~/.tokenless/stash.db` | Reversible stash database path |
+
+`TOKENLESS_STATS_DB` and `TOKENLESS_STASH_DB` take precedence over
+`TOKENLESS_DATA_DIR`, which may be any accessible absolute non-root directory.
+Custom database files must remain under the real user home or selected data
+directory.
+
+### View Statistics
+
+```bash
+tokenless stats summary
+tokenless stats list --limit 20
+tokenless stats show <id>
+```
+
+## Compression Pipeline
+
+```
+Raw tool_response (JSON)
+    │
+    ├─ Step 1: ResponseCompressor
+    │   ├─ Drop: debug, trace, stack, stacktrace, logs, logging fields
+    │   ├─ Truncate: strings > 512 chars, arrays > 16 items
+    │   ├─ Drop: null values, empty strings, empty arrays, empty objects
+    │   └─ Limit: max depth 8 levels
+    │
+    ├─ Step 2: TOON Encoding (if result is still valid JSON)
+    │   └─ Binary-to-TOON format encoding (~15-40% additional savings)
+    │
+    └─ Guard: output only if smaller than input (safety check)
+```
+
+## Architecture
+
+```
+codex-plugin-tokenless/
+├── plugin.json.in           # Codex plugin manifest (version-stamped by Makefile)
+├── hooks/
+│   └── hooks.json           # Hook definitions (SessionStart, PreToolUse, PostToolUse)
+├── scripts/
+│   ├── compress-response    # PostToolUse: response compression + env error detection
+│   ├── rewrite-hook         # PreToolUse: RTK command rewriting
+│   ├── tool-ready           # PreToolUse: registered hard-disabled pass-through
+│   ├── check-tokenless      # SessionStart: version/availability check
+│   ├── install.sh           # Build and install tokenless CLI + register plugin
+│   ├── detect.sh            # Detect tokenless availability
+│   └── uninstall.sh         # Cleanup plugin registration + marketplace
+└── README.md
+```
+
+## Related
+
+- [Tokenless Rust CLI](../../crates/tokenless-cli/) — core compression engine
+- [OpenClaw Plugin](../openclaw/) — same compression for OpenClaw
+- [Hermes Plugin](../hermes/) — same compression for Hermes
+
+## License
+
+Same as the ANOLISA project.

package/adapters/tokenless/codex/hooks/hooks.json

@@ -0,0 +1,52 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${PLUGIN_ROOT}/scripts/tool-ready",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "Bash|run_shell_command|terminal|Shell|exec|process",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${PLUGIN_ROOT}/scripts/rewrite-hook",
+            "timeout": 10,
+            "statusMessage": "Rewriting command via RTK..."
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${PLUGIN_ROOT}/scripts/compress-response",
+            "timeout": 15,
+            "statusMessage": "Compressing tool response..."
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": null,
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${PLUGIN_ROOT}/scripts/check-tokenless",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/adapters/tokenless/codex/scripts/_common.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# _common.sh — Shared helpers for codex adapter scripts.
+# Source this file from install.sh and uninstall.sh.
+
+# Resolve the codex CLI binary.
+resolve_codex() {
+    if [[ -n "$CODEX_BIN" ]] && command -v "$CODEX_BIN" &>/dev/null; then
+        echo "$CODEX_BIN"
+        return
+    fi
+    for candidate in codex /usr/local/bin/codex /usr/bin/codex "$HOME/.local/bin/codex"; do
+        if command -v "$candidate" &>/dev/null; then
+            echo "$candidate"
+            return
+        fi
+    done
+    # Last resort: direct path check
+    for candidate in /usr/local/bin/codex /usr/bin/codex "$HOME/.local/bin/codex"; do
+        if [[ -x "$candidate" ]]; then
+            echo "$candidate"
+            return
+        fi
+    done
+    echo ""
+}