Chisle Cuts AI Coding Assistant Token Usage to 52% via Three-Layer Compression

Project Overview

Chisle is an efficiency rule set and runtime compressor for AI coding assistants. It simultaneously manages three aspects in a single session: how the model writes, what the model reads, and how much the model reads. The first two are handled by injecting rule text into the context; the third uses a compression hook attached to tool-return events. All compression and rewriting occur locally with no model calls, network requests, or third-party dependencies, and there are no intensity levels—only on or off.

Core Capabilities

Prompt Rule Injection : At session start, the full rule body (~1.6k tokens) is injected. Each subsequent turn adds only a ~50-token reminder. Only brand-new sessions receive the full rules; resume, clear, or compress events get a single line to avoid repeated billing for the same rules.

Seven-Level Code Ladder : Questions cascade from "Does this need to exist?" down to "Can it be one line?" stopping at the first satisfied rung. Safety, error handling, and accessibility are explicitly excluded from reduction.

Reasoning Also Bills : The ladder is encoded as a stop rule rather than a checklist to recite, with explicit instruction not to re-weigh already-excluded options, while preserving the requirement that understanding the problem cannot be shortcut.

Tool Output Compression : A pure Node standard-library PostToolUse hook selects tools via a whitelist, then scrubs, truncates the middle, and deduplicates oversized outputs before replacing what the model actually sees.

Recoverable Omission : Before cutting the middle, the full original is written to disk; the replacement marker includes the file path. Later retrieval becomes an exact search rather than re-running the command—critical for non-replayable commands.

Return Structure Restoration : Compressed text must be reinserted into the tool's original return structure; unrecognized structures are left untouched rather than guessed.

Reading Habit Rules : Search by symbol first, then read only matching ranges; narrow output from the source; avoid re-reading files already in context; keep only failures and summaries from build and test logs.

Nine Clients, One Command : Auto-detects installed assistants and installs via plugin, package, appended rule segment, or project-local rule file.

Built-in Benchmark Suite : Four controlled test suites—real-time comparative scripts, offline replay, auto-graded correctness tests, and real-repository test suites.

Quick Start

Requirements

Node ≥ 18 (for installer and npx)

For input-side compression and /chisle toggle, Claude Code or Pi required

Other seven clients receive only the persistent rule portion

Installation

# npm, auto-detect and install each
npx chisle

# or shell launcher
curl -fsSL https://raw.githubusercontent.com/JayPokale/Chisle/main/install.sh | bash

# Windows
irm https://raw.githubusercontent.com/JayPokale/Chisle/main/install.ps1 | iex

# Install for a single client, preview changes
npx chisle --only claude --dry-run

# Claude Code via native plugin marketplace
claude plugin marketplace add JayPokale/Chisle
claude plugin install chisle@chisle

# Pi via package manager
pi install npm:chisle

Usage Example

$ npx chisle
... ── summary ──  detected:  2  installed: claude-hooks, codex
Done. Restart your agent. Type /chisle in Claude Code or Pi, or just start coding.
If Chisle earns its keep, a star helps others find it: https://github.com/JayPokale/Chisle
$ npx chisle --list
chisle: detected agents:
  ? Claude Code
  ? Pi
  ? Gemini CLI
  ? Codex CLI
  ? Cursor (project-scoped)
  ? Windsurf (project-scoped)
  ? Cline (project-scoped)
  ? Kiro (project-scoped)
  ? GitHub Copilot (project-scoped)
Run npx chisle to install for the detected (?) agents.

Upgrade and Uninstall Pitfalls

Running npx chisle again does not upgrade; each install path skips if already present, so the upgrade command prints a success summary but changes no files. --update binds "force overwrite" and "already installed" checks together. npx chisle may use a cached package; upgrades must include @latest.

Cursor, Windsurf, Cline, Kiro, and Copilot write rule files into the project repo, so upgrades must be run in each project containing those files.

Nine-Client Integration

Each client has a detection expression and install method. Claude Code and Pi receive full support; the other seven receive only static rules.

Claude Code : Plugin; falls back to standalone hook + settings.json merge + status-bar badge. Scope: Global. Detection: claude command.

Pi : Pi package containing extension and skill pack. Scope: Global. Detection: pi command.

Gemini CLI : Gemini extension. Scope: Global. Detection: gemini command.

Codex : Appends a marked rule segment to ~/.codex/AGENTS.md. Scope: Global. Detection: codex command or ~/.codex directory.

Cursor : .cursor/rules/chisle.mdc. Scope: Project. Detection: cursor command or ~/.cursor directory.

Windsurf : .windsurf/rules/chisle.md. Scope: Project. Detection: Command or ~/.windsurf, ~/.codeium/windsurf directories.

Cline : .clinerules/chisle.md. Scope: Project. Detection: Editor extension directory contains cline.

Kiro : .kiro/steering/chisle.md. Scope: Project. Detection: kiro command or ~/.kiro directory.

GitHub Copilot : .github/copilot-instructions.md. Scope: Project. Detection: Editor extension directory contains copilot.

