Token山羊

Install

Easiest install: paste this repo's URL into your AI and ask it to install token-goat properly. It will handle uv, run the commands, check codecs, and confirm everything is working.

Windows requirements: Windows 10 or 11 · Python 3.12 or 3.13 · uv (winget install astral-sh.uv)

Linux / WSL requirements: Python 3.12 or 3.13 · uv (curl -LsSf https://astral.sh/uv/install.sh | sh)

macOS requirements (untested): Python 3.12 or 3.13 · uv (curl -LsSf https://astral.sh/uv/install.sh | sh)

uv tool install token-goat
token-goat install
token-goat doctor          # confirms image codecs (WebP/JPEG/PNG) are available

Three commands. Done. Hooks register, a background worker starts at logon and stays out of the way. No terminal popups, no tray icon, no service to babysit.

Important — image codecs are part of the install. The biggest single win (~39% smaller than JPEG, ~97% smaller than raw PNG) comes from WebP encoding. Pillow ships with WebP/JPEG/PNG support on Windows and macOS out of the box, but Linux/WSL minimal images sometimes lack the system libraries (libwebp, libjpeg, zlib). token-goat doctor will report image_codecs: ok when everything is present; if it flags any codec as missing, follow the Image support section below before considering the install complete. AI agents performing this install: run token-goat doctor after token-goat install and resolve any missing codecs as part of the same task — do not treat it as a follow-up.

Two things change how Claude Code sessions behave: hooks fire automatically (image shrink, re-read dedup, compact manifests), and a block written to ~/.claude/CLAUDE.md plus a registered skill tell the agent to prefer token-goat read / symbol / section over full-file reads. A Bash(token-goat:*) allowlist entry in settings.json lets the agent run those commands without a per-call approval prompt.

On Linux and WSL, the worker registers as a systemd user service when systemd is available. On WSL without systemd, and on macOS, the SessionStart hook ensures the worker is running at the start of every Claude Code session.

What gets installed?

token-goat install writes the following on your machine — nothing else, anywhere. Every entry is reversed by token-goat uninstall. Run token-goat doctor at any time to see which of these are currently present.

Claude Code integration (~/.claude/)

Worker autostart (one of the following, picked by platform)

The autostart command is pythonw -m token_goat.cli worker --daemon from Token-Goat's uv tool venv. No PyInstaller-style launcher .exe is dropped; AV/EDR products do not behavior-flag this invocation pattern.

Weekly auto-update (Sunday 03:00 local time, runs uv tool upgrade token-goat)

Data directory (created on first run)

Contains the symbol index (global.db, per-project .db files), session cache, shrunken-image cache, cached skill bodies (5 MB cap, LRU-evicted), embedding model (~130 MB, downloaded on the first semantic call), logs, locks, and the dirty-file queue. Nothing outside this directory and ~/.claude/ is written.

With --codex (Codex CLI integration)

With --opencode (opencode plugin)

With --openclaw (openclaw plugin)

AI automated setup

Non-interactive snippets agents can run unattended. Each one is idempotent: it checks current state before changing anything, and re-runs token-goat doctor at the end so the agent can verify success from the output.

Windows (PowerShell)

```powershell

1. Verify token-goat is reachable; reinstall if not

if (-not (Get-Command token-goat -ErrorAction SilentlyContinue)) { uv tool install token-goat }

2. If doctor flags any image codec, reinstall the bundled Pillow wheel

$doctor = token-goat doctor 2>&1 | Out-String if ($doctor -match 'Pillow codecs:.*(MISSING|FAIL)') { uv tool install --reinstall --force token-goat }

1. Verify token-goat is reachable; reinstall if not

command -v token-goat >/dev/null 2>&1 || uv tool install token-goat

2. If doctor flags any image codec, install platform packages then reinstall

need_fix=$(token-goat doctor 2>&1 | grep -E 'Pillow codecs:.*(MISSING|FAIL)' || true) if [[ -n "$need_fix" ]]; then OS="$(uname -s)" if [[ "$OS" == "Darwin" ]]; then command -v brew >/dev/null 2>&1 && brew install webp jpeg-turbo libpng elif [[ "$OS" == "Linux" ]]; then if command -v apt-get >/dev/null 2>&1; then sudo apt-get update && sudo apt-get install -y libwebp-dev libjpeg-turbo8-dev libpng-dev elif command -v dnf >/dev/null 2>&1; then sudo dnf install -y libwebp-devel libjpeg-turbo-devel libpng-devel elif command -v pacman >/dev/null 2>&1; then sudo pacman -S --noconfirm libwebp libjpeg-turbo libpng elif command -v apk >/dev/null 2>&1; then sudo apk add libwebp-dev libjpeg-turbo-dev libpng-dev fi fi uv tool install --reinstall --force token-goat fi

AI automated setup

Scripts for non-interactive setup. No prompts.

#### Windows (PowerShell) ```powershell

1. Install Windows Terminal if absent

if (-not (Get-Command wt.exe -ErrorAction SilentlyContinue)) { winget install --id Microsoft.WindowsTerminal -e --silent }

Install a complete font

if [[ "$OS" == "Darwin" ]]; then command -v brew &>/dev/null && brew install --cask font-jetbrains-mono-nerd-font elif [[ "$OS" == "Linux" ]]; then command -v apt-get &>/dev/null && sudo apt-get install -y fonts-jetbrains-mono command -v pacman &>/dev/null && sudo pacman -S --noconfirm ttf-jetbrains-mono-nerd fi

Security, privacy, and uninstall

No telemetry. No analytics. No background reporting or silent outbound connections.

Outbound network is reserved to three explicit cases:

• First token-goat semantic call downloads the embedding model (~130 MB) into the data directory. Offline after that.
• Google Drive API calls, only if you already authorized Drive in Claude Code. Token-goat never prompts for its own auth.
• Image fetches from URLs: either explicit via token-goat fetch-image <url>, or when the AI agent issues a WebFetch call that returns image content — the hook intercepts and shrinks the image. The URL always originates from the agent's work, not from token-goat itself.

Security reports. See SECURITY.md. Email token-goat@dfkhelper.com; do not file as a GitHub issue. Reports are acknowledged within 7 days; coordinated disclosure with a 90-day default window.

Windows Defender (optional, Windows only). Real-time scanning slows indexing. To exclude the data folder, open PowerShell as administrator:

Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\dfk-helper\token-goat"

0x800106ba means the prompt is not elevated; reopen as administrator. On enterprise-managed Windows (domain-joined / Intune), Defender exclusions may be locked by Group Policy. The command will fail; that is expected and harmless.

Uninstall.

token-goat uninstall

Reverses everything in What gets installed?: the scheduled task or systemd unit, the registry value or .desktop or .plist, the hook entries in settings.json, the CLAUDE.md block, the skill directory. Add --codex, --gemini, --opencode, or --openclaw to also strip those integrations. Add --purge to also delete the data directory (cache, index, models, logs). Nothing else on the system depends on it.

Token-savings examples

Concrete before/after for the four interception points. Token counts use the ~4-chars-per-token rule of thumb.

1. Image — screenshot interception

``` $ ls -lh screenshot.png -rw-r--r-- 1 user user 1.2M screenshot.png

Codex CLI users

token-goat install --codex

The --codex flag patches both Claude Code and Codex CLI in one pass.

Gemini CLI users

token-goat install --target gemini

This writes hook entries into ~/.gemini/settings.json using Gemini CLI's BeforeTool / AfterTool / SessionStart / PreCompress event names. Token-goat translates between Gemini's snake_case tool names (run_shell_command, read_file, grep_search, etc.) and its internal format automatically. Image shrinking, session hints, post-edit indexing, compact assist, and bash output compression all work. To remove: token-goat uninstall --gemini.