Security & trustRead this
Read this
first.
Project Pals runs agents on your machine and changes a few files outside Herdr's folder. Here is all of it, plainly, including what it doesn't protect you from.
Every file it touches.
| Where | What | Skip it with |
|---|---|---|
~/.config/herdr-app/layouts/pals.json, mods/crew-* | The pals layout and its mods. A shortcut is added to Herdr's keys.json only if it's free (backed up first). | always installed |
~/.local/bin/pal and friends | The commands. buddy, botz and crew are linked as aliases only if the name is free or already ours. | always installed |
~/.local/lib/herdr-crew/ | The shared Python the commands use. | always installed |
~/.config/systemd/user/herdr-crew.service | crewd, the background helper: delivers messages between turns, runs routines, the nightly memory review and dream loop, and checks for updates. | --no-helpers |
~/.claude/settings.json | Claude Code hooks (message delivery, the approval gate) and a status-line wrapper. Backed up first. | --no-helpers |
~/.claude/skills, ~/.codex/skills | Links to the crew's shared skills. | --no-helpers |
Backups go to ~/.config/herdr-app/.crew-backups/ · your pals, rooms, memory, routines and tasks (~/.config/herdr-app/data/) are never touched by an install or an update
Checked, then
reversible.
- Source
- Only this project's GitHub releases
- Check
- The tarball must match the release's SHA256SUMS, or it's refused
- Scope
- Replaces only Project Pals' own files
- Undo
- The previous version is kept for Roll back; a failed install puts it back by itself
- Asks
- A quiet pill in the status bar; nothing installs until you click Update now
What it holds.
- Commands
- git push, merges (
pal land), releases (including release scripts), deploys and publishing - Files
- A pal's edits to a project's AGENTS.md or CLAUDE.md
- Approval
- Your click in the Inbox, good for one run of that exact command
- Expiry
- 30 minutes unused, then it asks again
- Record
- Every approve and decline attempt is logged, with where it came from
What it doesn't.
- It isn't a sandbox. It sees the commands a pal types. A script that pushes inside itself, or a pal with permissions bypassed, can get around it.
- Claude Code only. Codex, Grok, Gemini, opencode and Hermes pals aren't gated. Antigravity CLI support, gate included, is coming in 0.3.1.
- It doesn't review code. Use branches, worktree channels and
pal diffbefore you approve a push.
Only you
speak as you.
Some things only you can do, and Project Pals checks that it's really you: a click in its own windows, not a message that claims to be from you.
- Approvals
- Only your click in the Inbox approves. A message from another pal, even the head pal, is never approval.
- Prompts
- Pals never answer an agent's own questions for you, including Claude Code's "trust this folder?"
- Missions
- A pal can propose its mission; only you accept it.
- Agent files
- Changes to AGENTS.md or CLAUDE.md are proposals until you've seen the diff and clicked.
- Messages Coming in 0.3.1
- A message headed "[from you]" needs your click; text inside a message can't fake a header.
What leaves
your machine.
- Your agents
- Talk to their own providers, as they always do
- Memory reviews
- Send channel screens to Claude (Haiku) to distil what's worth remembering; the nightly distillation uses Sonnet
- The dream loop
- One small model call groups the notebooks' hiccups into patterns
- Update checks
- GitHub, at most every 6 hours
- Notebooks
- Refuse private keys and mask key- and token-shaped text
Found a security problem? Please tell the maintainer privately through GitHub rather than opening a public issue.