What is this?

If you are a developer who uses AI, you ran into the problem that the AI suddenly tries to modify unrelated files in an attempt to "improve" the mess it started to create.

Guard is a tool that allows you to change file permissions on a whim so that the AI can't. Effectively preventing the AI from changing files or their permissions without yours.

Guard provides you the ability to toggle the guard of individual files, defined collections of files and provides an interactive mode for power users who need the fastest workflow possible to set and toggle file guards.

What does it do?

Interactive Mode with Fuzzy Search

╔═ Files ════════════════════════════════╤═ Collections ════════════════╗
║ ▼ src                                  │ [G] core-modules             ║
║ │ ├─ [G] main.go                       │ [-] test-fixtures            ║
║ │ └─ [G] config.go                     │                              ║
║ ▶ docs                                 │                              ║
║   [-] README.md                        │                              ║
║   [ ] notes.txt                        │                              ║
║ ▶ vendor/           (light blue)       │                              ║
║   [g] dep.go        (light blue)       │                              ║
╠════════════════════════════════════════╧══════════════════════════════╣
║  Search: main                                                         ║
╠═══════════════════════════════════════════════════════════════════════╣
║ ↑↓:Navigate  ←→:Expand/Collapse  Space:Toggle  Tab:Switch  /:Search   ║
║ R:Refresh  Q:Quit                                                     ║
╚═══════════════════════════════════════════════════════════════════════╝

Press / to activate fuzzy search and instantly filter the file tree. Press Esc to clear and close the search box. Use Tab to cycle focus between panels and the search box.

Items that are gitignored but still visible (because they are guard-tracked) appear in light blue with a lowercase [g] indicator, so you can distinguish them from normal files at a glance.

Follow the onboarding guide below to make guard your own tool.

Why `HUMAN.md` Exists

This repository includes an explanation artifact in HUMAN.md. Its purpose is to document, in plain language, what Guard does, why it was built this way, where it is fragile, and what was learned while building it.

The point is that the proof of understanding should travel with the project itself, not live only in a demo, a chat log, or the author's head.

How does it do it?

It remembers the mode of files (owner, group and read/write/execute permissions) in a .guardfile.
It changes the files group and owner and removes write permissions to guard a file against modifications by the AI.
It sets the immutable flag so that even the owner of the file cannot change its permissions without sudo.
It restores the original file settings when you are done.

Filtering with .guardignore and .gitignore

Guard can filter files using .gitignore and .guardignore files. Both use standard gitignore syntax, including negation patterns (!). By default, both are enabled.

How rules are evaluated:

Within each directory, .gitignore is read first, then .guardignore is appended — they are treated as one combined rule set. Directories are stacked from root to leaf, and the last matching rule wins.

For a file at src/vendor/file.go, rules are evaluated in this order:

1. /.gitignore
2. /.guardignore            ← can negate rules from 1
3. /src/.gitignore          ← can negate rules from 1–2
4. /src/.guardignore        ← can negate rules from 1–3
5. /src/vendor/.gitignore   ← can negate rules from 1–4
6. /src/vendor/.guardignore ← can negate rules from 1–5

This means .guardignore can un-ignore files that .gitignore would hide. For example, if your .gitignore contains vendor/ but you still want Guard to manage files inside it, add !vendor/ to your .guardignore.

Configuration:

guard config set use_gitignore <true|false>      # default: true
guard config set use_guardignore <true|false>     # default: true

When both are disabled, no filtering is applied and all files are visible. Registered (guard-tracked) files are always shown regardless of ignore rules.

Star This Repository

If you find guard useful, please consider ⭐ starring this repository! It helps others discover the project and shows your appreciation for the work.

System Requirements

Supported Platforms

Guard is designed for Unix-like systems that support traditional file permissions and ownership like:

Linux
macOS
BSD variants (FreeBSD, OpenBSD, NetBSD)

Why Not Windows?

Guard relies on Unix-style file permissions (read/write/execute for owner/group/other) and file ownership concepts that are fundamental to Unix-like systems. Windows uses a different permission model (ACLs - Access Control Lists) that doesn't map directly to the rwx permission system that Guard manages.

If you're on Windows, consider using:

WSL (Windows Subsystem for Linux) - Run Guard inside a Linux environment
Docker - Use a Linux container to run Guard
Virtual Machine - Run a Linux VM for development work

Critical Security Requirement for AI Development

IMPORTANT: When using Guard with AI coding agents (Claude, Cursor, GitHub Copilot, etc.), the user account running the AI coding agent MUST NOT have sudo privileges or at the very least using sudo must require entering a password.

This is essential because:

Guard uses sudo to change file ownership and permissions to protect files
If your AI coding agent has automatic sudo access, it can override Guard's protection mechanisms
The security model depends on the AI running under a user account that cannot silently escalate privileges

