docs: PAI has no formal tool prerequisite list — rg, fd, rtk are silent requirements

[DonovanJonesUK]

Summary

PAI assumes several CLI tools are present but never states them as installation requirements. A fresh setup on any machine will hit silent degradation without them — with no signal that anything is wrong.

Current State in CLAUDE.md

"In Bash: rg over grep, fd over find"

This reads as a style preference, not a requirement. rtk isn't mentioned at all as a prerequisite — only implied by the existence of ContextReduction.hook.sh. There is no "before you start" or "required tools" section anywhere in PAI.

Tools PAI Silently Requires

Tool	Used by	Linux install	macOS install
rg (ripgrep)	CLAUDE.md preference, search-intensive skills, hooks	apt install ripgrep	brew install ripgrep
fd	CLAUDE.md preference, skills	apt install fd-find + symlink (see note)	brew install fd
rtk	ContextReduction.hook.sh — provides 60–90% token reduction on Bash calls	curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh	same
jq	Multiple tools, statusline, healthcheck scripts	apt install jq	brew install jq
bun	All PAI TypeScript tooling	curl -fsSL https://bun.sh/install | bash	same

Debian/Ubuntu note on fd: the package is named fd-find and the binary is fdfind. A symlink is required for PAI to find it: sudo ln -sf /usr/bin/fdfind /usr/local/bin/fd. This is a common silent failure point.

rtk note: not available in any package manager; must be curl-installed. Lands in ~/.local/bin/ — which must be on the hook PATH (see related issue #1368).

Failure Mode

All three tools (rg, fd, rtk) degrade silently when absent:

• rg/fd — skills and hooks that invoke them emit command not found only in contexts where stderr is visible; many contexts suppress it
• rtk — ContextReduction.hook.sh has an explicit guard that exits 0 when rtk is absent, meaning 60–90% token reduction is simply never applied, with no notification

Discovery

Found during a full PAI tool audit on a Hetzner VPS (Ubuntu 24.04) — an installation that had been running PAI for several weeks. All three tools were absent and had been silently degrading hooks since initial setup.

Proposed Fix

Add a ## Required Tools section to CLAUDE.md (or a new SETUP.md) listing these tools with install commands for both Linux (apt) and macOS (brew). Specifically:

• Mark rtk explicitly as required for the ContextReduction hook, with its curl install command
• Note the fd-find/fdfind Debian/Ubuntu naming difference and the required symlink
• Cross-reference the settings.json env.PATH requirement (issue docs: hooks run in stripped environment — settings.json env.PATH is a required but undocumented field #1368) since these tools must also be on the hook PATH to function

[danielmiessler]

Hey @DonovanJonesUK, thanks for raising this, and sorry it sat for a while.

We're changing how LifeOS ships. Instead of cloning a full ~/.claude directory and running it as a complete system, LifeOS is becoming a skill you install through an agentic installer. The installer hands integration to your own AI, which reads your actual machine (your OS, your paths, your harness) and wires the hooks and system prompt in where they belong.

That's aimed right at what you hit here. The old "one directory, one layout, hope it matches your setup" approach is exactly what broke for so many people, and the new model should handle it far better because your AI does the integration per machine instead of us guessing.

So we're closing this in prep for that release. If it still bites you once the skill-based version is out, reopen or file a fresh one and we'll jump on it. Appreciate you taking the time.