Detection syntax uses || to chain conditions: cmd: checks command existence, dir: checks directory, file: checks file, vscode-ext: searches four extension directories ( .vscode, .vscode-server, .cursor, .windsurf under extensions/). Command detection uses sh -c "command -v xxx" (or where on Windows), enabling cross-platform operation with zero dependencies.

Full Installer Command Surface

npx chisle

: Auto-detect and install npx chisle --list: Only detect, list assistants, no install npx chisle --stats: Print compressor cumulative saved chars and token estimate, read-only npx chisle@latest --update: Refresh all installed clients, no new installs npx chisle --only <id>: Limit to one client, repeatable npx chisle --dry-run: Print files that would change, no modifications npx chisle --force: Reinstall/overwrite even if already installed npx chisle --uninstall / -u: Uninstall all npx chisle --config-dir <path>: Override Claude config dir (default $CLAUDE_CONFIG_DIR or ~/.claude) npx chisle --no-color: Disable ANSI colors npx chisle --help / -h: Help

Besides /chisle toggle, Claude Code has three slash commands (defined in commands/*.toml): /chisle-audit [path]: Review a diff, file, or entire repo; lists over-engineered code and verbose comments/docs sorted by removable volume; reports only, no edits. /chisle-review [file]: Inspect current diff or a file; flags over-engineering, single-implementation abstractions, reinvented standard library. /chisle-help: Quick reference card.

All Switches

# Default mode: env var first, then config file, then default on
export CHISLE_DEFAULT_MODE=off
# or write to ~/.config/chisle/config.json
{ "defaultMode": "off" }
# Input-side compression, shared switch for Claude Code and Pi
CHISLE_COMPRESS=0          # disable entire compression
CHISLE_COMPRESS_SCRUB=0    # disable lossless scrub only
CHISLE_COMPRESS_DEDUP=0    # disable duplicate marking only
CHISLE_COMPRESS_SPILL=0    # disable disk spill (loses recovery path)
CHISLE_COMPRESS_MAX_CHARS=8000  # truncate only above this char count
CHISLE_COMPRESS_HEAD_LINES=60   # retain this many head lines
CHISLE_COMPRESS_TAIL_LINES=40   # retain this many tail lines
CHISLE_COMPRESS_TOOLS=bash,grep # override tool whitelist
CHISLE_UPDATE_CHECK=0      # disable version check (default: major version only, cached 3 days)

Three Lines, Three Hooks — Where Chisle Attaches in the Session

Chisle's architecture: no resident process, no server; all logic hooks into the client's own lifecycle events at three points, each handling one concern.

1. Architecture Overview

The three hooks correspond to three different frequency moments—by design. Rule injection is expensive (~1.6k tokens) so it happens once per new session. Per-turn reminders are cheap (~50 tokens) so they fire every turn. Compression triggers on demand, only when a tool actually returns a large output.

Session start (once per new session)
└─ SessionStart → chisle-activate.js → write toggle flag + inject full rules
    Resume/clear/compress only return one line

Each user prompt (every input)
└─ UserPromptSubmit → chisle-mode-tracker.js → parse toggle + append reminder

Each tool return (every call)
└─ PostToolUse → chisle-compress-output.js → scrub → truncate → dedup → restore original structure

2. Module Responsibilities

Install & Detect : Detection, install, upgrade, uninstall for nine clients; selects install path per client type

Settings Write : Fault-tolerant read/write of settings.json; strips entries client would reject; atomic write

Config Parse : Decides default toggle (env var → config file → default on); safe read/write of toggle flag file

Session Start Hook : Writes flag; decides rule injection amount by event source; prompts status bar; warns deprecated settings; major version update notice

Per-Turn Hook : Parses on/off from user input; writes flag; appends per-turn reminder

Compression Hook : Whitelist check; extracts plain text; dedup; scrub; truncate; restore return structure; accounting

Mode Parse : Shared regex set mapping colloquial phrases to on/off

Status Bar Script : Pure shell rendering [CHISLE] badge; draws progress bar from quota in stdin; shows cumulative saved tokens

Single-Source Rule Generation : One rule body generates five client rule files; --check mode for CI drift detection

Client Extension : Pi-side injection, toggle, badge, and tool_result compression

Benchmark Suite : Four test suites: four-way comparative, correctness, real-repo, offline replay

Compressor's Three Layers and Backup Mechanism

Goal: shrink output without hiding what the model must see.

First Gate: Which Tools Are Allowed

Whitelist (not blacklist) is hard-coded:

// hooks/chisle-compress-output.js:52
// Read/Edit/Write intentionally omitted: their outputs participate in exact-match edits
const SAFE_TOOLS = [
  'Bash', 'Agent', 'WebFetch', 'WebSearch', 'Grep', 'Glob'
];

Whitelist is mandatory because Read output is later used by Edit 's old_string for exact matching; cutting the middle would make the model edit against text it never saw, directly corrupting files. This is a file-corruption path, so explicit allow is required, not default-allow with exceptions. mcp__ -prefixed tools are separately allowed as read-only info tools. Data-backed: in measured corpus, the largest incompressible oversized output was full-file Read at 327 calls, 5.62M characters. Since the compressor cannot touch it, the rule side separately provides reading-habit rules to address upstream.

Second Gate: Three Sequential Layers

Layer 1: scrub() — lossless. Strips terminal control codes, trailing whitespace, collapses ≥3 consecutive newlines into one, collapses ≥4 identical consecutive lines into one line plus a "repeated N times" marker. Runs only when output exceeds 1k characters.

Layer 2: compress() — lossy but bounded. Keeps head 60 lines, tail 40 lines. Before cutting the middle, a regex extracts error-like lines (patterns for error, failed, exception, traceback, panic, timed out, cannot find, ~20 patterns), up to 12 lines, each ≤300 chars, placed below the marker. This directly addresses a real failure scenario: the single critical line in a 3000-line build log is often in the middle.

Layer 3: Deduplication — triggers only within the same session, same tool, byte-for-byte identical, and only for outputs >1800 characters.

Third Gate: If Savings Are Too Small, Don't Replace

MIN_WIN = 64

: if compression saves fewer than 64 characters, return null and the client changes nothing. This threshold is the guardrail: "don't introduce risk for trivial savings."

Backup Mechanism: Write Full Content to Disk First

The replacement marker includes the disk path, turning recovery into an exact search instead of re-running the command. The author emphasizes: re-running the command costs more than the saved characters, and for non-replayable commands it's fundamentally wrong. Directory permissions 0700, files 0600, retain only the most recent 40; CHISLE_COMPRESS_SPILL=0 disables it. A finer point: even if the spill write fails, compression proceeds normally—only the recovery path is lost. This "main path does not depend on optional step success" pattern appears multiple times in the file.

Benchmarks That Publish Even the Crash Run

The project invests more effort in "proving usefulness" than in features. The repo contains a complete benchmarking tool; raw records are committed under benchmarks/results/.

Four Suites, Each Answering One Question

Four-Way Comparative : Bare model, caveman, ponytail, Chisle — same 20 prompts, only system prompt differs; isolated HOME and config dirs to prevent personal settings leakage. Answers: How many tokens saved, how bad is the worst day.

Correctness : 32 math problems graded by exact match, 20 coding problems graded by hidden unit tests; no model-as-judge. Answers: Does shortening break correctness.

Real Repo : Five small repos each seeded with a bug; run with real tools, then copy tests in for grading. Answers: Do reuse, root-cause, fewer-file rules actually fire in real repos.

Offline Replay : Feed tool outputs from local session history into the same compression function. Answers: How much can input-side save, zero model calls.

Key Results

20 prompts, four-way comparative, token % relative to bare model: caveman: 20-Prompt Total 80%, Avg Per Prompt 98%, Worst Day 424% , Crash Count 6 / 20 ponytail: 20-Prompt Total 68%, Avg Per Prompt 91%, Worst Day 227%, Crash Count 8 / 20

Chisle : 20-Prompt Total 52% , Avg Per Prompt 69% , Worst Day 173% , Crash Count 1 / 20

Category breakdown:

Code-writing prompts (12 groups): caveman 74%, ponytail 59%, Chisle 44%

Explanation-only prompts (8 groups): caveman 103%, ponytail 104%, Chisle 87%

Short answers (10 groups): caveman 84%, ponytail 106%, Chisle 84%

Long answers (10 groups): caveman 79%, ponytail 59%, Chisle 45%

Compared to caveman, ponytail, headroom — What's the Real Difference

Four approaches to the same problem class:

Core Positioning : Chisle = Prompt + code + tool output compression; caveman = Prompt compression only; ponytail = Code compression only; headroom = Proxy-layer request rewrite

Language : Chisle = JavaScript (zero runtime deps); others not specified

Deployment : Chisle = npx one-liner, hooks into client events, no process/service; caveman / ponytail = Plugin/rule; headroom = Requires proxy

Extensibility : Chisle = Nine clients, single-source rule gen + CI drift guard; caveman / ponytail = Single client focus; headroom = Depends on proxy impl

Worst Day : Chisle = 173%, 1/20; caveman = 424%, 6/20; ponytail = 227%, 8/20; headroom = N/A

Public Failure Cases : Chisle = Yes, with correctness report; others = No

Choice depends on what you fear:

Only care about long verbose prompt replies → caveman 's specialized approach is more extreme on pure prose (and also stronger on the short-code prompts where it leads).

Care about reducing code abstraction → ponytail 's lazy-code rules are more focused.

But if you care about worst-case — i.e., "will this rule set blow up an already small output?" — the 52% average matters less than the 1/20 crash rate and 173% ceiling; the comparators' 6/20 and 8/20 show this isn't rare.

And if your token bill is dominated by tool output (CI runs, log inspection, codebase traversal), the others don't cover that at all — comparing against them is a category error.

Summary

Chisle is a three-part efficiency plugin for AI coding assistants that bundles "make the model talk less" and "make the model read less junk" into a single install package, backed by a public benchmark suite that even publishes its failure runs.

References

Project repo: https://github.com/JayPokale/Chisle
Official docs: https://chisle.jaypokale.me
Related article: https://github.com/JayPokale/Chisle/blob/main/benchmarks/results/2026-09-14-quality-and-agentic.md