Typical Setup:

Run your AI coding tools under a regular user account
If your user account has sudo access, make sure using sudo requires entering a password
Use sudo guard and sudo guard -i commands manually when you need to enable/disable file protection
This ensures the AI cannot bypass Guard's file protection system

Recommended Setup:

Create a dedicated user account specifically for running Guard operations
Ensure your regular user account cannot modify the dedicated user's file permissions
Open a separate terminal session as the dedicated user and use Guard from that terminal
This provides complete isolation between AI operations and Guard's security mechanisms

If you don't know how to set this up, paste the above into your AI of choice to guide you.

Installation

Prerequsisites:

You'll need a working installation of the go programming language, and the command runner just and the version control system git.

Installing Go

Download the latest stable version from https://go.dev/doc/install.
Follow your OS-specific instructions to install it.
Verify your installation by running go version inside a terminal.

Installing Just

Go to https://github.com/casey/just
Follow your OS-specific instructions to install it.
Verify your installation by running just --version inside a terminal.

Installing Git

Go to https://git-scm.com/install/
Follow your OS-specific instructions to install it.
Verify your installation by running git --version inside a terminal.

Installing Guard

Clone this repository.

git clone https://github.com/florianbuetow/guard.git
cd guard

Build the guard tool binary

just build

Install the guard binary in $GOPATH/bin

just install

Verify the guard tool installation in a new terminal window.

guard --version

Note: When the guard tool is not found in the last step, you probably need to fix your GOPATH variable and re-run just install.

Onboarding Guide

To become a master at using Guard, I highly recommend that you go through the tutorials. They are easy to follow and won't take up much of your time, I promise.

Tutorial 1: How to Protect a Single File - Learn the basics of protecting individual files with Guard
Tutorial 2: How to Protect a (Static) Collection of Files - Learn the basics of protecting collections of files with Guard
Tutorial 3: Speed up your Workflow with Interactive Mode - Tired of adding files manually? Learn how to use Guard in interactive mode to infinitely speed up your workflow while working with your AI agent(s) and guard.

Command Reference

Configuration Management

# Initialize guard with default settings
guard init <mode> <owner> <group>

# Show current configuration
guard config show

# Update multiple config values at once
guard config set [mode] [owner] [group]

# Update guard mode only
guard config set mode <mode>

# Update guard owner only
guard config set owner <owner>

# Update guard group only
guard config set group <group>

# Enable/disable .gitignore-based filtering in the TUI
guard config set use_gitignore <true|false>

# Enable/disable .guardignore-based filtering in the TUI
guard config set use_guardignore <true|false>

File Operations

# Register files (captures current permissions)
guard add file <path>...

# Remove files from management
guard remove file <path>...

# Toggle protection on/off
guard toggle file <path>...

# Enable protection on files
guard enable file <path>...

# Disable protection on files
guard disable file <path>...

# Show file status and collection membership
guard show file <path>...

Collection Operations

# Add files to a collection (auto-creates collection)
guard add file <path>... to <collection>...

# Remove files from a collection
guard remove file <path>... from <collection>...

# Show collection contents
guard show collection <name>

# List all collections
guard show collection

# Toggle protection for entire collection
guard toggle collection <name>

# Create empty collection(s)
guard add collection <name>...

# Remove collection(s) and disable guard on their files
guard remove collection <name>...

# Enable protection for all files in collection(s)
guard enable collection <name>...

# Disable protection for all files in collection(s)
guard disable collection <name>...

# Clear files from collection(s) (disable guard and remove files, keep collection)
guard clear <name>...

# Copy files from source collections to target collections
guard add collection <source>... to <target>...

# Remove files from target collections that exist in source collections
guard remove collection <source>... from <target>...

Maintenance Operations

# Disable protection on all files (preserves registrations)
guard reset

# Remove stale registry entries for deleted files
guard cleanup

# Show version information
guard version

# Reset, cleanup, and delete .guardfile
guard uninstall

Information and Help

# Show about information
guard info

# Show help for any command
guard help <command>

# Show general help (same as 'guard help')
guard

Development

Build Commands

# Check prerequisites and dependencies
just check

# Initialize development environment
just init

# Build the application
just build

# Install guard binary
just install

# Run all tests
just test

# Run basic tests (no sudo required)
just test-basic

# Run privileged tests (requires sudo)
just test-sudo

# Format code and run linter
just code-fmt
just code-lint

# Run ShellCheck over shell scripts
just code-shellcheck

# Run Semgrep static analysis
just code-semgrep

# Run cyclomatic complexity check
just code-cyclo

# Run cognitive complexity check
just code-cognit

# Generate test coverage report
just coverage

# Clean build artifacts
just clean

# Show available commands
just help

CI Dependencies

Run just check to verify your setup. The following tools are used by the CI pipeline:

