Integrations — tokf docs

Claude Code hook

tokf integrates with Claude Code as a PreToolUse hook that automatically filters every Bash tool call — no changes to your workflow required.

tokf hook install          # project-local (.tokf/)
tokf hook install --global # user-level (~/.config/tokf/)

Once installed, every command Claude runs through the Bash tool is filtered transparently. Track cumulative savings with tokf gain.

Custom binary path

By default the generated hook script calls bare tokf, relying on PATH at runtime. If tokf isn’t on PATH in the hook’s execution environment (common with Linuxbrew or cargo install when PATH is only set in interactive shell profiles), pass --path to embed a specific binary location:

tokf hook install --global --path ~/.cargo/bin/tokf
tokf hook install --tool opencode --path /home/linuxbrew/.linuxbrew/bin/tokf

tokf also ships a filter-authoring skill that teaches Claude the complete filter schema:

tokf skill install          # project-local (.claude/skills/)
tokf skill install --global # user-level (~/.claude/skills/)

Gemini CLI

tokf integrates with Gemini CLI as a BeforeTool hook that automatically filters run_shell_command tool calls.

tokf hook install --tool gemini-cli          # project-local (.gemini/)
tokf hook install --tool gemini-cli --global # user-level (~/.gemini/)

This registers a hook shim in .gemini/settings.json (or ~/.gemini/settings.json for --global). When --no-context is not set, it also creates .gemini/TOKF.md and patches .gemini/GEMINI.md with context about the compression indicator.

Cursor

tokf integrates with Cursor via a beforeShellExecution hook that automatically filters shell commands.

tokf hook install --tool cursor          # project-local (.cursor/)
tokf hook install --tool cursor --global # user-level (~/.cursor/)

This registers a hook in .cursor/hooks.json (or ~/.cursor/hooks.json for --global). When --no-context is not set, it also creates .cursor/rules/TOKF.md with context about the compression indicator.

Cline

tokf integrates with Cline via a rules file that instructs the agent to prefix supported commands with tokf run.

tokf hook install --tool cline          # project-local (.clinerules/)
tokf hook install --tool cline --global # user-level (~/Documents/Cline/Rules/)

This writes .clinerules/tokf.md (or ~/Documents/Cline/Rules/tokf.md for --global), which Cline auto-discovers. The rules file uses alwaysApply: true frontmatter.

Windsurf

tokf integrates with Windsurf via a rules file.

tokf hook install --tool windsurf          # project-local (.windsurf/rules/)
tokf hook install --tool windsurf --global # user-level (appends to global rules)

Project-local creates .windsurf/rules/tokf.md. Global mode appends a tokf section (with  markers for idempotent updates) to ~/.codeium/windsurf/memories/global_rules.md.

GitHub Copilot

tokf integrates with GitHub Copilot via instruction files. Copilot only supports repo-level instructions (no --global option).

tokf hook install --tool copilot

This creates .github/instructions/tokf.instructions.md (with applyTo: "**" frontmatter) and appends a tokf section to .github/copilot-instructions.md.

Aider

tokf integrates with Aider via conventions files.

tokf hook install --tool aider          # project-local (CONVENTIONS.md)
tokf hook install --tool aider --global # user-level (patches ~/.aider.conf.yml)

Project-local appends a tokf section to CONVENTIONS.md (which Aider auto-discovers). Global mode writes a conventions file and adds it to ~/.aider.conf.yml’s read: list.

OpenCode

tokf integrates with OpenCode via a plugin that applies filters in real-time before command execution.

Requirements: OpenCode with Bun runtime installed.

Install (project-local):

tokf hook install --tool opencode

Install (global):

tokf hook install --tool opencode --global

This writes .opencode/plugins/tokf.ts (or ~/.config/opencode/plugins/tokf.ts for --global), which OpenCode auto-loads. The plugin uses OpenCode’s tool.execute.before hook to intercept bash tool calls and rewrites the command in-place when a matching filter exists. Restart OpenCode after installation for the plugin to take effect.

If tokf rewrite fails or no filter matches, the command passes through unmodified (fail-safe).

OpenAI Codex CLI

tokf integrates with OpenAI Codex CLI via a Codex PreToolUse hook plus skills for guidance and discovery.

Install (project-local):

tokf hook install --tool codex

Install (global):

tokf hook install --tool codex --global

This writes a Codex PreToolUse hook to .codex/hooks.json (or ~/.codex/hooks.json for --global) and installs .agents/skills/tokf-run/SKILL.md (or ~/.agents/skills/tokf-run/SKILL.md for --global), which Codex auto-discovers.

Codex CLI 0.124.0 and newer enable lifecycle hooks by default. tokf’s Codex integration uses PreToolUse, which first appeared in Codex 0.117.0.

If the installed hook does not run, upgrade Codex or check that hooks are enabled, then restart Codex. Codex 0.129.0+ prefers [features].hooks = true; older builds used the legacy alias [features].codex_hooks = true.

Codex CLI 0.131.0 and newer support PreToolUse updatedInput, so tokf transparently rewrites matching Bash commands in-place. During installation, tokf checks the local codex --version output and installs a conservative deny-and-rerun fallback for older or unknown Codex versions so the original command does not fail open. After upgrading Codex, rerun tokf hook install --tool codex so tokf can refresh the generated shim mode. Commands without a matching tokf filter pass through unchanged.

Permission engines

tokf supports pluggable permission engines that analyse commands and decide whether to allow, deny, or prompt. This is useful for auto-approving safe commands without manual confirmation.

Dippy is an open-source permission engine with deep semantic analysis of bash commands — 34 CLI handlers covering git, aws, kubectl, docker, and more. See the external permission engine section for configuration.

Hook handle command

All hook-based integrations (Claude Code, Gemini CLI, Cursor, Codex) call tokf hook handle internally. The --format flag tells tokf which response protocol to use:

tokf hook handle                    # default: claude-code
tokf hook handle --format gemini    # Gemini CLI protocol
tokf hook handle --format cursor    # Cursor protocol
tokf hook handle --format codex     # Codex CLI protocol

The hook scripts generated by tokf hook install set --format automatically — you don’t need to pass it manually. The format also determines which JSON field the external permission engine should set (see hook JSON reference).

Creating Filters with Claude

tokf ships a Claude Code skill that teaches Claude the complete filter schema, processing order, step types, template pipes, and naming conventions.

Invoke automatically: Claude will activate the skill whenever you ask to create or modify a filter — just describe what you want in natural language:

“Create a filter for npm install output that keeps only warnings and errors” “Write a tokf filter for pytest that shows a summary on success and failure details on fail”

Invoke explicitly with the /tokf-filter slash command:

/tokf-filter create a filter for docker build output

The skill is in .claude/skills/tokf-filter/SKILL.md. Reference material (exhaustive step docs and an annotated example TOML) lives in .claude/skills/tokf-filter/references/.

Task runners

tokf also integrates with task runners like make and just by injecting itself as the task runner’s shell. Each recipe line is individually filtered while exit codes propagate correctly. See Rewrite configuration for details.