Skip to content
Back to search

token-savior

MCP server that gets Claude to 97.9% (188/192) on a real coding benchmark at -80% active tokens and -83% wall time, vs 78.3% plain. Structural code navigation + persistent memory engine. Works with every MCP client.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mibayy--token-savior/badge.svg)](/listings/mibayy--token-savior)

HTML

<a href="/listings/mibayy--token-savior"><img src="/api/listings/mibayy--token-savior/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

pip install "token-savior-recall[mcp]"

Add to your MCP config (e.g. Claude Code):

{
  "mcpServers": {
    "token-savior-recall": {
      "command": "/path/to/venv/bin/token-savior",
      "env": {
        "WORKSPACE_ROOTS": "/path/to/project1,/path/to/project2",
        "TOKEN_SAVIOR_CLIENT": "claude-code",
        "TOKEN_SAVIOR_PROFILE": "optimized"
      }
    }
  }
}

That's it. **`TOKEN_SAVIOR_PROFILE=optimized`** ships the Pareto-optimum config that wins tsbench. It bundles:

- `tiny_plus` (15 hot tools manifest) - thin inputSchema (-44% manifest) - capture sandbox disabled - memory hooks gated for cross-project safety

No other tuning needed.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 528 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <!-- mcp-name: io.github.Mibayy/token-savior -->
  2. <div align="center">
  3. # Token Savior
  4. > One MCP server. One profile. **97.9% on tsbench at -80% tokens.**
  5. > Structural code navigation, persistent memory, and Bash command rewriting for AI coding agents.
  6. [![PyPI](https://img.shields.io/pypi/v/token-savior-recall?color=orange&label=pypi)](https://pypi.org/project/token-savior-recall/)
  7. [![Benchmark](https://img.shields.io/badge/tsbench-97.9%25%20(188%2F192)-brightgreen)](https://mibayy.github.io/token-savior/)
  8. [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
  9. [![MCP](https://img.shields.io/badge/MCP-compatible-purple.svg)](https://modelcontextprotocol.io)
  10. [![CI](https://github.com/Mibayy/token-savior/actions/workflows/ci.yml/badge.svg)](https://github.com/Mibayy/token-savior/actions/workflows/ci.yml)
  11. **[mibayy.github.io/token-savior](https://mibayy.github.io/token-savior/)** -- project site + benchmark landing
  12. Benchmark source + fixtures: not currently published (see *Reproducing the score* below)
  13. <a href="https://github.com/Mibayy/token-savior/releases/download/v4.23.2/token-savior-v4-23.mp4">
  14. <img src="docs/media/v4-23-preview.gif" width="800" alt="Plain Claude Code against Claude Code + Token Savior: 92,609 vs 38,150 new tokens, cost -45%">
  15. </a>
  16. <sub>v4.23 in 31 seconds, measured on 2026-10-07 · <a href="https://github.com/Mibayy/token-savior/releases/download/v4.23.2/token-savior-v4-23.mp4">watch the full video (MP4, sound on)</a></sub>
  17. ---
  18. ### Benchmark -- 96 real coding tasks (Claude Opus 4.7, May 2026)
  19. | | Plain Claude Code | With Token Savior |
  20. |---|---:|---:|
  21. | **Score** | 141 / 180 (78.3%) | **188 / 192 (97.9%)** |
  22. | **Active tokens / task** | 17 221 | **3 395** (-80%) |
  23. | **Wall time / task** | 110.6 s | **18.9 s** (-83%) |
  24. Reproduces with the `optimized` profile (single env var). The harness that
  25. produced these numbers is described below; its repository is not public at the
  26. moment, so take the figures as reported rather than as independently verifiable.
  27. **A re-measurement was published here on 2026-08-09 and has been withdrawn on
  28. 2026-08-10.** It reported new-token savings from a small replacement harness.
  29. Those numbers did not measure this server at all: across 143 benchmark
  30. sessions, **exactly one** called a Token Savior tool. The client running the
  31. harness had MCP deferred-tool loading enabled, so all 18 tools sat behind a
  32. `ToolSearch` lookup instead of appearing in the model's manifest. The model
  33. never saw them and fell back to `Grep` and `Read` — 66 greps, 30 reads, one
  34. MCP call. What varied between the "profiles" was the size of the cached
  35. prefix, not what the agent did.
  36. The lesson is worth more than the numbers were: **a benchmark of an MCP server
  37. must assert that its tools were actually called.** Ours did not, so it happily
  38. compared two identical agents. That assertion now exists in the harness.
  39. The headline figures above therefore stand as reported and unverified, as
  40. stated in the previous paragraph.
  41. **Re-measured on 2026-10-07, with the tools actually called.** Same 8 tasks
  42. on a frozen copy of this repo (commit `9d15a1e`, no `CLAUDE.md`), Claude
  43. Haiku 4.5, plain Claude Code against the `auto` profile with `alwaysLoad`.
  44. The harness checks that the Token Savior sessions really called the server.
  45. | 3 passes, mean ± sd | Plain Claude Code | **v4.23.0 `auto`** |
  46. |---|---:|---:|
  47. | **Cost, 8 tasks** | $0.226 ± 0.011 | **$0.123 ± 0.020 (-45%, range -39% to -53%)** |
  48. | **New tokens** | 92 609 ± 6 731 | **38 150 ± 7 618 (-59%)** |
  49. | **Sessions that used TS** | — | **23 / 24** |
  50. | **Wall time, 8 tasks** | 157 ± 26 s | 216 ± 9 s (+40%) |
  51. All 48 sessions succeeded. v4.22.0, measured once, saved 14% and used the tools
  52. in 5 sessions out of 8. Editing, measured on 2026-10-08 on the same repository (3 tasks in files of
  53. 1 900 to 3 700 lines, graded by running the code and the module's tests,
  54. 4 passes): every session of both arms succeeded, and cost is too noisy to call
  55. a gain (from -54% to +16% per pass). Native `Edit` only needs a partial
  56. `Read`, so there is little left to remove there.
  57. Wall time is worse because each benchmark session starts a fresh server that
  58. indexes the repo first; a long-lived session pays that once. What moved from
  59. v4.22.0 to v4.23.0 is mostly wording: `search_codebase` now names the function
  60. holding each hit, and the tool descriptions say plainly which native call they
  61. replace.
  62. </div>
  63. ---
  64. ## Who starred this repo?
  65. [![starscope](https://starscope.duckdns.org/badge/Mibayy/token-savior.svg)](https://starscope.duckdns.org/r/_Na5VtAKXt-H)
  66. On June 30, 2026 GitHub restricted stargazer and watcher lists to repo admins and
  67. collaborators, which broke every "who starred my repo" tool at once. I rebuilt one
  68. that still works, precisely because it only reads repos you own or can push to:
  69. **[starscope](https://starscope.duckdns.org)** ranks the people who starred or
  70. forked your repo by influence, and surfaces their social accounts when their
  71. GitHub profile declares them.
  72. Numbers on this very repo, computed with it: 1,147 people, 27% with a public
  73. social account, and the most followed carries 18,922 followers. The named list is
  74. visible to the repo owner and to nobody else — the [public
  75. page](https://starscope.duckdns.org/r/_Na5VtAKXt-H) shows aggregates only.
  76. ---
  77. ## What's new
  78. Release notes live where they can't drift out of sync with the code:
  79. - [CHANGELOG.md](CHANGELOG.md) for the full history
  80. - [Releases](https://github.com/Mibayy/token-savior/releases) for the tagged builds
  81. - [PyPI](https://pypi.org/project/token-savior-recall/) for what `pip` will actually give you
  82. ---
  83. ## Quick start
  84. ```bash
  85. pip install "token-savior-recall[mcp]"
  86. ```
  87. Add to your MCP config (e.g. Claude Code):
  88. ```json
  89. {
  90. "mcpServers": {
  91. "token-savior-recall": {
  92. "command": "/path/to/venv/bin/token-savior",
  93. "alwaysLoad": true,
  94. "env": {
  95. "WORKSPACE_ROOTS": "/path/to/project1,/path/to/project2",
  96. "TOKEN_SAVIOR_CLIENT": "claude-code",
  97. "TOKEN_SAVIOR_PROFILE": "optimized"
  98. }
  99. }
  100. }
  101. }
  102. ```
  103. **`"alwaysLoad": true`** matters on Claude Code (2.1.28x and later): without
  104. it, every tool of the server sits behind ToolSearch and the model reaches for
  105. `Read` and `Grep`, which are already loaded. Measured on this project's
  106. benchmark before the option existed: one session in 143 called a Token Savior
  107. tool. With it, the manifest costs a few thousand cached tokens per session.
  108. That's it. **`TOKEN_SAVIOR_PROFILE=optimized`** ships the Pareto-optimum
  109. config that wins tsbench. It bundles:
  110. - `tiny_plus` (15 hot tools manifest)
  111. - thin inputSchema (-44% manifest)
  112. - capture sandbox disabled
  113. - memory hooks gated for cross-project safety
  114. No other tuning needed.
  115. ---
  116. ## Activation (Bash compaction + rewriting)
  117. Bash compaction and the PreToolUse rewriter are opt-in. Two env vars and
  118. one CLI call:
  119. ```bash
  120. export TS_BASH_COMPACT=1 # PostToolUse output compactors (34 of them)
  121. export TS_BASH_REWRITE=1 # PreToolUse command rewriter (10 rules)
  122. ts init --agent claude --yes # auto-merge hooks into ~/.claude/settings.json
  123. ```
  124. `ts init` is idempotent. It detects existing hook entries, dedups by
  125. `(matcher, command)`, prints a unified diff, and backs up `settings.json`
  126. to `.bak-YYYYMMDD-HHMMSS` (UTC) before writing. Supported agents:
  127. `claude`, `cursor`, `gemini`, `codex`, `openclaw`. Pass `--dry-run` to preview, or
  128. `--global` to write the user-level config.
  129. Optional audit log of every rewrite:
  130. ```bash
  131. export TS_BASH_REWRITE_LOG=$HOME/.local/state/token-savior/rewrites.jsonl
  132. ```
  133. ---
  134. ## Compactor catalog (34)
  135. | Family | Compactors |
  136. |---|---|
  137. | git | `status`, `diff`, `log`, `push`/`pull`, `commit`, `add`, `fetch`, `checkout`, `branch`, `worktree list`, `stash list` |
  138. | gh | `run list`, `run view`, `pr diff`, `pr view`, `issue view`, `repo view` |
  139. | test/lint | `pytest`, `jest`, `vitest`, `eslint`, `biome`, `cargo test`, `cargo build`/`clippy`, `tsc` |
  140. | cloud | `kubectl get`, `kubectl logs`, `aws sts`, `aws ec2`, `aws lambda`, `aws logs`, `aws iam`, `aws dynamodb`, `aws s3` |
  141. | docker | `docker ps`, `docker logs` |
  142. | packaging | `npm/yarn/pnpm list`, `pip list`/`show` |
  143. | shell catch-alls | `grep`, `find`, `cat`, `curl` |
  144. Each compactor is a pure function (no I/O, no globals) returning a
  145. token-efficient rendering. The dispatcher returns `None` when no matcher
  146. fires, leaving the existing sandbox path untouched. Compound commands
  147. (`cd ... && cmd`) fall through to the last meaningful segment.
  148. > **These run in PostToolUse, so they do not shrink the current turn.** The
  149. > hook fires after the tool has returned; it can add context, not remove it.
  150. > The compact rendering is appended below the raw output, which stays. What
  151. > you gain is persistence: the full output goes to the capture sandbox and
  152. > outlives a context compaction. For an actual reduction of what reaches the
  153. > model, use the PreToolUse rewriter (`TS_BASH_REWRITE=1`) — it edits the
  154. > command before it runs.
  155. ---
  156. ## `ts_discover` -- find missed TS opportunities
  157. New MCP tool that scans your Claude Code transcripts for patterns where
  158. TS tools would have been cheaper than what the agent actually did.
  159. ```python
  160. ts_discover() # active project, last 30 days
  161. ts_discover(project=None) # ALL transcript projects
  162. ts_discover(format="adoption") # TS vs native ratio per session
  163. ts_discover(format="adoption_json") # same, JSON
  164. ```
  165. Findings: Read->Grep->Read chains, sequential `find_symbol`, edits
  166. without `get_edit_context`, `memory_search` without `memory_index`,
  167. native shell on code files. Args are pruned to load-bearing keys
  168. (PII-safe). Streams JSONL with mtime fast-skip.
  169. ---
  170. ## `ts init` CLI
  171. ```bash
  172. ts init --agent claude [--global] [--dry-run] [--yes]
  173. ts init --agent cursor
  174. ts init --agent gemini
  175. ts init --agent codex
  176. ts init --agent openclaw
  177. ```
  178. Detects the target agent's settings location, deep-merges the Token
  179. Savior hook config (`PostToolUse` + `PreToolUse`), preserves existing
  180. hooks, dedups, prints a unified diff. Backs up to
  181. `settings.json.bak-YYYYMMDD-HHMMSS` (UTC). Re-running is a no-op.
  182. ---
  183. ## What it does
  184. Claude Code reads whole files to answer questions about three lines, and
  185. forgets everything the moment a session ends. Token Savior fixes both,
  186. plus a third axis: it bounds the noisy Bash output that bloats turn
  187. budgets between code reads — by rewriting the command before it runs.
  188. It indexes your codebase by symbol -- functions, classes, imports, call
  189. graph -- so the model navigates by pointer instead of by `cat`. Measured
  190. reduction: 97% fewer chars injected across 170+ real sessions.
  191. On top of that sits a persistent memory engine. Every decision, bugfix,
  192. convention, guardrail and session rollup is stored in SQLite WAL + FTS5
  193. + vector embeddings, ranked by Bayesian validity and ROI, and
  194. re-injected as a compact delta at the start of the next session.
  195. And on top of *that*, since v4.1, sit the Bash compactors and the
  196. PreToolUse rewriter. Bench numbers above.
  197. **Which of those two actually shrinks a turn, and which does not.** Measured
  198. 2026-08-09, and worth stating plainly because the distinction is not obvious:
  199. - The **PreToolUse rewriter** changes the command *before* it runs, so a
  200. smaller output is produced and a smaller output reaches the model. This is
  201. a real reduction in the current turn.
  202. - The **PostToolUse compactors** run *after* the tool has returned. A
  203. PostToolUse hook can only *add* context; by the time it fires, the raw
  204. output has already been sent. The compact rendering is appended, it does
  205. not replace anything. What the compactors genuinely buy you is different
  206. and still valuable: the full output is preserved in the capture sandbox and
  207. survives a context compaction, so it can be queried later instead of being
  208. re-run.
  209. If your goal is a smaller turn, `TS_BASH_REWRITE=1` is the switch that does
  210. it. If your goal is to stop losing command output across compactions, that is
  211. `TS_BASH_COMPACT=1`.
  212. ---
  213. ## Profile comparison
  214. | Profile | Tools exposed | Manifest tokens | When to use |
  215. |---|---:|---:|---|
  216. | **`optimized`** | **15** | **~1.5 KT** | **Recommended default -- Pareto win on tsbench** |
  217. | `auto` | adaptive | ~1-2 KT | Per-client telemetry-based (experimental) |
  218. | `tiny` | 6 | ~0.6 KT | Minimal hot loop |
  219. | `lean` | 51 | ~4 KT | Legacy -- broader surface |
  220. | **`compact-only`** | **1** | **~0.3 KT** | **Bash layer only (rewriter + capture) -- you already run symbol nav elsewhere** |
  221. | `full` | 68 | ~6 KT | Everything exposed |
  222. You probably want `optimized`.
  223. ---
  224. ## How it composes with adjacent tools
  225. Token Savior spans several layers, and most neighbouring tools occupy exactly
  226. one of them. Overlap is opt-out per layer, so running both is usually fine once
  227. you disable the half you already have. Thanks to @chirag127 for mapping this
  228. out in #45.
  229. | Tool | Layer | Overlap | What to do |
  230. |---|---|---|---|
  231. | RTK (repo currently unreachable) | PostToolUse Bash output compression | Same layer, same PostToolUse limit: neither shrinks the current turn | Pick one. `TS_BASH_COMPACT=0` to defer to RTK |
  232. | [serena](https://github.com/oraios/serena) | Symbol-graph navigation | Direct, with `find_symbol` / `get_dependents` | Run TS as `compact-only` if serena is your navigator |
  233. | codebase-memory | Persistent code graph | With the memory engine | `TS_MEMORY_DISABLE=1` |
  234. | [Ponytail](https://github.com/DietrichGebert/ponytail), Caveman | Output-side compression (code and prose) | Partial: Token Savior ships an opt-in Ponytail-style discipline (`TS_DISCIPLINE=1`) wired to its tools | Complementary, no knob needed |
  235. The layers Token Savior owns that these do not: the PreToolUse Bash **rewriter**
  236. (it shrinks the command before it runs, not the output after), structural
  237. **editing** that keeps the index in sync, and the audit tools
  238. (`detect_breaking_changes`, `find_dead_code`, `analyze_config`).
  239. If you only want the Bash layer, `TOKEN_SAVIOR_PROFILE=compact-only` advertises
  240. a single tool and leaves the compactors and rewriter running. Of those two, the
  241. rewriter is the one that reduces the current turn.
  242. ---
  243. ## Token savings
  244. | Operation | Plain Claude | Token Savior | Reduction |
  245. |-----------|-------------:|-------------:|----------:|
  246. | `find_symbol("send_message")` | 41M chars (full read) | 67 chars | **-99.9%** |
  247. | `get_function_source("compile")` | grep + cat chain | 4.5K chars | direct |
  248. | `get_change_impact("LLMClient")` | impossible | 16K chars | new capability |
  249. | 96-task tsbench (Opus, plain vs ts) | 17 221 active/task | **3 395 active/task** | **-80%** |
  250. | 7-day Bash output bench (v4.3) | ~30 K tokens/week | ~9.6 K tokens/week | **~20.4 K/week** |
  251. ---
  252. ## Install
  253. ### pip (MCP server)
  254. ```bash
  255. pip install "token-savior-recall[mcp]"
  256. # Optional hybrid vector search:
  257. pip install "token-savior-recall[mcp,memory-vector]"
  258. ```
  259. ### uvx (no venv, no clone)
  260. ```bash
  261. uvx token-savior-recall
  262. ```
  263. ### Claude Code one-liner
  264. ```bash
  265. claude mcp add token-savior -- /path/to/venv/bin/token-savior
  266. ```
  267. ### Development
  268. ```bash
  269. git clone https://github.com/Mibayy/token-savior
  270. cd token-savior
  271. python3 -m venv .venv
  272. .venv/bin/pip install -e ".[mcp,dev]"
  273. pytest tests/ -q
  274. ```
  275. Suite size: **1898 passed, 2 skipped** on main. CI green on Python
  276. 3.11 / 3.12 / 3.13.
  277. ---
  278. ## Bench it yourself
  279. The compactor numbers above come from replaying real Claude Code
  280. transcripts through the dispatcher. Two scripts live under `scripts/`:
  281. ```bash
  282. python3 scripts/bench_compactors_real.py # match rate + mean savings
  283. python3 scripts/bench_compactors_unmatched.py # top unmatched commands
  284. ```
  285. The first walks `~/.claude/projects/*/*.jsonl`, replays every Bash
  286. output through the registry, and reports per-family savings + overall
  287. match rate. The second buckets the unmatched commands so the next
  288. compactor target is obvious from the histogram.
  289. ### Reproducing the tsbench score
  290. **Honest status, checked 2026-08-09:** the benchmark repository these
  291. instructions pointed at returns 404, and so did the BENCHMARK-SUMMARY link
  292. above. Rather than leave a recipe that cannot run, here is what the harness
  293. does, so the number can be judged on its method:
  294. - A generated toy repo (deterministic seed) with four planted traps: a symbol
  295. defined twice, a three-level call chain, an `a -> b -> c -> a` import cycle,
  296. and a dead function whose name contains a live one.
  297. - Eight read-only tasks, scored mechanically against an `expected` list and a
  298. `forbidden` list. The forbidden list is the half that matters: an answer can
  299. contain the right target *and* the wrong one, and a grader that only looks
  300. for the right one would score it correct.
  301. - A `sans_ts` control arm running plain Read/Grep/Glob, without which the
  302. bench compares Token Savior profiles to each other and can never conclude
  303. "useless" — and therefore never "useful" either.
  304. One trap worth knowing about if you rebuild it: the harness spawns
  305. `claude -p`, which inherits `~/.claude/settings.json`. If any Token Savior
  306. PreToolUse hook is enabled on the machine, it applies to the control arm too
  307. and rigs the comparison. Neutralise them in both arms
  308. (`TS_GUARD_OFF=1 TS_READ_GUARD=0 TS_BASH_REWRITE=0`).
  309. ---
  310. ## Bonus: `ts` CLI for non-MCP agents
  311. For agents without MCP (Cursor, Aider, Continue, scripts, CI), the `ts`
  312. command exposes a subset of the tools via shell:
  313. ```bash
  314. ts use /path/to/project
  315. ts get my_function # JSON output
  316. ts search 'pattern'
  317. ts daemon start # ~145ms per call vs 1.5s cold fork
  318. ts init --agent cursor # wire up Bash hooks for non-Claude agents
  319. ```
  320. On Claude Code, prefer the MCP server -- measured cheaper than CLI on
  321. Opus 4.7. The CLI is there for the portability case.
  322. ---
  323. ## Environment variables
  324. All optional. Values shown as `=1` also accept nothing else — set exactly `1`;
  325. values shown as *bool* accept `1`/`true`/`yes` (and `on` where noted).
  326. ### Server & tool manifest
  327. | Var | Default | Purpose |
  328. |---|---|---|
  329. | `WORKSPACE_ROOTS` | current dir | Comma-separated project roots to index. Codex trap: Codex whitelist-filters the MCP server environment, so an exported shell variable never arrives — set it in `config.toml` under `[mcp_servers.token-savior] env` (or `env_vars`) |
  330. | `PROJECT_ROOT` | — | Single-root alternative to `WORKSPACE_ROOTS` |
  331. | `CLAUDE_PROJECT_ROOT` | — | Deliberate active-project override (Token Savior's own contract — no host sets it). Registered if valid, wins over every other boot signal |
  332. | `TS_STICKY_ACTIVE` | off (*bool*, `on` ok) | Freeze the active project: explicit `project=` hints and absolute path arguments still route each call, but no call repoints the shared default. For parallel agents in sibling worktrees |
  333. | `TOKEN_SAVIOR_PROFILE` | `full` | Tool profile. `optimized` — the value the quickstart config and `ts init` recommend — ships the Pareto manifest, implies thin schemas, and omits the capture tools from the manifest |
  334. | `TS_THIN_SCHEMAS=1` | off (on in `optimized`) | Strip verbose tool schemas from the manifest |
  335. | `TS_DISCIPLINE` | off (*bool*) | Session instructions in the style of Ponytail: smallest complete change scoped by `get_edit_context`, reuse found by `search_codebase`, one closing line on what was skipped. Off by default: on tsbench they cost 3-4 % more per session with no measured gain |
  336. | `TS_PROMPTS` | on (*bool*) | The `review` / `audit` / `lean` MCP prompts (slash commands in Claude Code). Free until called. `0` removes them |
  337. | `TS_AUTO_HOT_K` | `8` | Hot-tool count exposed by the telemetry-driven `auto` profile (13 tools in all) |
  338. | `TS_LEVEL_BANDIT` | off | Let a Thompson-sampling bandit pick the detail level of `get_function_source` / `get_class_source` when no `level` is given. Off by default: it drifted to summaries in place of source |
  339. | `TS_EXECUTE_MAX_CHARS` | `60000` | Ceiling on a `ts_execute` result; past it the returned value is cut and the cut is reported |
  340. | `TS_GUARD_READ_FREE_LINES` | `200` | Discipline guard: whole-file `Read` of indexed code passes up to this many lines |
  341. | `TOKEN_SAVIOR_CHAIN_NUDGE` | on | `0`/`false`/`off` disables chained-tool nudges |
  342. | `TS_MEMORY_DISABLE=1` | off | Disable the memory engine (clean-context workloads) |
  343. | `TS_CAPTURE_DISABLED=1` | off | Skip read-side capture sandboxing and drop the capture tools from the manifest (no profile flips this; `optimized` only hides the capture tools) |
  344. | `TS_CODE_MODE_DISABLE=1` | off | Disable code-mode tools |
  345. | `TS_CODE_MODE_NODE` | `node` | Node binary used by the code-mode sandbox |
  346. | `TS_RESOURCES_DISABLED` | off (*bool*) | Don't expose observations as `ts://obs/{id}` MCP resources |
  347. | `TS_WARM_START` | off (*bool*) | Pre-build project slots at startup |
  348. | `TOKEN_SAVIOR_NO_WARMUP` | off (*bool*) | Skip the `ts_search` embedding warm-up |
  349. | `TS_SEARCH_COLD_DELEGATE` | off (*bool*, `on` ok) | Delegate the cold `ts_search` call to a running `ts` daemon |
  350. | `TS_SOCK` | `/tmp/ts.sock` | Unix socket of the `ts` daemon (CLI + cold delegate) |
  351. | `TOKEN_SAVIOR_CLIENT` | auto-detected | Client label (`claude-code`, …) for telemetry/client detection |
  352. | `TOKEN_SAVIOR_SESSION_LABEL` | — | Free-form label attached to session telemetry |
  353. ### Indexing
  354. | Var | Default | Purpose |
  355. |---|---|---|
  356. | `INCLUDE_PATTERNS` | built-in list | Colon-separated globs; **replaces** the default include list |
  357. | `EXCLUDE_PATTERNS` | built-in list | Colon-separated globs; **replaces** the default exclude list |
  358. | `EXCLUDE_EXTRA` | — | Colon-separated globs **appended** to the default excludes |
  359. | `TOKEN_SAVIOR_EXCLUDE_PATTERNS` | — | Colon-separated globs appended at the indexer level |
  360. | `TOKEN_SAVIOR_MAX_FILE_SIZE` | `500000` | Max file size (bytes) to index |
  361. | `TOKEN_SAVIOR_MAX_FILES` | `10000` | Max files per project |
  362. | `TOKEN_SAVIOR_WATCHER` | `auto` | File watcher: `auto` / `on` / `off` |
  363. | `TS_WATCHER_FORCE_POLLING` | off | Force the polling watcher backend |
  364. ### Claude Code hooks
  365. | Var | Default | Purpose |
  366. |---|---|---|
  367. | `TS_CAPTURE_THRESHOLD_BYTES` | `4096` | Minimum tool-output size to sandbox |
  368. | `TS_CAPTURE_REPLACE=1` | off | Strong-replace: tell the agent to ignore the inline output and `capture_get` the URI |
  369. | `TS_CAPTURE_TTL_DAYS` | `30` | Captures older than this are purged on the next `capture_put`; `0` disables the GC |
  370. | `TS_BASH_COMPACT=1` | off | PostToolUse compactors. Preserves output across compaction; does NOT shrink the current turn (see note above) |
  371. | `TS_COMPACT_INLINE_THRESHOLD` | `4096` | Hybrid mode: compact-result size above which the full original is also sandboxed |
  372. | `TS_COMPACT_TINY_THRESHOLD` | `256` | Hybrid mode: compact-result size below which the sandbox is always skipped |
  373. | `TS_BASH_REWRITE=1` | off | Enable the PreToolUse Bash command rewriter |
  374. | `TS_BASH_REWRITE_LOG` | — | JSONL audit log of every rewrite |
  375. | `TS_HOOK_MINIMAL=1` | off | SessionStart memory hook emits only the Memory Index block |
  376. ### Memory extras
  377. | Var | Default | Purpose |
  378. |---|---|---|
  379. | `TS_VIEWER_PORT` | off | Port for the observation web viewer (unset = disabled) |
  380. | `TS_AUTO_EXTRACT=1` + `TS_API_KEY` | off | LLM auto-extraction of memory observations (Anthropic API key required) |
  381. | `TS_MODEL` | `claude-sonnet-4-6` | Auto-extraction model override |
  382. | `TOKEN_SAVIOR_MEMORY_AUTO_SAVE=1` | off | Auto-save memory observations |
  383. | `TELEGRAM_BOT_TOKEN` + `TELEGRAM_CHAT_ID` | — | Critical-observation feed |
  384. ### Storage, dashboard, debugging
  385. | Var | Default | Purpose |
  386. |---|---|---|
  387. | `TOKEN_SAVIOR_STATS_DIR` | `~/.local/share/token-savior` | Telemetry + stats directory |
  388. | `TOKEN_SAVIOR_DASHBOARD_HOST` | `127.0.0.1` | Dashboard bind host |
  389. | `TOKEN_SAVIOR_DASHBOARD_PORT` | `8921` | Dashboard port |
  390. | `TOKEN_SAVIOR_INCLUDE_TMP_PROJECTS` | off (*bool*) | Dashboard also lists projects under temp dirs |
  391. | `TOKEN_SAVIOR_DEBUG=1` | off | Debug logging |
  392. | `TOKEN_SAVIOR_TRACE` | off (*bool*) | MCP request lifecycle tracing |
  393. Not knobs: `CLAUDECODE`, `CLAUDE_CODE_ENTRYPOINT`, `CLAUDE_PROJECT_DIR`,
  394. `CLAUDE_CONTEXT_REMAINING_PCT`, `CODEX_*` and `HERMES_*` are read for host/client
  395. detection and boot-time project hints — the environment sets them, you don't.
  396. (`CLAUDE_PROJECT_DIR` is what Claude Code actually exports; it always names the
  397. main checkout, never the worktree the session works in, so the launch directory
  398. outranks it when that directory is a linked worktree. `CLAUDE_PROJECT_ROOT`
  399. moved up into the knobs table: nothing sets it but you.)
  400. Naming trap: `TS_PROFILE` in the benchmark snippets is **tsbench's** variable;
  401. the server reads `TOKEN_SAVIOR_PROFILE`.
  402. ---
  403. ## License
  404. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.