agentignore

Policy-Filtered Filesystem for AI Agents.

agentignore is a FUSE filesystem that provides a filtered virtual view of a real directory tree. Files and directories matching rules in a .agentignore file are completely hidden from processes interacting with the mounted filesystem — they don't appear in ls, find, glob expansion, or direct access.

The primary use case is constraining autonomous AI/LLM agents that have shell access, so irrelevant files and directories (node_modules/, .git/, target/, .env, secrets/, etc.) genuinely appear non-existent to the agent while still allowing the agent to execute build and test tools.

All visible files behave as a transparent passthrough: reads and writes go directly to the real filesystem.

Note: This is not a security boundary. AgentIgnore is designed to reduce LLM context by hiding irrelevant files, not to prevent a determined attacker from accessing them.

Table of Contents

• Quick Start
• Prerequisites for Running
  • Linux (bare-metal)
  • Docker / Dev Container
  • WSL2
• Usage
  • init — create policy files
  • run — mount, execute, unmount
  • explain — debug visibility
• Policy Files
• Building from Source
• Development

Quick Start

Install via your favorite package manager:

# npm
npm install -g --ignore-scripts @xlansoftware/agentignore

# pnpm
pnpm add -g --ignore-scripts @xlansoftware/agentignore

# bun
bun add -g --ignore-scripts @xlansoftware/agentignore

# run it
agentignore run bash

Install via crate:

cargo install agentignore
agentignore run bash

Or build from source with Cargo:

# 1. Ensure FUSE is available (see Prerequisites below)

# 2. Build the binary
cargo build --release

# 3. Create example policy files in your project
./target/release/agentignore init

# 4. Start a shell inside the filtered view
./target/release/agentignore run bash

Prerequisites for Running

AgentIgnore needs the FUSE kernel module and libfuse3 on the host. Setup differs slightly across environments.

Linux (bare-metal)

# Ubuntu / Debian
sudo apt update
sudo apt install fuse3

# Fedora / RHEL
sudo dnf install fuse3

# Arch
sudo pacman -S fuse3

# Load the kernel module (usually auto-loads on access, but this guarantees it)
sudo modprobe fuse

# Verify
ls -l /dev/fuse          # should be present
fusermount3 --version    # should print 3.x

No additional configuration needed — run the binary directly.

Docker / Dev Container

When running inside a container, FUSE support must be explicitly granted at container creation time:

docker run \
  --device /dev/fuse \
  --cap-add SYS_ADMIN \
  my-image

For VS Code Dev Containers, add to .devcontainer/devcontainer.json:

{
  "runArgs": [
    "--device", "/dev/fuse",
    "--cap-add", "SYS_ADMIN"
  ]
}

Why SYS_ADMIN? The mount(2) syscall (which FUSE uses internally) requires CAP_SYS_ADMIN inside a container. The --device /dev/fuse flag exposes the kernel FUSE interface.

Inside the container, libfuse3 is usually preinstalled. If not:

sudo apt update && sudo apt install fuse3

WSL2

WSL2 supports FUSE out of the box with recent kernels:

# Install fuse3 inside your WSL distribution (Ubuntu example)
sudo apt update
sudo apt install fuse3

# Load the module
sudo modprobe fuse

Known issue: Custom WSL2 kernels built before Linux 5.4 may lack FUSE support. Run uname -r to check your kernel version. If FUSE is unavailable, update your WSL kernel via wsl --update from a Windows PowerShell.

Usage

init — create policy files

Creates .agentignore and .agentallow files in a directory:

agentignore init              # current directory
agentignore init /path/project

run — mount, execute, unmount

Mount a filtered view, run a command inside it, and unmount automatically:

# Run bash inside a filtered view of the current directory
agentignore run bash

# Run a specific tool with arguments
agentignore run -- ls -la

# Run from a specific source directory
agentignore run --source /home/user/project bash 

explain — debug visibility

Check whether a path would be hidden and why:

agentignore explain .env
# HIDDEN
# canonical path: "/project/.env"
# matched rule:   .env

agentignore explain src/main.rs
# VISIBLE
# canonical path: "/project/src/main.rs"

Policy Files

.agentignore

Uses standard gitignore pattern syntax. Files matching these patterns are hidden from the agent.

# secrets
.env
*.pem
*.key

# hidden directories
secrets/
node_modules/

# recursive patterns
**/*.tfstate

# negations (exceptions)
!important.env

.agentallow

Process-based bypass rules. Processes matching entries in this file can see hidden files — useful for development tools that need full access.

Example use case: The agent should not "see" files within node_modules but if it launch npm run build, the tool needs these files to build the app.

One entry per line. Empty lines and lines starting with # are ignored (comments).

Process name / cmdline matching

| Syntax | Behaviour | |--------|-----------| | ^npm run | Regex matched against the process comm name or its full cmdline; also checks ancestor processes (parent, grandparent, etc.). | | =npm | Exact match against comm or cmdline; ancestors are also checked. | | =bash! | Exact match, no ancestor walk — matches only the exact process. | | node! | Regex, no ancestor walk — matches only the exact process. |

Binary path matching (entry starts with /)

| Syntax | Behaviour | |--------|-----------| | /usr/bin/node | Literal path; matches process or any ancestor. | | /usr/bin/java! | Literal path; matches only that exact process. |

# Allow npm and its children to see everything (regex, walks ancestors)
npm

# Allow only the exact 'restic backup' command (exact match, no ancestor walk)
=restic backup!

# Allow the exact bash process, not commands run inside it (exact, no ancestor walk)
=bash!

# Allow any java process or its children (regex, walks ancestors)
java

# Allow a specific binary and everything under it (literal path, walks ancestors)
/usr/bin/git

# Allow only that exact binary path (literal path, no ancestor walk)
/usr/bin/git!

Building from Source

Build prerequisites

See https://rust-lang.org/tools/install/ how to prepare rust dev environmet or use the provided devcontainer in this repo.

Build commands

# Fast type-check during development
cargo check

# Debug build
cargo build

# Optimized release build
cargo build --release

# Run with cargo
cargo run -- mount /real/project /mnt/agent

# Run tests
cargo test

# Run linter and formatter before committing
cargo clippy -- -D warnings
cargo fmt

Development

Or you can create one yourself. See docs/project.md for a one-shot prompt to re-create the project.