terse

🌈 99.9% vibe engineered with Claude Opus 4.6. Don't come for me.

terse is a Rust CLI that intercepts shell commands from Claude Code hooks, runs them through an optimization pipeline, and returns compact output designed to reduce token usage while preserving key signal.

Table of contents

• Installation
  • One-liner install (recommended)
  • From source
• Quick start
• What it does
• Current implemented scope
  • Fast path optimizers
  • Smart path
  • Safety gates
• Architecture overview
• Hook setup (manual / from-source builds)
• CLI usage
  • Core
  • Analytics
  • Diagnostics
  • Installation management
  • Config management
  • Web dashboard
• Smart path setup (Ollama)
• Configuration
• Runtime files
• Development
• Web dashboard details
• Status

Installation

One-liner install (recommended)

Downloads the latest release binary, places it in ~/.terse/bin/, creates a default config, and registers the Claude Code hook — all automatically.

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/benwelker/terse/master/scripts/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/benwelker/terse/master/scripts/install.ps1 | iex

Both scripts will:

1. Download the correct binary for your platform/architecture
2. Place it in ~/.terse/bin/ and add to PATH
3. Generate a default ~/.terse/config.toml
4. Check for Ollama availability (optional, for Smart Path)
5. Register the PreToolUse hook in ~/.claude/settings.json

To update or uninstall:

terse update              # update to latest release
terse uninstall           # remove hook, PATH, and all files

Uninstall accepts --keep-data to preserve config and logs.

From source

git clone https://github.com/benwelker/terse.git
cd terse
cargo build --release

Binary path after release build:

• Windows: target\release\terse.exe
• macOS/Linux: target/release/terse

After building from source, run terse config init to create your config and see PATH setup instructions, then register the hook manually (see Hook setup below).

Quick start

# Verify installation
terse health

# Preview routing + optimization for a command
terse test git status

# View aggregate token savings after usage
terse stats

Example terse test git status output:

terse Optimization Preview
==================================================
	Command:       git status
	Hook decision: rewrite
	Path taken:    fast
	Optimizer:     git
	Tokens:        120 -> 28 (76.67% savings)

--- Output ---
branch: main...origin/main
modified (2): src/main.rs, README.md
untracked (1): notes.txt

What it does

• Rewrites safe Bash tool commands to terse run "<original command>" via Claude PreToolUse hook protocol
• Routes output through:
  • Fast path (rule-based optimizers: git, file, build, docker, generic)
  • Smart path (local LLM via Ollama, opt-in)
  • Passthrough (for unsafe/small/unoptimizable cases)
• Applies a deterministic preprocessing pipeline before path selection:
  • Noise removal (ANSI/progress/spinner/boilerplate cleanup)
  • Path filtering (collapses verbose dependency/build paths)
  • Deduplication (collapses repeated lines)
  • Truncation (head/tail preserve when still oversized)
  • Whitespace normalization (trim + blank-line cleanup)
• Logs analytics and events for stats/trends/discovery

Current implemented scope

Fast path optimizers

Currently implemented fast-path optimizers:

• git — Git porcelain/history/diff/worktree compaction
• file — file/listing/content command compaction
• build — test/build/lint output summarization
• docker — container/image/log/build output compaction
• generic — fallback whitespace + line-cap compaction

Supported command families include:

• Git: git status, git log, git diff, git branch, git show, git stash, git worktree, short summaries for git push|pull|fetch|add|commit
• File/system: ls|dir|Get-ChildItem, find, cat|head|tail|type|Get-Content, wc, tree
• Build/test/lint: cargo|npm|yarn|pnpm|dotnet|go|maven|gradle|make|cmake|msbuild|pip build/test/lint families
• Docker: docker ps, docker images, docker logs, docker inspect, docker build, docker pull|push, docker compose ps|build, docker network|volume ls

Smart path

• Uses Ollama HTTP API (/api/chat)
• Disabled by default; enabled via config or TERSE_SMART_PATH=1
• Performs validation before accepting LLM output

