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 093fe07
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: CHANGELOG.md
+36Lines changed: 36 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,6 +4,42 @@ All notable changes to Token-Goat are documented in this file. Format follows Ke
4
4
5
5
## [Unreleased]
6
6
7
+
## [0.3.1] - 2026-05-16
8
+
9
+
### Added
10
+
11
+
-**Linux and WSL support.** The worker now registers as a `systemd --user` service (`~/.config/systemd/user/token-goat-worker.service`) when systemd is available, with an XDG autostart `.desktop` fallback elsewhere. On WSL without systemd, the SessionStart hook starts the worker at the beginning of every Claude Code session. Data directory: `~/.local/share/token-goat/`. The install/uninstall flow, doctor checks, weekly auto-update (via `crontab`), and hook entry-point are platform-aware end-to-end.
12
+
-**macOS support** (untested). The worker registers as a LaunchAgent at `~/Library/LaunchAgents/com.dfkhelper.token-goat-worker.plist`, loaded via `launchctl`. Data directory: `~/Library/Application Support/dfk-helper/token-goat/`. Weekly auto-update uses the same crontab path as Linux.
13
+
-**PyPI Trusted Publishing.** A `Publish to PyPI` GitHub Actions workflow builds and publishes on GitHub Release via OIDC, replacing long-lived API tokens stored as repo secrets. PyPI's docs explicitly call out the security and usability advantages of OIDC-based publishing.
14
+
-**README `What gets installed?` and `Security, privacy, and uninstall` sections** enumerating every file, hook, autostart entry, scheduled task, and data path the installer writes — and how each is reversed.
15
+
- README badges for PyPI version and CI status (in addition to the existing Python version and license badges).
16
+
- Lefthook git hooks for local lint / type-check / test parity with CI.
17
+
- PyPI project URLs, classifiers, and keywords surfaced in `pyproject.toml`.
18
+
19
+
### Changed
20
+
21
+
- Data directory namespace renamed from `DFK Helper LLC` to `dfk-helper` for cross-platform path hygiene (matches the platformdirs convention on every OS). A reinstall will recreate the index at the new path; the old directory can be removed by hand.
22
+
- Author / namespace migrated to `DFK Helper LLC` across the project (replaces a personal username in metadata and packaging fields).
23
+
- CI slimmed to Python 3.13 on Windows for `ruff`, `mypy`, and `pytest`. The package itself still declares support for 3.11–3.13.
24
+
- README rewritten with a before/after comparison table and stat callouts.
25
+
26
+
### Fixed
27
+
28
+
- Python 3.13 changed how `stat()` reports paths that contain a null byte; existing tests and a defensive check in `paths.py` were updated to accommodate the new error type.
29
+
- Three Windows-runner CI test failures resolved.
30
+
- Ruff caught a handful of orphaned imports left over from the iteration sweeps — all removed.
31
+
-`token-goat stats` no longer charges suggestion-only hints with an overhead "saving" they did not earn.
32
+
-`token-goat stats` bar-scale and share-% now use separate denominators so a single dominant kind no longer flattens the rest of the chart.
33
+
34
+
### Security
35
+
36
+
- Continued hardening of input validation in `paths.py` (`is_safe_rel_path`, hash-traversal guards in `project_db_path` and `session_cache_path`) so no rel-path can escape the data directory under any caller.
37
+
38
+
### Removed
39
+
40
+
- Legacy `tokenwise` launcher binaries (`tokenwise`, `tokenwise-hook`, `tokenwise-worker`) are now removed during install and uninstall when they sit alongside the current `token-goat` launchers.
41
+
- Provisional application number stripped from the patent notice.
@@ -84,32 +89,56 @@ The `--codex` flag patches both Claude Code and Codex CLI in one pass.
84
89
85
90
First `token-goat semantic` call downloads a small embedding model, about 130 MB, into the token-goat data directory. One-time. Offline after that.
86
91
87
-
## Zero maintenance
92
+
## What gets installed?
88
93
89
-
After `token-goat install`, there is nothing to start, stop, or restart. The worker:
94
+
`token-goat install` writes the following on your machine — nothing else, anywhere. Every entry is reversed by `token-goat uninstall`. Run `token-goat doctor` at any time to see which of these are currently present.
90
95
91
-
-**Windows:** starts at logon via the Windows startup registry (HKCU Run key, no admin rights needed), runs without a console window
92
-
-**Linux with systemd:** registers as a systemd user service (`~/.config/systemd/user/token-goat-worker.service`), starts at login automatically
93
-
-**WSL without systemd:** the SessionStart hook starts the worker at the beginning of every Claude Code session
94
-
-**macOS (untested):** the SessionStart hook starts the worker at the start of every Claude Code session
95
-
- survives reboots on all platforms
96
-
- needs zero ongoing attention
96
+
**Claude Code integration** (`~/.claude/`)
97
97
98
-
To remove it later, `token-goat uninstall` reverses every change, including the startup entry.
98
+
| Path | What |
99
+
|------|------|
100
+
|`~/.claude/settings.json`| Hook entries for `SessionStart`, `PreToolUse` (Read, Drive/WebFetch), `PostToolUse` (Edit/Write/MultiEdit, Read/Grep/Glob), and `PreCompact`. Plus a `Bash(token-goat:*)` permission allowlist entry. Existing hooks are preserved; a timestamped `.bak` is written before any change. |
101
+
|`~/.claude/CLAUDE.md`| A delimited block (`<!-- token-goat-begin -->` … `<!-- token-goat-end -->`) telling the agent to prefer `token-goat read` / `symbol` / `section` over `Read` / `Grep`. Any existing content is preserved. |
102
+
|`~/.claude/skills/token-goat/SKILL.md`| The token-goat skill — the same routing guidance in skill form. |
99
103
100
-
## Windows Defender (Windows only)
104
+
**Worker autostart** (one of the following, picked by platform)
101
105
102
-
Optional speed-up for large repos. Token-goat works fine without it.
106
+
| Platform | Entry |
107
+
|---------|------|
108
+
| Windows |`HKCU\Software\Microsoft\Windows\CurrentVersion\Run\token-goat-worker`. No admin rights required. |
109
+
| Linux (with `systemd --user`) |`~/.config/systemd/user/token-goat-worker.service`, enabled. |
110
+
| Linux (no systemd, incl. WSL) |`~/.config/autostart/token-goat-worker.desktop`. On WSL without systemd, the SessionStart hook also starts the worker on every Claude Code session. |
111
+
| macOS (untested) |`~/Library/LaunchAgents/com.dfkhelper.token-goat-worker.plist`, loaded via `launchctl`. |
103
112
104
-
Real-time scanning slows indexing. To exclude the token-goat folder, open PowerShell as administrator and run:
113
+
The autostart command is `pythonw -m token_goat.cli worker --daemon` from Token-Goat's `uv tool` venv. No PyInstaller-style launcher `.exe` is dropped; AV/EDR products do not behavior-flag this invocation pattern.
**Weekly auto-update** (Sunday 03:00 local time, runs `uv tool upgrade token-goat`)
116
+
117
+
| Platform | Entry |
118
+
|---------|------|
119
+
| Windows | Scheduled task `token-goat-update` (`schtasks`). |
120
+
| Linux / macOS | A `crontab` line tagged with `# token-goat-autoupdate`. |
109
121
110
-
If you see `0x800106ba`, the prompt is not elevated. Reopen as administrator.
122
+
**Data directory** (created on first run)
111
123
112
-
On enterprise-managed Windows (domain-joined or Intune-managed), Defender exclusions may be locked by Group Policy. The command will fail even with admin rights. That is expected and harmless.
124
+
| Platform | Path |
125
+
|---------|------|
126
+
| Windows |`%LOCALAPPDATA%\dfk-helper\token-goat\`|
Contains the symbol index (`global.db`, per-project `.db` files), session cache, shrunken-image cache, embedding model (~130 MB, downloaded on the first `semantic` call), logs, locks, and the dirty-file queue. Nothing outside this directory and `~/.claude/` is written.
|`~/.codex/AGENTS.md`| A delimited block (`<!-- token-goat-codex-begin -->` … `<!-- token-goat-codex-end -->`) with the same routing guidance, adapted for Codex tool names. |
138
+
139
+
## Zero maintenance
140
+
141
+
After install, there is nothing to start, stop, or restart. The worker runs at logon on Windows, Linux, and macOS; on WSL without systemd, the SessionStart hook covers it. Survives reboots on every platform. `token-goat uninstall` reverses every change, including the startup entry.
113
142
114
143
## Verify
115
144
@@ -120,23 +149,33 @@ token-goat stats
120
149
121
150
`doctor` confirms the install is healthy. `stats` shows cumulative savings.
122
151
123
-
## Uninstall
152
+
## Security, privacy, and uninstall
124
153
125
-
```
126
-
token-goat uninstall
127
-
```
128
-
129
-
## Privacy
154
+
**No telemetry. No analytics. No background reporting or silent outbound connections.**
130
155
131
-
No telemetry. No analytics. No background reporting or silent outbound connections.
156
+
Outbound network is reserved to three explicit cases:
132
157
133
-
Outbound network only in three explicitly disclosed cases:
134
-
135
-
- First `token-goat semantic` call downloads the embedding model. After that, semantic search runs offline.
158
+
- First `token-goat semantic` call downloads the embedding model (~130 MB) into the data directory. Offline after that.
136
159
- Google Drive API calls, only if you already authorized Drive in Claude Code. Token-goat never prompts for its own auth.
137
160
- Explicit, user-triggered URL fetches via `token-goat fetch-image <url>`.
138
161
139
-
All caches and the index live in the token-goat data directory: `%LOCALAPPDATA%\dfk-helper\token-goat\` on Windows, `~/.local/share/token-goat/` on Linux and WSL, `~/Library/Application Support/dfk-helper/token-goat/` on macOS. Delete the folder any time. Nothing else on the system depends on it.
162
+
**Security reports.** See [SECURITY.md](SECURITY.md). Email `token-goat@dfkhelper.com`; do not file as a GitHub issue. Reports are acknowledged within 7 days; coordinated disclosure with a 90-day default window.
163
+
164
+
**Windows Defender (optional, Windows only).** Real-time scanning slows indexing. To exclude the data folder, open PowerShell as administrator:
`0x800106ba` means the prompt is not elevated; reopen as administrator. On enterprise-managed Windows (domain-joined / Intune), Defender exclusions may be locked by Group Policy. The command will fail; that is expected and harmless.
171
+
172
+
**Uninstall.**
173
+
174
+
```
175
+
token-goat uninstall
176
+
```
177
+
178
+
Reverses everything in [What gets installed?](#what-gets-installed): the scheduled task or systemd unit, the registry value or `.desktop` or `.plist`, the hook entries in `settings.json`, the `CLAUDE.md` block, the skill directory. Add `--codex` to also strip the Codex integration. Add `--purge` to also delete the data directory (cache, index, models, logs). Nothing else on the system depends on it.
Copy file name to clipboardExpand all lines: pyproject.toml
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
[project]
2
2
name = "token-goat"
3
-
version = "0.3.0"
3
+
version = "0.3.1"
4
4
description = "Hook-based token optimizer for Claude Code on Windows, macOS, Linux, and WSL. Image shrink, re-read dedup, and compaction assist — automatic."
0 commit comments