Quickstart

By the end of this page every Bash tool call the agent makes flows through a compression pipeline and the agent stops paying for tokens it didn’t need.

Prerequisites

• One of the supported agent harnesses installed and working — Claude Code, Cursor, or GitHub Copilot CLI. tokenshift install detects which you have and wires the right hooks for each.
• Your tenant ID (a UUID handed to you at onboarding) — required for telemetry, recovery sync, and any cloud-side feature. Skippable if you only want the local proxy and hooks. See Enrollment.

1. Download the binary

All artifacts are signed and hosted on Cloudflare R2. Each link below redirects to a presigned URL valid for 5 minutes; if it expires before the download completes, click it again.

Platform	Architecture	Download
macOS	Apple Silicon (arm64)	tokenshift_darwin_arm64.tar.gz
macOS	Intel (amd64)	tokenshift_darwin_amd64.tar.gz
Linux	x86_64 (amd64)	tokenshift_linux_amd64.tar.gz
Linux	aarch64 (arm64)	tokenshift_linux_arm64.tar.gz
Windows	x86_64 (amd64)	tokenshift_windows_amd64.tar.gz

Untar, drop the tokenshift binary on your PATH, done. Each archive ships a per-platform SHA-256 alongside it — verify with sha256sum -c or fetch the hash via /v1/version/latest on the ingestor.

Note

To pin a specific version, append &version=0.4.0 to the URL. Without version, the link resolves to whichever release is currently promoted on the stable channel. Don’t embed presigned URLs in scripts — they expire in 5 minutes. Hit /api/download?... from your MDM each time to mint a fresh URL.

Signed .pkg, .msi, .deb, and .rpm installers for MDM rollouts are shipped via PointFive’s MDM channel rather than this download endpoint — talk to your PointFive contact.

2. Wire the agent hooks

1. Run the install:

   tokenshift install

   The installer detects which agent harnesses are installed and wires the right hook file for each — ~/.claude/settings.json for Claude Code, ~/.cursor/hooks.json for Cursor, ~/.copilot/hooks/tokenshift.json for GitHub Copilot CLI. The picker also asks about telemetry opt-in the first time you run it.

2. Bind the binary to your tenant:

   tokenshift enroll --tenant-id=00000000-0000-4000-8000-000000000001

   One flag — everything else is defaulted (Tier 2 telemetry, raw directory name as the project label). This writes ~/.tokenshift/enrollment.json. Without it, TokenShift still compresses locally; telemetry just stays off. Need to override a default, or prefer a manifest file? See Enrollment.

3. Verify the wire is live end-to-end:

   tokenshift doctor --verify

   Ships one synthetic record through the live ingest path and reports acceptance. Drop --verify for a no-network status check.

Tip

tokenshift doctor is also the first thing to run when something feels off — it reports pinning, manifest, telemetry, and hook state in one block.

What just happened

• The agent’s Bash tool now invokes tokenshift hook post-tool after every shell command. The hook matches the command, runs a compression pipeline, and rewrites the tool output the model sees.
• Full output is preserved in a local recovery cache. The model gets a hint like [Full output: tokenshift recover a1b2c3d4] and can fetch the original whenever it needs it.
• Telemetry, if you enrolled, ships hybrid-encrypted records straight to the ingest endpoint. No control plane, no broker.

Next

• How it works — the architectural overview.
• Core commands — doctor, dashboard, recover, and the other handful you might run by hand.
• Security overview — what stays local, what goes off-device.