Required: Go, Git, Bash

Optional (auto-installed or with fallbacks):

golangci-lint - Linting (falls back to go vet if not installed)
shellcheck - Shell script analysis
semgrep - Security analysis
gocyclo - Cyclomatic complexity analysis
gocognit - Cognitive complexity analysis
tmux - Required for TUI tests

Testing

Guard uses a comprehensive testing strategy:

Unit Tests: Test individual components with mocked dependencies
Property-Based Tests: Use gopter framework (minimum 100 iterations)
Integration Tests: Test complete workflows with real filesystem operations

Architecture Overview

CLI Interface: Cobra-based command-line interface
Guard Manager: Orchestrates operations between Registry and Filesystem components
Registry Component: State management for .guardfile (thread-safe)
Filesystem Operations: Handles file permission and ownership changes

Troubleshooting

Platform Compatibility

Windows users: Guard is not compatible with Windows due to fundamental differences in file permission systems. Use WSL, Docker, or a Linux VM instead.

Permission system differences: Guard expects Unix-style rwx permissions and user/group ownership. If you're seeing unexpected behavior, verify your system supports these concepts.

Common Issues

Permission denied errors

Some operations require elevated privileges (sudo)
Use sudo guard for operations that change file ownership

Registry corruption

Guard handles corrupted .guardfile gracefully
Use guard cleanup to clean up stale entries

Files not found

Use guard cleanup to remove registry entries for deleted files
Verify file paths are correct and accessible

Configuration issues

Verify file mode format (octal strings like "0644")
Ensure user/group names exist on the system
Check the .guardfile to verify current settings

Contributing

Guard is an AI-developed project with human oversight. We welcome contributions in the form of bug reports and feature suggestions — not code pull requests.

Why No Code PRs?

Guard is built and maintained by AI agents guided by human constraints. Rather than reviewing externally written code, we let the AI generate fixes and features from clear, reproducible descriptions. This keeps the codebase consistent and avoids the overhead of reviewing vibe-coded contributions.

Instead of a pull request, file a bug report. A well-written bug report is the most valuable contribution you can make.

Bug Reports

Found a bug? Open a bug report with steps to reproduce. The best bug reports include one or both of the following:

Option A: Shell test to reproduce

Write a minimal shell script that demonstrates the bug. Follow the pattern used in tests/:

#!/usr/bin/env bash
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "$SCRIPT_DIR/helpers-cli.sh"
setup_test_env

# Setup
guard init 0000 root wheel

# Steps to reproduce
echo "hello" > "$TEST_DIR/example.txt"
guard add file example.txt
guard enable file example.txt

# What goes wrong
OUTPUT=$(guard show file example.txt 2>&1)
assert_output_contains "$OUTPUT" "expected content" "Bug: missing expected content"

cleanup_test_env

Option B: TUI screenshot (copy & paste)

If the bug is in the interactive TUI, copy-paste the terminal output showing the issue and add a textual description of the bug:

┌─ Files ──────────────────────────┐┌─ Details ─────────────────────────┐
│ ▸ example.txt          [guarded] ││ Path: ./example.txt               │
│   other.txt          [unguarded] ││ Mode: 0644                        │
│                                  ││ Status: guarded                   │
│                                  ││                                   │
│                                  ││ BUG: Details pane shows stale     │
│                                  ││ info after toggling guard status  │
└──────────────────────────────────┘└───────────────────────────────────┘

What to include

Environment: OS, Go version (go version)
Steps to reproduce: Exact commands or keystrokes
Expected behavior: What should happen
Actual behavior: What happens instead

Feedback & Feature Requests

Have suggestions or ideas? Open an issue describing what you'd like to see and why.

License

This project is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. See the LICENSE file for details.

You are free to:

Share — copy and redistribute the material in any medium or format
Adapt — remix, transform, and build upon the material

Under the following terms:

Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made
NonCommercial — You may not use the material for commercial purposes
ShareAlike — If you remix, transform, or build upon the material, you must distribute your contributions under the same license

For more information, visit: https://creativecommons.org/licenses/by-nc-sa/4.0/

Name		Name	Last commit message	Last commit date
.agents		.agents
.kiro		.kiro
cmd/guard		cmd/guard
docs		docs
internal		internal
tests		tests
.gitignore		.gitignore
.guardignore		.guardignore
.semgrep.yml		.semgrep.yml
.shellcheckrc		.shellcheckrc
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
DEVLOG.md		DEVLOG.md
HUMAN.md		HUMAN.md
LICENSE		LICENSE
README.md		README.md
go.mod		go.mod
go.sum		go.sum
interview-notes.md		interview-notes.md
justfile		justfile
mise.toml		mise.toml
to-do.md		to-do.md

Latest commit

History

Folders and files

Repository files navigation