Skip to content

Commit 093fe07

Browse files
committed
merge: improve-readme-publishing — changelog, OIDC publish, v0.3.1 bump
2 parents 7de6d9e + ef9ebd6 commit 093fe07

4 files changed

Lines changed: 159 additions & 31 deletions

File tree

‎.github/workflows/publish.yml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
name: Publish to PyPI
2+
3+
# Publishes the package to PyPI on every GitHub Release using OIDC-based
4+
# Trusted Publishing — no long-lived API tokens are stored as repo secrets.
5+
#
6+
# PyPI side: configure a Trusted Publisher at
7+
# https://pypi.org/manage/project/token-goat/settings/publishing/ with
8+
# Owner: DFKHelper
9+
# Repository: token-goat
10+
# Workflow: publish.yml
11+
# Environment: pypi
12+
# The first publish must be done manually (or via PyPI's "Pending publisher"
13+
# flow) so the project exists; subsequent releases flow through here.
14+
15+
on:
16+
release:
17+
types: [published]
18+
workflow_dispatch:
19+
20+
jobs:
21+
build:
22+
name: Build sdist + wheel
23+
runs-on: ubuntu-latest
24+
steps:
25+
- uses: actions/checkout@v4
26+
- uses: astral-sh/setup-uv@v3
27+
- run: uv python install 3.13
28+
- name: Build
29+
run: uv build
30+
- name: Upload artifacts
31+
uses: actions/upload-artifact@v4
32+
with:
33+
name: dist
34+
path: dist/
35+
36+
publish:
37+
name: Publish to PyPI (OIDC)
38+
needs: build
39+
runs-on: ubuntu-latest
40+
environment:
41+
name: pypi
42+
url: https://pypi.org/p/token-goat
43+
permissions:
44+
id-token: write
45+
contents: read
46+
steps:
47+
- name: Download artifacts
48+
uses: actions/download-artifact@v4
49+
with:
50+
name: dist
51+
path: dist/
52+
- name: Publish
53+
uses: pypa/gh-action-pypi-publish@release/v1

‎CHANGELOG.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,42 @@ All notable changes to Token-Goat are documented in this file. Format follows Ke
44

55
## [Unreleased]
66

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.
42+
743
## [0.2.3] - 2026-05-14
844

945
### Changed

‎README.md‎

Lines changed: 69 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,17 @@
66
Cuts the tokens Claude Code and Codex CLI burn. Windows, Linux, WSL, and macOS. Install once, then forget it.
77
</p>
88

9+
<p align="center">
10+
<a href="https://pypi.org/project/token-goat/"><img src="https://img.shields.io/pypi/v/token-goat?label=PyPI&logo=pypi&logoColor=white" alt="PyPI version"></a>
11+
<a href="https://github.com/DFKHelper/token-goat/actions/workflows/ci.yml"><img src="https://github.com/DFKHelper/token-goat/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
12+
<a href="https://pypi.org/project/token-goat/"><img src="https://img.shields.io/pypi/pyversions/token-goat?logo=python&logoColor=white" alt="Python 3.11 | 3.12 | 3.13"></a>
13+
<a href="LICENSE"><img src="https://img.shields.io/badge/license-PolyForm%20Noncommercial-lightgrey" alt="PolyForm Noncommercial"></a>
14+
</p>
15+
916
<p align="center">
1017
<img src="https://img.shields.io/badge/Windows-10%20%7C%2011-0078d4?logo=windows&logoColor=white" alt="Windows 10 | 11">
1118
<img src="https://img.shields.io/badge/Linux-including%20WSL-FCC624?logo=linux&logoColor=black" alt="Linux including WSL">
1219
<img src="https://img.shields.io/badge/macOS-untested-lightgrey?logo=apple&logoColor=white" alt="macOS (untested)">
13-
<img src="https://img.shields.io/badge/Python-3.11%20%7C%203.12%20%7C%203.13-3776ab?logo=python&logoColor=white" alt="Python 3.11 | 3.12 | 3.13">
14-
<img src="https://img.shields.io/badge/license-PolyForm%20Noncommercial-lightgrey" alt="PolyForm Noncommercial">
1520
<img src="https://img.shields.io/badge/requires-uv-6340ac" alt="requires uv">
1621
</p>
1722

@@ -84,32 +89,56 @@ The `--codex` flag patches both Claude Code and Codex CLI in one pass.
8489

8590
First `token-goat semantic` call downloads a small embedding model, about 130 MB, into the token-goat data directory. One-time. Offline after that.
8691

87-
## Zero maintenance
92+
## What gets installed?
8893

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.
9095

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/`)
9797

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. |
99103

100-
## Windows Defender (Windows only)
104+
**Worker autostart** (one of the following, picked by platform)
101105

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`. |
103112

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.
105114

106-
```powershell
107-
Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\dfk-helper\token-goat"
108-
```
115+
**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`. |
109121

110-
If you see `0x800106ba`, the prompt is not elevated. Reopen as administrator.
122+
**Data directory** (created on first run)
111123

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\` |
127+
| Linux / WSL | `~/.local/share/token-goat/` |
128+
| macOS | `~/Library/Application Support/dfk-helper/token-goat/` |
129+
130+
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.
131+
132+
**With `--codex`** (Codex CLI integration)
133+
134+
| Path | What |
135+
|------|------|
136+
| `~/.codex/config.toml` | Hooks block with Codex-specific matchers (`view_image|Bash`, `apply_patch`, `web_search`). Existing hooks preserved. |
137+
| `~/.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.
113142

114143
## Verify
115144

@@ -120,23 +149,33 @@ token-goat stats
120149

121150
`doctor` confirms the install is healthy. `stats` shows cumulative savings.
122151

123-
## Uninstall
152+
## Security, privacy, and uninstall
124153

125-
```
126-
token-goat uninstall
127-
```
128-
129-
## Privacy
154+
**No telemetry. No analytics. No background reporting or silent outbound connections.**
130155

131-
No telemetry. No analytics. No background reporting or silent outbound connections.
156+
Outbound network is reserved to three explicit cases:
132157

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.
136159
- Google Drive API calls, only if you already authorized Drive in Claude Code. Token-goat never prompts for its own auth.
137160
- Explicit, user-triggered URL fetches via `token-goat fetch-image <url>`.
138161

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:
165+
166+
```powershell
167+
Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\dfk-helper\token-goat"
168+
```
169+
170+
`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.
140179

141180
## About
142181

‎pyproject.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[project]
22
name = "token-goat"
3-
version = "0.3.0"
3+
version = "0.3.1"
44
description = "Hook-based token optimizer for Claude Code on Windows, macOS, Linux, and WSL. Image shrink, re-read dedup, and compaction assist — automatic."
55
readme = "README.md"
66
requires-python = ">=3.11,<3.15"

0 commit comments

Comments
 (0)