https://github.com/kawarimidoll/guard-and-guide
🛡️ Guard coding agents from dangerous operations, and 🧭 Guide them to safer alternatives.
https://github.com/kawarimidoll/guard-and-guide
ai-agent claude-code cli gemini-cli hooks rust
Last synced: 25 days ago
JSON representation
🛡️ Guard coding agents from dangerous operations, and 🧭 Guide them to safer alternatives.
- Host: GitHub
- URL: https://github.com/kawarimidoll/guard-and-guide
- Owner: kawarimidoll
- License: mit
- Created: 2026-03-12T13:58:57.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-21T23:02:45.000Z (2 months ago)
- Last Synced: 2026-04-22T01:11:30.711Z (2 months ago)
- Topics: ai-agent, claude-code, cli, gemini-cli, hooks, rust
- Language: Rust
- Homepage:
- Size: 132 KB
- Stars: 6
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# guard-and-guide
[](https://github.com/kawarimidoll/guard-and-guide/actions/workflows/ci.yml)
[](https://github.com/kawarimidoll/guard-and-guide/releases/latest)
[](https://docs.anthropic.com/en/docs/claude-code)
[](https://github.com/google-gemini/gemini-cli)
[](https://www.rust-lang.org/)
[](https://nixos.org/)
🛡️ Guard coding agents from dangerous operations, and 🧭 Guide them to safer alternatives.
## Motivation
You tell your AI coding agent: "Don't run `git push`."
The agent gets blocked — and tries harder:
```
🧑 deny(git push)
🤖 Got it! I'll use /usr/bin/git push instead.
🧑 NOOO!!!
```
AI agents don't give up when simply denied. They try absolute paths, alternative commands, and creative workarounds to get the job done.
**guard-and-guide** solves this by not only blocking dangerous operations, but also telling the agent _why_ it was blocked and _what to do instead_. When given clear guidance, agents are much more likely to comply.
## Install
### nix
```sh
nix profile install github:kawarimidoll/guard-and-guide
```
### cargo
```sh
cargo install --git https://github.com/kawarimidoll/guard-and-guide
```
## Setup
### 1. Create rules
Create `~/.config/guard-and-guide/rules.toml` with your rules.
See [`rules.example.toml`](rules.example.toml) for a full example.
Rules use canonical tool names (`Bash`, `File`) and regex patterns:
```toml
version = 1
[[rules]]
matcher = "File"
regex = '\.env$'
message = "Access to .env files is prohibited. Ask the user to check or provide the values you need."
[[rules]]
matcher = "Bash"
regex = '\bgit\s+push\b'
message = "Use of 'git push' is prohibited. Ask the user to execute it."
```
`File` is an alias for `Read|Write|Edit`.
### 2. Register hook
#### Claude Code
Add to `~/.claude/settings.json`:
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "",
"hooks": [{ "type": "command", "command": "guard-and-guide" }]
}
]
}
}
```
#### Gemini CLI
Add to `~/.gemini/settings.json`:
```json
{
"hooks": {
"BeforeTool": [
{
"matcher": "",
"hooks": [{ "type": "command", "command": "guard-and-guide --agent gemini-cli" }]
}
]
}
}
```
> Copilot CLI support is planned.
## Usage
```
stdin (hook JSON) | guard-and-guide [OPTIONS]
```
| Option | Description |
|---|---|
| `--agent ` | `claude-code` (default), `gemini-cli` |
| `--config ` | Rules file path (default: `~/.config/guard-and-guide/rules.toml`) |
## How it works
```
Hook stdin → Parse JSON → Resolve tool name → Match rules → Deny or pass
```
1. Agent hook pipes JSON to stdin
2. Parse and extract tool name + input (format depends on `--agent`)
3. Resolve agent-specific tool name to canonical name (`Bash`, `Read`, `Write`, `Edit`)
4. Check each rule: does the canonical name match? Does the regex match the relevant field?
5. First match → output deny JSON to stdout. No match → silent exit 0.
### Tool name mapping
| Canonical | Claude Code | Gemini CLI |
|---|---|---|
| `Bash` | `Bash` | `run_shell_command` |
| `Read` | `Read` | `read_file` |
| `Write` | `Write` | `write_file` |
| `Edit` | `Edit` | `replace` |
## License
MIT