Handrail
Now for Claude Code · macOS & Linux · v0.1.2

Rules your coding agent can't switch off.

Handrail installs security and privacy policy for Claude Code where the agent itself cannot change it, and tells you plainly which rules are enforced and which are only requests.

$curl -fsSL https://handrail.bitey.ai/install.sh | sh

Then: handrail use baseline --dry-run to see exactly what would change, and handrail use baseline to apply it.

8 packs · 3 profiles Apache-2.0 No account, no telemetry Other ways to install
The problem

A rule in a prompt is a request. Handrail installs enforcement.

Most "agent rules" are lines in an instructions file. The model usually follows them — and the agent, running as you, can edit or delete the file. Nothing tells you which of your rules are real.

request

A line in an instructions file

# ~/.claude/CLAUDE.md
Never publish anything to the internet.
  • The model decides whether to follow it
  • Anything running as you can change the file
  • No way to tell if it was loaded
enforced

Policy the agent evaluates

# managed-settings.d/handrail-privacy.json  (owned by root)
{ "enableArtifact": false,
  "disableRemoteControl": true, … }
  • Claude Code applies it, whatever the model thinks
  • Top precedence: user and project settings cannot override it
  • Changing it needs your password — the agent can't
What you get

Built to be trusted with root.

Handrail writes system policy, so every change is planned, shown, checked and reversible.

Out of the agent's reach

Enforced packs live in Claude Code's root-owned managed policy directory, which user and project settings cannot override.

Honest about enforcement

Every pack says whether Claude Code fully enforces it or only partly, what it costs you, and what it cannot do.

Transactional

Changes are staged, backed up and journaled. If a run dies halfway, the next one restores the previous state exactly.

Trusts nothing it's handed

Only which packs you want goes to sudo. The privileged step recomputes the plan itself and refuses if it differs from the one you reviewed.

Detects tampering

handrail doctor compares installed files with what Handrail wrote and warns when another policy source would override yours.

Leaves no trace

handrail disable --all removes everything it installed. Files it didn't create are never touched, byte for byte.

Packs

Pick what you need. See what it costs.

enforced Claude Code applies it whatever the model does. partial Enforced for common paths; the pack's limits say what slips through.

enforcedenforced tieranti-bypass

No bypassing

Lock out 'skip all permission prompts' mode and stop a personal setting from switching off every hook. Without this, every other pack can be bypassed in one step.

Details
Protects against
  • Bypassing every prompt with --dangerously-skip-permissions
  • Disabling managed hooks with disableAllHooks in personal settings
Tradeoffs
  • bypassPermissions mode is unavailable (auto mode is not affected)
Limits
A local administrator can still edit the managed directory. Protecting against the administrator requires MDM.
handrail enable anti-bypass
partialenforced tierdestructive

Confirm destructive commands

Force-push, hard reset, recursive delete, git clean and similar irreversible commands always ask first. sudo is denied outright.

Details
Protects against
  • git push --force overwriting others' commits
  • git reset --hard / git clean discarding uncommitted work
  • Accidental rm -rf
  • Reusing a sudo credential you entered recently
Tradeoffs
  • These commands stop and ask even in auto mode
Limits
Rules match command prefixes. Wrapping rm in a script, an alias or a different spelling gets around them. This is a speed bump, not isolation.
handrail enable destructive
enforcedenforced tiersandbox

OS-level sandbox

Enforced by the operating system (macOS Seatbelt, Linux bubblewrap): Bash and every child process cannot read credential directories and can only reach allowlisted domains.

Details
Protects against
  • Any process, including Python or Node scripts, reading ~/.ssh, ~/.aws and similar
  • Sending data to arbitrary domains
Tradeoffs
  • Network commands can only reach allowlisted domains (package registries and GitHub by default); ssh to your own servers fails until you add them
  • If the sandbox cannot start, Claude Code refuses to run instead of silently falling back
  • A command that fails in the sandbox cannot be retried outside it
Limits
Commands you type yourself after the ! prefix are not sandboxed. Native Windows is not supported; use WSL2.
handrail enable sandbox
partialenforced tiersecrets

Credentials and secret files

Stop Claude's own file tools from reading or editing SSH keys, cloud credentials, .env files and private keys.

Details
Protects against
  • ~/.ssh, ~/.aws, ~/.gnupg, ~/.kube, ~/.docker, ~/.netrc, cloud CLI credentials
  • .env, *.pem and *.key files in projects
  • macOS keychain files
Tradeoffs
  • You edit .env files yourself
  • Legitimate *.key files in a project are blocked too
Limits
Covers Claude's built-in file tools and the file commands it recognizes in Bash (cat, head, sed, ...). A Python script that opens a file itself is not covered. For OS-level blocking, add 80-sandbox.
handrail enable secrets
enforcedenforced tiersupply-chain

Run only your own hooks

Run only hooks from managed policy; hooks shipped inside cloned repositories never run. Also disables automatic installation from the official plugin marketplace.

Details
Protects against
  • When you trusted a parent folder or run claude -p, hooks defined in a cloned repository's .claude/settings.json run arbitrary commands
Tradeoffs
  • Hooks in your own ~/.claude/settings.json stop running too (terminal integrations, custom notifications)
  • To keep one of your hooks, package it as a pack of your own
