You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 4992161
Browse filesBrowse the repository at this point in the historyBrowse files
Changelog for the 2.9.30 changes and the version bump.
README, CONTRIBUTING, docs/cli.md and docs/install.md now describe the upgrade notice and doctor --repair, the Windows double-backslash refusal, MCP project root inference, the doctor, stats, semantic and answer options added since 2.9.29, the Copilot postToolUseFailure and subagentStart hooks, and the Lefthook jobs that actually run.
Copy file name to clipboardExpand all lines: CHANGELOG.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
3
3
All notable changes to Token-Goat are documented in this file. Format follows Keep a Changelog. Token-Goat follows Semantic Versioning starting at 1.0.
4
4
5
-
## [Unreleased]
5
+
## [2.9.30] - 2026-10-03
6
6
7
7
Upgrading reparses the index. The parser stamp moves for every language, so each file is read once more. CSS, SCSS, Less, Vue, Svelte and Astro files come back with their full rule and declaration spans, and minified bundles already in the index are removed in the same pass. Every indexed file is also re-embedded once, because the embedding stamp moved with the check that stops a slow embedding run from overwriting newer vectors; Markdown files that open with a front-matter block come back with corrected heading boundaries. The heading-matcher and spreadsheet-redaction fixes below move the parser, Markdown and Excel stamps too, and the same single pass covers them.
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+5-1Lines changed: 5 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -13,7 +13,7 @@ npm run lint # ESLint
13
13
14
14
## Lefthook (pre-commit / pre-push)
15
15
16
-
Lefthook wires three fast checks into `pre-commit` — lint, then typecheck, then `npm run test:guards`— and the full test suite into`pre-push`.
16
+
Lefthook runs lint, the typechecks (source, tests, VS Code extension), `npm audit signatures`, the VS Code extension tests, a secrets scan and `npm run test:guards`on `pre-commit`, the commit-message checks on `commit-msg`, and the full test suite on`pre-push`. After a pull, merge or rebase, the `post-merge` and `post-rewrite` hooks run `scripts/post-merge.mjs`, which reinstalls dependencies when `package-lock.json` changed, rebuilds `dist/token-goat.mjs`, stops the resident hook servers, restarts the worker, refreshes the harness shims and instructions, and triggers a reindex, so a running agent never keeps using a bundle the checkout has replaced.
17
17
18
18
`lefthook` is a devDependency and `npm install` runs `prepare` → `lefthook install`, so a fresh clone gets the hooks automatically. If `.git/hooks/pre-commit` is missing, run `npx lefthook install` — the guards below only protect you if the hook actually exists.
19
19
@@ -56,6 +56,10 @@ The same trick applies to any tool that takes URL-style paths on the command lin
56
56
4. The release event triggers `.github/workflows/publish.yml` which runs `npm publish`.
57
57
5. Verify at `https://www.npmjs.com/package/token-goat`.
58
58
59
+
## Adoption numbers
60
+
61
+
`npm run adoption` prints npm downloads, GitHub stars and GitHub forks for each week since the repository was created, newest week first. It rebuilds the table from the public npm and GitHub APIs on every run and stores nothing. GitHub does not list stargazers without a token, so set `GH_TOKEN` (`GH_TOKEN=$(gh auth token) npm run adoption` works locally). `--json` prints the rows as data and `--since YYYY-MM-DD` starts later. The scheduled `adoption.yml` workflow puts the same table in its job summary every Monday. The script lives in the repository and does not ship in the npm package.
62
+
59
63
## Session mining for improvements
60
64
61
65
If you notice missed token savings, hook friction, or command errors during an AI coding session (Copilot CLI, Claude Code, Cursor, etc.), run the [Session Mining Prompt](docs/PROMPT_SESSION_MINING.md) on your session history to generate an actionable Maintainer Feedback Card before submitting a bug report or pull request.
Copy file name to clipboardExpand all lines: README.md
+3-2Lines changed: 3 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -113,6 +113,7 @@ The fastest way to reduce AI token costs is fixing these six, not writing shorte
113
113
| Large markdown file read in full (README.md, CHANGELOG.md, CLAUDE.md ≥8 KB) | Heading tree intercepted instead — H1–H3 with `#2`/`#3` disambiguation; `token-goat section` shortcuts listed for well-known files; post-edit injects a re-read suggestion rather than the full file |
114
114
| Subagent reads a ≥30 KB markdown file whole, on its first look at it | Off by default. Set `subagent_markdown_first_read_deny = true` under `[hints]` to block that read and answer with the heading tree instead. Only fires in a subagent, only on a first, un-ranged read of a `.md`/`.mdx`/`.markdown` file with at least three headings; a read that already asks for a line range, and every main-session read, pass through untouched |
115
115
| Claude Code spawns an agent without `subagent_type` while tools-restricted agent definitions exist | Off by default. Set `agent_scoped_spawn_deny = true` under `[hints]` (or `TOKEN_GOAT_AGENT_SCOPED_SPAWN_DENY=1`) to refuse the first such spawn in a session and name the restricted agents, so the retry can pick one. An untyped spawn runs as general-purpose, whose context starts with every tool and MCP schema on the machine. Re-issuing the same call runs it: the refusal happens once per session. A spawn that names any `subagent_type`, `general-purpose` included, is never refused, and Copilot CLI and VS Code are left alone |
116
+
| Claude Code Bash command on Windows that contains two backslashes in a row | Refused before it runs, with the reason and what to do instead. Git Bash halves every run of two or more backslashes in the command it is handed, so an escaped path, a regular expression or a `printf` format string would run as different text with no error. Write the text to a file with the Write tool and run it by path, use the PowerShell tool, or use forward slashes in paths. Claude Code on Windows only; set `deny_bash_double_backslash = false` under `[hints]` (or `TOKEN_GOAT_DENY_BASH_DOUBLE_BACKSLASH=0`) to turn it off |
116
117
| A source file is read whole for the first time, with no earlier copy to compare it against | Keeps each function's declaration and its first eight lines, replacing the rest with one line naming the symbol, the exact range removed, and the command that returns it. Set `fold_code_bodies = false` under `[hints]` to turn it off. Comment blocks of twelve lines or more fold to their first two on the same terms. Imports, signatures, type declarations, classes and interfaces are never folded, and a file whose index no longer matches what is on disk keeps its bodies. Measured on this repository's own source: 229 of 256 files fold, and 43% of what a read of them delivers is removed. A read that already names an offset or a limit, and any file holding something that looks like a secret, pass through untouched |
117
118
| PDF opened via Read | Full read denied; PDF shows page count and outline (`token-goat pdf-extract` pulls the actual text, optionally paged/sliced, when the outline isn't enough) |
118
119
| Excel/PowerPoint/Word file (.xlsx/.pptx/.docx) opened via Read | Full read denied; redirects to the matching narrow-slice command family (`xlsx-sheets`/`xlsx-columns`/`xlsx-head`/`xlsx-range`/`xlsx-query`, `pptx-outline`/`pptx-slide`/`pptx-notes`/`pptx-text`, `docx-outline`/`docx-tables`/`docx-text`) instead of extracting the whole document as text |
@@ -369,7 +370,7 @@ Every command, with its flags, its output, and the comparison workflows that cha
369
370
token-goat mcp-serve
370
371
```
371
372
372
-
Runs token-goat as an MCP ([Model Context Protocol](https://modelcontextprotocol.io)) stdio server, exposing surgical-read tools (including `brief`, a one-shot symbol orientation call bundling body, callers, and containing doc section, and `index_status`, which reports whether a project's index has ever been populated, current file/symbol counts, dirty-queue depth, worker liveness, and embeddings availability — call it after an unexpectedly empty result from another tool, since an MCP-only client has no hook layer to warn it apart from a genuine "not found") plus `compress_text`, `retrieve_text`, `handoff_create`, and `handoff_resolve`. These local-only tools use bounded, redacted storage; MCP never intercepts a client's built-in file reads.
373
+
Runs token-goat as an MCP ([Model Context Protocol](https://modelcontextprotocol.io)) stdio server, exposing surgical-read tools (including `brief`, a one-shot symbol orientation call bundling body, callers, and containing doc section, and `index_status`, which reports whether a project's index has ever been populated, current file/symbol counts, dirty-queue depth, worker liveness, and embeddings availability — call it after an unexpectedly empty result from another tool, since an MCP-only client has no hook layer to warn it apart from a genuine "not found") plus `compress_text`, `retrieve_text`, `handoff_create`, and `handoff_resolve`. These local-only tools use bounded, redacted storage; MCP never intercepts a client's built-in file reads. Every tool takes an optional `projectRoot`. When a call leaves it out, the server infers the project: from an absolute path that exists, then from indexed file paths ending with the path you gave, then, for a bare name, from the project that defines that symbol. It only infers a project token-goat has indexed that sits inside the server's allowed roots; otherwise it keeps its own working directory, so with `mcp.confine_reads_to_project_root` on, a path outside it is still refused. Passing `projectRoot` always wins.
373
374
374
375
### Generic compression and handoffs
375
376
@@ -445,7 +446,7 @@ Hooks fire automatically on every tool call once installed — nothing to start
445
446
446
447
Hooks also answer faster after the first call. That call starts a small resident process, the hook server, and later hook calls go to it instead of starting Node and loading token-goat each time. In measurements on Windows that took a hook call from 110 to 135 ms down to about 70 ms in Claude Code, Codex, Copilot CLI and VS Code chat, and a read command such as `token-goat section` from 122 ms to 60 ms when its output goes to the agent rather than a terminal. You never start it yourself. It stops after 30 minutes idle, after an upgrade, when you turn it off, and when `uninstall --purge` runs. `token-goat hook-server status` shows what is running and `token-goat hook-server stop` stops it. To turn it off, set `server = false` under `[hooks]` in your global config, or `TOKEN_GOAT_HOOK_SERVER=0`. A project's `.token-goat.toml` cannot change this setting, because one server answers every project.
447
448
448
-
To move to a newer release, `token-goat upgrade` installs it from npm and then re-runs `token-goat install`, so your hooks and integration manifests point at the build that just landed. `token-goat upgrade --check` reports whether one is available without installing anything, and `--json` gives the same answer for a script. Both go quiet when `network.offline` is set, and `token-goat doctor` mentions an available update at the end of its report.
449
+
To move to a newer release, `token-goat upgrade` installs it from npm and then re-runs `token-goat install`, so your hooks and integration manifests point at the build that just landed. `token-goat upgrade --check` reports whether one is available without installing anything, and `--json` gives the same answer for a script. The check asks `npm view` first, so a registry set up in npm (Artifactory, Nexus), its auth token and its CA certificate are used; it falls back to a direct request to the registry in `npm_config_registry`, or to npmjs.org. A successful result is cached for 24 hours, though `upgrade --check` itself always asks again. When a newer version is out, `token-goat doctor` mentions it at the end of its report, `token-goat stats` lists it in its insights, and the context added at session start says so. None of this happens when `network.offline` is set, and `token-goat doctor --repair` installs the update as its last step.
0 commit comments