rtk-ai · mpecan · Mar 13, 2026 · Mar 16, 2026 · Mar 16, 2026 · Mar 16, 2026
diff --git a/.release-please-manifest.json b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "0.29.0"
+  ".": "0.30.0"
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,40 @@ All notable changes to rtk (Rust Token Killer) will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.30.0](https://github.com/rtk-ai/rtk/compare/v0.29.0...v0.30.0) (2026-03-16)
+
+
+### Features
+
+* add rtk session command for adoption overview ([be67d66](https://github.com/rtk-ai/rtk/commit/be67d660100c06a0751c08d943dc884ad5bff6a3))
+* add rtk session command for adoption overview ([12d44c4](https://github.com/rtk-ai/rtk/commit/12d44c4068d7d4f65d5bd7551af29ab5a2352ed1)), closes [#487](https://github.com/rtk-ai/rtk/issues/487)
+* add worktree slash commands for isolated development ([#364](https://github.com/rtk-ai/rtk/issues/364)) ([ab83e79](https://github.com/rtk-ai/rtk/commit/ab83e7933ebc26ca76f843d33285729875efb913))
+* Claude Code tooling — 2 agents, 7 commands, 2 rules, 4 skills ([#491](https://github.com/rtk-ai/rtk/issues/491)) ([7b7a5ae](https://github.com/rtk-ai/rtk/commit/7b7a5ae4b6d23fbb882ed7d5e815e2ed0672c46c))
+
+
+### Bug Fixes
+
+* 6 critical bugs — exit codes, unwrap, lazy regex ([#626](https://github.com/rtk-ai/rtk/issues/626)) ([3005ebd](https://github.com/rtk-ai/rtk/commit/3005ebd0ad07912ae919687f6d3d49482aabaeac))
+* align 7 TOML filter tests with on_empty behavior ([04ed6d8](https://github.com/rtk-ai/rtk/commit/04ed6d8c314dcbf86b147903b5a7f1cd956dc980))
+* align 7 TOML filter tests with on_empty behavior ([9a499b9](https://github.com/rtk-ai/rtk/commit/9a499b9714e97a553d5603680ab1f843034acf28))
+* **cicd-docs:** add agent reviewer + some contribute guidelines ([de710f4](https://github.com/rtk-ai/rtk/commit/de710f4ea30c333130c46f8a2e2c5b6b9edd4889))
+* **cicd-docs:** some logs to understand what is happening when check docs ([191ea9a](https://github.com/rtk-ai/rtk/commit/191ea9af9f99ee78d74385fe1952ce83045e4afe))
+* **cicd:** Clean cicd, rework depends and add pre-release ([d24a765](https://github.com/rtk-ai/rtk/commit/d24a7650e26aca89224a3ec5d263f1ce7c7121d6))
+* **cicd:** Clean cicd, rework depends and add pre-release ([6303e95](https://github.com/rtk-ai/rtk/commit/6303e9530a379a8e3939e6c122ab4cf07cb16751))
+* **cicd:** clippy - do not treat warn as error ([5da5db2](https://github.com/rtk-ai/rtk/commit/5da5db222d9927394995ccaeb3afc103e80c22bd))
+* failing context for doc analyze -&gt; cat from files ([c6b7db2](https://github.com/rtk-ai/rtk/commit/c6b7db2e5a6cd9a05262e934b4fc7a44c699c3b0))
+* git log --oneline regression drops commits ([#619](https://github.com/rtk-ai/rtk/issues/619)) ([8e85d67](https://github.com/rtk-ai/rtk/commit/8e85d676d78b12d2c421bb892f93971fc222fb39))
+* improve adoption metric by detecting hook-rewritten commands ([eb8a2c4](https://github.com/rtk-ai/rtk/commit/eb8a2c4a71072870fca4b64e90189a4453acff84))
+* normalize binlogs CRLF ([5344af9](https://github.com/rtk-ai/rtk/commit/5344af9a51f06b5dc42692e42c948ff11a3173c6))
+* preserve commit body in git log output ([e189bbb](https://github.com/rtk-ai/rtk/commit/e189bbbe749120eda4d98a2130937269d8c0e92a))
+* preserve first line of commit body in git log output ([c3416eb](https://github.com/rtk-ai/rtk/commit/c3416eb45f2f97297ec149d296a6a500697d302b))
+* remove version check from validate-docs CI ([#476](https://github.com/rtk-ai/rtk/issues/476)) ([#543](https://github.com/rtk-ai/rtk/issues/543)) ([6e61c24](https://github.com/rtk-ai/rtk/commit/6e61c2447cc03af94220ce6ce83686f155e18086))
+* split chained commands in adoption metric ([127f85c](https://github.com/rtk-ai/rtk/commit/127f85c02efd52a64e461005fa142d05f81615f8))
+* support git -C &lt;path&gt; in rewrite registry ([c916bab](https://github.com/rtk-ai/rtk/commit/c916bab33ae9760b234fd720c944a849141f0d2e)), closes [#555](https://github.com/rtk-ai/rtk/issues/555)
+* test-all.sh aborts when gt not installed ([#500](https://github.com/rtk-ai/rtk/issues/500)) ([#544](https://github.com/rtk-ai/rtk/issues/544)) ([26f5473](https://github.com/rtk-ai/rtk/commit/26f547371798ad32aed3569965303bc4857789ed))
+* trust boundary followup — TOML key typo + missing meta commands ([#625](https://github.com/rtk-ai/rtk/issues/625)) ([8d8e188](https://github.com/rtk-ai/rtk/commit/8d8e188705e5784829693a83b2076d6118154764))
+* windows path fix for git tests ([0a904e2](https://github.com/rtk-ai/rtk/commit/0a904e264d58f8f4b5f10e37ec3b11f717458fe0))
+
 ## [0.29.0](https://github.com/rtk-ai/rtk/compare/v0.28.2...v0.29.0) (2026-03-12)
 
 
@@ -88,6 +122,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Features
 
+* **toml-dsl:** replace RTK's custom 8-stage filter engine with `tokf-filter` crate
+  * Full backward compatibility — all 47 built-in filters and user-authored `.rtk/filters.toml` files work unchanged
+  * RTK keeps its TOML parsing/registry/matching layer; delegates filtering to `tokf-filter::apply()`
+  * RTK handles `head_lines`/`tail_lines`/`max_lines` with omission markers (tokf silently truncates)
+  * `truncate_lines_at` now uses `…` (unicode ellipsis) instead of `...` (3 ASCII dots)
+  * Unlocks tokf's advanced features for user-authored filters: sections, chunks, aggregates, templates, JSON extraction, `on_success`/`on_failure` branches, `dedup`
 * **toml-dsl:** declarative TOML filter engine — add command filters without writing Rust ([#299](https://github.com/rtk-ai/rtk/issues/299))
   * 8 primitives: `strip_ansi`, `replace`, `match_output`, `strip/keep_lines_matching`, `truncate_lines_at`, `head/tail_lines`, `max_lines`, `on_empty`
   * lookup chain: `.rtk/filters.toml` (project-local) → `~/.config/rtk/filters.toml` (user-global) → built-in filters

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "rtk"
-version = "0.29.0"
+version = "0.30.0"
 edition = "2021"
 authors = ["Patrick Szymkowiak"]
 description = "Rust Token Killer - High-performance CLI proxy to minimize LLM token consumption"
@@ -32,6 +32,8 @@ ureq = "2"
 hostname = "0.4"
 flate2 = "1.0"
 quick-xml = "0.37"
+tokf-filter = { version = "0.2.33", default-features = false }
+tokf-common = "0.2.33"
 which = "8"
 
 [build-dependencies]

diff --git a/docs/filter-workflow.md b/docs/filter-workflow.md
@@ -40,14 +40,15 @@ flowchart TD
         S -->|"✅ match"| U["exec command\ncapture stdout"]
         U --> V
 
-        subgraph PIPELINE ["8-stage filter pipeline"]
-            V["strip_ansi"] --> W["replace"]
-            W --> X{"match_output\nshort-circuit?"}
-            X -->|"✅ pattern matched"| Y[["emit message\nstop pipeline"]]
-            X -->|"no match"| Z["strip/keep_lines"]
-            Z --> AA["truncate_lines_at"]
-            AA --> AB["tail_lines"]
-            AB --> AC["max_lines"]
+        subgraph PIPELINE ["tokf-filter pipeline + RTK post-processing"]
+            V{"match_output\nshort-circuit?\n(strip_ansi applied\nif enabled)"} -->|"✅ pattern matched"| Y[["emit message\nstop pipeline"]]
+            V -->|"no match"| W["replace\n(replace_all mode)"]
+            W --> WA["strip_ansi\ntrim_lines"]
+            WA --> Z["skip/keep lines"]
+            Z --> ZA["dedup"]
+            ZA --> AA["truncate_lines_at"]
+            AA --> AB["head/tail_lines\n(RTK adds omission\nmarkers)"]
+            AB --> AC["max_lines\n(RTK adds truncation\nmarker)"]
             AC --> AD{"output\nempty?"}
             AD -->|"yes"| AE[["emit on_empty"]]
             AD -->|"no"| AF[["print filtered\noutput + exit code"]]

diff --git a/src/filters/README.md b/src/filters/README.md
@@ -3,6 +3,9 @@
 Each `.toml` file in this directory defines one filter and its inline tests.
 Files are concatenated alphabetically by `build.rs` into a single TOML blob embedded in the binary.
 
+Filtering is powered by the [tokf-filter](https://crates.io/crates/tokf-filter) engine.
+RTK handles the TOML registry, command matching, and `head/tail/max_lines` omission markers.
+
 ## Adding a filter
 
 1. Copy any existing `.toml` file and rename it (e.g. `my-tool.toml`)
@@ -37,15 +40,27 @@ expected = "expected filtered output"
 | `description` | string | Human-readable description |
 | `match_command` | regex | Matches the command string (e.g. `"^docker\\s+inspect"`) |
 | `strip_ansi` | bool | Strip ANSI escape codes before processing |
-| `strip_lines_matching` | regex[] | Drop lines matching any regex |
-| `keep_lines_matching` | regex[] | Keep only lines matching at least one regex |
-| `replace` | array | Regex substitutions (`{ pattern, replacement }`) |
-| `match_output` | array | Short-circuit rules (`{ pattern, message }`) |
-| `truncate_lines_at` | int | Truncate lines longer than N characters |
-| `max_lines` | int | Keep only the first N lines |
-| `tail_lines` | int | Keep only the last N lines (applied after other filters) |
+| `strip_lines_matching` | regex[] | Drop lines matching any regex (alias: `skip`) |
+| `keep_lines_matching` | regex[] | Keep only lines matching at least one regex (alias: `keep`) |
+| `replace` | array | Regex substitutions (`{ pattern, replacement }`) — all occurrences per line |
+| `match_output` | array | Short-circuit rules (`{ pattern, message, unless }`) |
+| `truncate_lines_at` | int | Truncate lines longer than N characters (uses `…` ellipsis) |
+| `head_lines` | int | Keep only the first N lines (with `"... (N lines omitted)"` marker) |
+| `tail_lines` | int | Keep only the last N lines (with omission marker) |
+| `max_lines` | int | Absolute line cap after head/tail (with `"... (N lines truncated)"` marker) |
 | `on_empty` | string | Fallback message when filtered output is empty |
 
+## Pipeline order
+
+1. `match_output` — short-circuit if pattern matches (ANSI-stripped when `strip_ansi = true`)
+2. `replace` — regex substitutions, all occurrences per line, rules chained sequentially
+3. `strip_ansi` — remove ANSI escape codes
+4. `skip`/`keep` — filter lines by regex
+5. `truncate_lines_at` — truncate long lines
+6. `head_lines`/`tail_lines` — keep first/last N lines (with omission markers)
+7. `max_lines` — absolute line cap
+8. `on_empty` — message if result is empty
+
 ## Naming convention
 
 Use the command name as the filename: `terraform-plan.toml`, `docker-inspect.toml`, `mix-compile.toml`.