Limits
Does not cover MCP servers or skills shipped in a repository. Inspect an unfamiliar repository's .claude/ directory before working in it.
handrail enable supply-chain
enforcedenforced tierprivacy

Keep data on this machine

Turn off every optional upload: Remote Control, cloud agents, hosted artifacts, claude.ai connectors, telemetry, error reports, feedback and transcript uploads.

Details
Protects against
  • Sessions synced to the cloud
  • Output published to claude.ai
  • Feedback reports that attach the whole conversation and code
  • Telemetry and error reports
Tradeoffs
  • No Remote Control from your phone
  • The Artifact tool and claude.ai connectors (Gmail, Drive, ...) are unavailable
  • /feedback, /bug and /share are unavailable
Limits
Model inference itself must send the conversation to the model API. No local setting can change that. See the README section 'Limits'.
Requires
Claude Code 2.1.242 or later
handrail enable privacy
enforcedenforced tierretention

Keep local transcripts 7 days

Session transcripts are stored in plaintext under ~/.claude/projects/ for 30 days by default. Reduce that to 7 days.

Details
Protects against
  • Passwords and customer data that appeared in a conversation lingering on disk
  • Exposure if the machine is lost or someone else logs in
Tradeoffs
  • Sessions older than 7 days can no longer be resumed
Limits
Does not delete copies already taken by backups or cloud sync. Also enable full-disk encryption and exclude ~/.claude from cloud sync.
handrail enable retention
enforcedenforced tieraudit

Local audit log

Every tool call leaves one line on this machine: when, which session, which directory, what was called. Written locally, never sent anywhere.

Details
Protects against
  • Answering 'what exactly did it do?' after the fact
  • Spotting unexpected network access or deletions
Tradeoffs
  • The log can contain sensitive command-line arguments (common password patterns are masked); files are mode 600
Limits
The log is written as you, so any process running as you can edit it. It protects against mistakes, not deliberate tampering.
handrail enable audit
Profiles

Or start from a profile.

A profile is a named set of packs. handrail use <profile> makes the installed set exactly that; your own rules are kept.

baseline recommended

Barely changes daily use. Recommended for everyone.

privacyanti-bypassaudit
handrail use baseline
strict

Baseline plus credential protection, confirmation for destructive commands, shorter local retention.

privacyanti-bypasssecretsdestructiveauditretention
handrail use strict
paranoid

Adds the OS-level sandbox and runs only your own hooks. Changes daily use; read each pack's tradeoffs first.

privacyanti-bypasssecretsdestructivesupply-chainauditretentionsandbox
handrail use paranoid
How it works

Handrail writes the policy. Claude Code enforces it.

Handrail doesn't sit between you and the agent. It puts policy where Claude Code reads it first — and nothing else can override it.

$ handrail use baseline
  sudo receives only: which packs you want

/Library/Application Support/ClaudeCode/   # root-owned
├─ managed-settings.d/
│  ├─ handrail-privacy.json      # settings & permission rules
│  ├─ handrail-anti-bypass.json
│  └─ handrail-audit.json
├─ handrail/packs/privacy/hooks/
│  └─ guard.sh                   # runs before every tool call
└─ CLAUDE.md                     # Handrail's block: loaded
                                 # in every session

  1. Plan

    Handrail computes the exact files a change writes. --dry-run shows them; nothing else is touched.

  2. Elevate — the intent only

    You confirm and type your password. The privileged step rebuilds the plan from the catalog inside the binary and checks it matches.

  3. Apply transactionally

    Validate, stage, back up, journal, commit. Interrupted runs roll back to the exact previous state.

  4. Claude Code enforces

    Settings, permission rules and hooks are applied by Claude Code itself; the instructions block is guidance for the model.

See the source

In a new claude session run /status: the managed policy appears under "Setting sources". claude doctor shows the same.

See the instructions

Run /memory: the managed CLAUDE.md with Handrail's block is listed as loaded.

Watch it block

Ask for an Artifact, or start with --dangerously-skip-permissions: both are refused. With audit, every tool call is logged locally.

Check for tampering

handrail doctor flags edited or missing files, a writable binary, and MDM policy that would override Handrail.

Extend

Your rules, new packs, more agents.

Security is the first category, not the last. The catalog is plain files, validated by tests.

Add your own rules

One command puts a rule into the root-owned instructions block, loaded in every session.

handrail rule add "Reply in English"

Write a pack

A directory with metadata, instructions, and optional settings and hooks. cargo test validates it and runs its hook tests.

catalog/packs/my-pack/
├─ pack.toml
├─ rules.md
└─ claude-code/settings.json

More agents

Packs describe intent; each agent gets an adapter that maps it to the strongest mechanism that agent has — and labels it honestly when that's only a suggestion.

Roadmap →

Limits

What Handrail can't do.

A security tool that overclaims is worse than none. So, plainly:

Inference still leaves the machine

Your conversation is sent to the model API — that's how the model answers. Handrail turns off every optional upload and cloud path, not that one.

Administrators can undo it

A local admin can edit the managed directory. Protecting against the admin needs MDM.

MDM policy wins

If your organisation deploys Claude Code policy by MDM, Claude Code ignores file-based policy by default. handrail status tells you.

Install in one line. Remove in one line.

$curl -fsSL https://handrail.bitey.ai/install.sh | sh

Prefer to read it first? View the installer — it verifies the release checksum and uses sudo only for the final copy.

Read the docs   View on GitHub