bash-guard.en — Claude Code rule: what it does, how to install
The bash-guard.en rule for Claude Code restricts dangerous terminal commands and enforces background task timeouts.
Apache-2.0 ★ 262 updated 2026-11-17
.claude/rules/bash-guard.en.mdWhat bash-guard.en does
The rule governs bash command execution for coding agents. It blocks pkill -f, polling loops, and long foreground sleeps, requiring explicit timeouts and tags like # long-running-ok for persistent services.
For Claude Code subagents, foreground tasks exceeding 290 seconds automatically shift to the background. Network downloads route through a proxy when HOOK_PROXY is active, while direct fetches require the # direct-ok flag.
Before merging pull requests, the agent checks recorded verification entries and prevents sending test messages to restricted team channels.
What it helps with
- prevent shell termination caused by
pkill -f - enforce strict timeouts on background shell commands
- block infinite polling loops and
sleepcommands - route network downloads through a proxy environment
Example prompts for the agent
- Run a long build command with a proper timeout and flag
- Check my bash command list against execution restrictions
- Ensure tests run in the background without polling loops
How to install bash-guard.en
Manually: put the files in place
.claude/rules/bash-guard.en.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/bash-guard.en.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/bash-guard.en.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/bash-guard.en.mdManually: put the files in place
.clinerules/bash-guard.en.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about bash-guard.en
How to install bash-guard.en in Claude Code?
Place the rule file into .claude/rules/bash-guard.en.md.
What does bash-guard.en do?
It restricts unsafe terminal commands, manages task timeouts, and stops agent polling loops in the shell.
What is required to use bash-guard.en?
A supported AI coding assistant environment such as Claude Code, Cursor, or Windsurf.
Source text
bash-guard.en.md · Apache-2.0
- Commands (bash-guard): no `pkill -f` (it kills the shell running it); use `kill $(pgrep -f '[x]yz')` or a pid file. Background commands need a timeout (`timeout <s> <cmd>`; on macOS `perl -e 'alarm shift; exec @ARGV' <s> <cmd>`) and no `| tail`/`| head`; end a long-running service with `# long-running-ok`. With HOOK_PROXY set, downloads go through the proxy; add `# direct-ok` when a direct download is really needed. - Reject foreground gh watch, sleep >=60 seconds and sleep polling loops. DSH also rejects any foreground sleep, repeated polls/read-only commands and a fourth sequential single read-only step. Batched reads, child sessions and outing turns have scoped exemptions. DSH network installs/fetches require a timed background task. Missing session history never fabricates counts. - A Claude Code subagent's foreground command with a timeout over 290 seconds gets it cut to 290 seconds (a subagent's prompt cache lasts 5 minutes); what does not finish moves to the background by itself. Do not poll it then: deliver with the log path and the next step. Dispatch work that waits 5–60 minutes to a long-task subagent (1-hour cache, not capped). A while … sleep loop inside perl/python counts as polling too. - In the main session a foreground remote, install/download, CI or build/test command with a timeout over 5 minutes is capped to 290 seconds and moves to the background if it runs longer; start such commands in the background. A test command piped into `tail/head` gets `set -o pipefail` added: judge by the exit code. - `for … sleep … break` polling and `caffeinate -w` also count as waiting in the foreground. Before a PR merge, merge-gate checks the recorded real-entry verification; no test messages go to the team chat channels on the list. - Other CLIs do not inherit the Claude long-task cache policy. Start work expected to exceed five minutes in the native background, report its log/task ID, and end the turn: DSH run_in_background (timeoutMs can promote to background), Grok block_until_ms=0, Gemini is_background, or the session ID returned by Codex exec_command. Do not poll with wait/sleep. DSH child timeouts above 290000 ms are denied with capped retry arguments; Grok child block_until_ms is capped at 290000.
© zuiho-kai · Apache-2.0 · zuiho-kai/bothouse