Safety gates

Never optimized:

• Destructive/editor commands like rm, mv, vim, code, etc.
• Commands with file output redirection (>, >>)
• Heredoc-heavy commands
• Existing terse run ... calls (infinite-loop guard)

Architecture overview

1. Claude Code triggers PreToolUse hook (terse hook)
2. Hook either:
   • returns {} (passthrough), or
   • rewrites command to terse run "..."
3. terse run executes original command
4. Router preprocesses output (noise removal, path filtering, dedup, truncation, whitespace normalization) and selects path based on config + output size
5. Optimized output is printed to stdout and logged

Hook setup (manual / from-source builds)

If you used the install script, the hook is already registered. For manual or from-source installs, add a PreToolUse hook entry to ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/terse hook"
          }
        ]
      }
    ]
  }
}

CLI usage

Core

terse hook
terse run <command>

Analytics

terse stats [--format table|json|csv] [--days N]
terse analyze --days N [--format table|json|csv]
terse discover [--format table|json|csv] [--days N]

Diagnostics

terse health
terse test <command>

Installation management

terse update                         # update to latest GitHub release
terse update --force                 # skip confirmation prompt
terse uninstall                      # remove hook, PATH, and all files
terse uninstall --keep-data          # preserve config and logs
terse uninstall --force              # skip confirmation prompt

Config management

terse config show
terse config init [--force]
terse config set <dotted.key> <value>
terse config reset

Web dashboard

terse web                          # opens http://127.0.0.1:9746
terse web --addr 0.0.0.0:8080      # custom bind address

Smart path setup (Ollama)

1. Install Ollama
2. Pull a model (default expected model is llama3.2:1b)

ollama pull llama3.2:1b

3. Enable smart path:

TERSE_SMART_PATH=1

or in config:

[smart_path]
enabled = true
model = "llama3.2:1b"
ollama_url = "http://localhost:11434"

Configuration

Config hierarchy used by terse:

1. Built-in defaults
2. Global config: ~/.terse/config.toml
3. Project config: .terse.toml
4. Environment overrides: TERSE_*

Generate a starter config:

terse config init

Useful env vars:

• TERSE_ENABLED
• TERSE_MODE (hybrid, fast-only, smart-only, passthrough)
• TERSE_PROFILE (fast, balanced, quality)
• TERSE_SAFE_MODE
• TERSE_SMART_PATH
• TERSE_SMART_PATH_MODEL
• TERSE_SMART_PATH_URL
• TERSE_SMART_PATH_TIMEOUT_MS

Runtime files

• Config: ~/.terse/config.toml
• Legacy smart-path JSON fallback: ~/.terse/config.json
• Command analytics log: ~/.terse/command-log.jsonl
• Raw hook event log: ~/.terse/events.jsonl
• Hook diagnostic log: ~/.terse/hook.log

Development

cargo build
cargo test
cargo clippy
cargo fmt --check

Live LLM integration tests (requires Ollama running):

TERSE_TEST_LLM=1 cargo test llm_live

Web dashboard details

terse ships with a built-in web dashboard — a single-page app compiled into the binary with zero external dependencies.

terse web

Opens http://127.0.0.1:9746 in your default browser and serves:

• Dashboard — total commands, token savings, path distribution bar, top commands table
• Trends — daily bar chart of token savings over the last 30 days
• Discovery — passthrough/smart-path commands that could benefit from new fast-path optimizers
• Configuration — form-based editor for all key settings, saving directly to ~/.terse/config.toml

The server is synchronous (tiny_http), single-threaded, and binds to localhost only by default. Override with --addr.

Status

This repository is an actively evolving implementation. The long-range roadmap and phase plan are tracked in:

• .claude/plans/terse-FINAL-Plan.md

Current codebase already includes hook integration, router, preprocessing pipeline, fast-path optimizers (git, file, build, docker, generic), LLM smart path integration, analytics commands, TOML-based configuration management, web dashboard, cross-platform support, and CI/CD workflows.