Rules your coding agent can't switch off.

Built to be trusted with root.

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

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.

handrail use baseline

handrail use strict

handrail use paranoid

Your rules, your packs, shared in one command.

Security is the first category, not the last. A pack is a directory of plain files; the same checks that guard the built-in catalog run on yours.

1. Add a rule of your own

   The quickest extension: one sentence, placed in the root-owned instructions block that every session loads. Good for team conventions that don't need enforcement.

   $ handrail rule add "Reply in English"                  # id: rule-7k3m
   $ handrail rule add "Keep commit subjects under 50 characters" --id commits
   $ handrail rule list
   $ handrail rule edit commits "Commit subjects: 50 characters, imperative mood"
   $ handrail rule remove rule-7k3m

2. Write a pack

   When a rule needs teeth, make it a pack. This complete example keeps agents away from production: a permission rule that asks before deploys, a hook that blocks commands aimed at production, instructions for the model, and tests for the hook.

   my-packs/
   └─ packs/no-prod/
      ├─ pack.toml                  # what it is, what it costs, what it can't do
      ├─ rules.md                   # instructions loaded into every session
      ├─ claude-code/
      │  ├─ settings.json           # permissions and hooks, enforced by Claude Code
      │  └─ hooks/guard.sh          # exit 2 blocks the tool call
      └─ tests/guard.cases          # inputs the hook must block or allow

   packs/no-prod/pack.toml

   id = "no-prod"
   version = "1.0.0"
   category = "team"
   tier = "enforced"
   title = "Keep agents away from production"
   summary = "Commands aimed at production hosts or a production environment are blocked; deploy scripts ask first."
   protects = [
     "A migration or delete run against the production database",
     "Deploying from a laptop by accident",
   ]
   tradeoffs = [
     "Legitimate production work has to happen outside the agent",
   ]
   limits = "Matches command text. A script that reads the host from a config file gets past it."
   
   [targets.claude-code]
   enforcement = "partial"
   settings = "claude-code/settings.json"
   hooks = ["claude-code/hooks/guard.sh"]

   packs/no-prod/rules.md

   ### Production (no-prod)
   
   - Never run commands against production hosts, databases or environments.
   - When a task needs production access, write the command out for the user to run.

   packs/no-prod/claude-code/settings.json

   {
     "permissions": {
       "ask": ["Bash(./deploy*)", "Bash(kubectl --context prod*)"]
     },
     "hooks": {
       "PreToolUse": [
         {
           "matcher": "Bash",
           "hooks": [{ "type": "command", "command": "\"@PACK_DIR@/hooks/guard.sh\"" }]
         }
       ]
     }
   }

   packs/no-prod/claude-code/hooks/guard.sh

   #!/bin/sh
   # Exit 2 blocks the call; stderr tells the model why.
   input=$(cat)
   if printf '%s' "$input" | grep -Eq 'prod\.internal|--env[= ]production|RAILS_ENV=production'; then
     echo "Blocked by no-prod: this command targets production" >&2
     exit 2
   fi
   exit 0

   packs/no-prod/tests/guard.cases — tab-separated: name, expected exit code, hook input

   # name	expected exit	input
   production host	2	{"tool_name":"Bash","tool_input":{"command":"psql -h db.prod.internal"}}
   production env	2	{"tool_name":"Bash","tool_input":{"command":"rails db:migrate RAILS_ENV=production"}}
   local database	0	{"tool_name":"Bash","tool_input":{"command":"psql -h localhost"}}

   @PACK_DIR@ becomes the pack's installed hook directory. Hooks run as /bin/sh on every matching call, so keep them small: a broken managed hook blocks every session. The pack format reference lists every field.

3. Check and try it locally

   handrail check validates the format, runs every hook test and lints the scripts. --catalog puts your directory next to the built-in packs for any command, so you can review the exact files before anything is written.

   $ handrail check ./my-packs
   $ handrail show no-prod --catalog ./my-packs
   $ handrail enable no-prod --catalog ./my-packs --dry-run
   $ handrail enable no-prod --catalog ./my-packs

   Handrail installs a copy of the pack, so it keeps working if you move or delete the directory; run enable again with --catalog to install a new version. An external pack can't take the id of a built-in pack or override its settings.

4. Share it with a link

   Push the directory to any git repository. Anyone who trusts it installs your pack straight from the repository; no review, no waiting. Private repositories work with your usual git credentials, which makes this the simplest way to roll a policy out to a team.

   # you
   $ git -C my-packs init && git -C my-packs add . && git -C my-packs commit -m "no-prod"
   $ git -C my-packs push git@github.com:you/my-packs.git main
   # your teammates
   $ handrail enable no-prod --catalog github.com/you/my-packs

5. Publish it to the shared catalog

   Think others would want it? handrail publish proposes it to handrail-packs as a pull request. It runs the checks, forks the catalog into your account if needed, commits the pack on a branch and opens the pull request, all through the GitHub API. You don't need git or a manual fork.

   $ handrail publish no-prod --catalog ./my-packs --dry-run
   $ handrail publish no-prod --catalog ./my-packs

   • Access: uses the GitHub CLI if it's signed in, or a token in GITHUB_TOKEN (scope public_repo). With neither, it prints the manual steps.
   • Review: packs can run as root on other people's machines, so a maintainer reviews every pull request. Once merged, the pack ships in the next Handrail release and anyone can install it by name.
   • Updates: bump version and publish again; files you removed are removed in the pull request too.
   • Your own catalog: --repo your-org/policy-packs sends the pull request to a team repository instead.

6. Bring another agent

   Packs describe intent. Each agent gets an adapter that maps that intent to the strongest mechanism the agent offers, and labels it honestly when the result is only a suggestion. A pack adds support by adding a directory next to claude-code/ and a [targets.<agent>] section.

   See the roadmap →