PRECC — Predictive Error Correction for Claude Code#

PRECC saves ~34 % of Claude Code costs through three savings pillars: correcting bash commands before they fail, compressing tool output, and reducing context token usage via semantic search and file compression. v1.1 adds a token-cost prediction oracle ( precc predict) that ships its own trainable ridge model, and opt-in counterfactual telemetry for measuring would-have-run vs. did-run deltas. Ships as a single Rust binary.

Three Savings Pillars#

Pillar 1: Command Correction & Output Compression#

• Fixes wrong-directory commands — Detects when cargo build or npm test is run in the wrong directory and prepends cd /correct/path &&
• Prevents repeated failures — Learns from past session failures and auto-corrects commands that would fail the same way
• Compresses CLI output — Rewrites verbose commands for 60-90% smaller output via RTK
• Suggests GDB debugging — When a command fails repeatedly, suggests precc debug

Pillar 2: Semantic Code Search (cocoindex-code)#

• Optional AST-aware semantic search across 28+ languages, saving ~70% of search tokens
• Built into the precc-hook binary; no extra scripts needed
• Requires separate cocoindex-code install ( pipx install cocoindex-code)

Pillar 3: Context File Compression#

• Strips filler words from CLAUDE.md and memory files via precc compress
• Reduces tokens loaded on every API call (~30 % compression)
• Backups saved automatically, revertible with precc compress --revert

Token-Cost Prediction Oracle (v1.1)#

precc predict records a prediction → actual labelled dataset for any multi-step task you plan in tokens (never in wall-clock time). It ships two predictors:

• heuristic-1 — rule-based category × length estimator, available out of the box.
• trained-v1 — closed-form ridge regression on category + log(description length), persisted to ~/.local/share/precc/predict_model.json. Fit it from your own closed predictions with precc predict --train; subsequent predictions are tagged trained-v1 automatically.

bash

precc predict "<task description>"               # log a prediction
precc predict --record <id> <actual_tokens>       # close the loop
precc predict --train                             # fit trained-v1
precc predict --eval                              # MAPE per category

Counterfactual Telemetry (v1.1, opt-in, dormant by default)#

The hook can record a (would-have-run, did-run, outcome) triple per Bash invocation to a SQLCipher-encrypted store at ~/.local/share/precc/triples.db. The stream is opt-in only — disabled by default; you turn it on per machine via the [counterfactual] section of consent.toml (CLI ceremony lands in a future release). A daily-rotated salt + agent-class fingerprint keeps the data re-identification-resistant; nothing leaves the machine until a separate upload path is configured. The telemetry schema is designed for k-anonymity, with a documented threat model.

Install#

bash

curl -fsSL https://peria.ai/install.sh | bash
precc init

The install script downloads a platform-specific binary from GitHub Releases, verifies its SHA256 checksum, and places it in ~/.local/bin. It then configures a PreToolUse hook in ~/.claude/settings.json.

Live Status Line#

PRECC includes a built-in status line that shows real-time session metrics directly in the Claude Code terminal:

text

PRECC: 12 fixes, ~3.6K tokens saved | 2.1ms avg

The status line is automatically configured during installation. It shows:

• Corrections — commands fixed in the current session
• Tokens saved — estimated token savings from all corrections
• Hook latency — average hook execution time

To enable manually, add to ~/.claude/settings.json:

json

{
  "statusLine": {
    "type": "command",
    "command": "~/.local/bin/precc-hook --statusline"
  }
}

What PRECC Modifies#

• ~/.claude/settings.json — Adds a PreToolUse hook entry pointing to precc-hook
• ~/.local/share/precc/ — SQLite databases for learned failure-fix patterns and skill heuristics
• ~/.local/bin/ — Installs precc, precc-hook, and precc-learner binaries

Usage#

Once installed, PRECC works automatically as a PreToolUse hook.

bash

# Mine existing session history for failure-fix patterns
precc ingest --all

# View what PRECC has learned
precc skills list

# View unified savings report (all three pillars)
precc savings

# Semantic code search (requires cocoindex-code)
ccc init && ccc index
ccc search "authentication middleware"

# Compress context files
precc compress --dry-run   # preview
precc compress             # compress
precc compress --revert    # revert

# Token-cost prediction (v1.1)
precc predict "<task description>"
precc predict --record <id> <actual_tokens>
precc predict --train      # fit trained-v1 once you have ≥ 10 actuals
precc predict --eval       # mean error / MAPE

Measured Results#

MetricValueCost savings****$296 / $878 (34%)Failures prevented352 / 358 (98%)Bash calls improved894 / 5,384 (17%)Cache reads saved988M / 1.67B tokens (59%)Hook latency2.93ms avg (1.77ms overhead)

Links#

• GitHub: https://github.com/peri-a-i/precc-cc
• ClawHub: https://clawhub.ai/skills/precc
• cocoindex-code: https://github.com/cocoindex-io/cocoindex-code
• RTK: https://github.com/rtk-ai/rtk