From afb739f061d6e73a08ce5db6a769db3251450f6f Mon Sep 17 00:00:00 2001
From: rootiest <chris@rootiest.com>
Date: Fri, 19 Jun 2026 23:18:32 -0400
Subject: [PATCH] docs: add systemd user service and persistent env setup

Add templates/claude-tokenization-proxy.service (systemd user unit that runs
the proxy at login, restarts on failure) and README sections covering its
installation, lingering for boot-before-login, and permanently setting
ANTHROPIC_BASE_URL across fish, bash/zsh, and environment.d.
---
 README.md                                   | 59 +++++++++++++++++++++
 templates/claude-tokenization-proxy.service | 22 ++++++++
 2 files changed, 81 insertions(+)
 create mode 100644 templates/claude-tokenization-proxy.service

diff --git a/README.md b/README.md
index 697962b..facacda 100644
--- a/README.md
+++ b/README.md
@@ -84,6 +84,65 @@ Treat them as opaque identifiers and preserve them exactly as they appear when
 writing or reading files.
 ```
 
+## Run at boot/login (systemd user service)
+
+[`templates/claude-tokenization-proxy.service`](templates/claude-tokenization-proxy.service)
+is a ready-to-use systemd **user** unit that runs the proxy in the background and
+restarts it on failure.
+
+```bash
+# 1. Install the unit
+mkdir -p ~/.config/systemd/user
+cp templates/claude-tokenization-proxy.service ~/.config/systemd/user/
+
+# 2. Edit WorkingDirectory= to point at your clone (and the node path if you
+#    use a version manager like nvm/fnm/asdf — see the comments in the unit)
+$EDITOR ~/.config/systemd/user/claude-tokenization-proxy.service
+
+# 3. Enable + start it
+systemctl --user daemon-reload
+systemctl --user enable --now claude-tokenization-proxy.service
+
+# Check status / logs
+systemctl --user status claude-tokenization-proxy.service
+journalctl --user -u claude-tokenization-proxy.service -f
+```
+
+A user service starts when **you** log in. To keep it running at boot before
+any login (and after you log out), enable lingering for your account:
+
+```bash
+sudo loginctl enable-linger "$USER"
+```
+
+## Permanently point claude-code at the proxy
+
+Setting `ANTHROPIC_BASE_URL` per shell (as in [Setup](#setup)) only lasts for
+that session. To make it stick:
+
+- **fish** — set a universal variable once; it persists across sessions:
+
+  ```fish
+  set -Ux ANTHROPIC_BASE_URL http://localhost:8080
+  ```
+
+- **bash/zsh** — add the export to your shell rc (or `~/.profile` for all
+  shells):
+
+  ```bash
+  echo 'export ANTHROPIC_BASE_URL=http://localhost:8080' >> ~/.bashrc
+  ```
+
+- **All processes in a graphical session** (works regardless of shell) — drop
+  it in systemd's user environment:
+
+  ```bash
+  mkdir -p ~/.config/environment.d
+  echo 'ANTHROPIC_BASE_URL=http://localhost:8080' >> ~/.config/environment.d/claude.conf
+  ```
+
+  Takes effect on next login.
+
 ## Scripts
 
 | Command           | What it does                                          |
diff --git a/templates/claude-tokenization-proxy.service b/templates/claude-tokenization-proxy.service
new file mode 100644
index 0000000..2054f9e
--- /dev/null
+++ b/templates/claude-tokenization-proxy.service
@@ -0,0 +1,22 @@
+# Copyright (C) 2026 Rootiest
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+[Unit]
+Description=claude-code tokenization proxy (ggshield DLP)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+# Edit this to the absolute path where you cloned the repo.
+WorkingDirectory=%h/projects/claude-tokenization-proxy
+# Requires Node >= 23.6 on PATH. If you use nvm/fnm/asdf, replace
+# "/usr/bin/env node" with the absolute path to your node binary
+# (run `which node` to find it).
+ExecStart=/usr/bin/env node src/index.ts
+Restart=on-failure
+RestartSec=5
+# Optional overrides (see README "Configuration"):
+# Environment=PORT=8080
+
+[Install]
+WantedBy=default.target