# Cline .clineignore: Setup, Deprecation, and PreToolUse Hooks

A .clineignore file is a pattern-based configuration file in Cline designed to prevent the AI agent from automatically ingesting sensitive keys, build artifacts, and private repository directories. The original mechanism filtered automatic context loading but left shell execution unconstrained. Modern Cline setups replace .clineignore with PreToolUse hooks and gitignore guard plugins that actively intercept tool calls and block unauthorized file access.

Source: https://fast.io/resources/cline-clineignore-guide/
Last reviewed: 2026-09-09

## Why .clineignore Fails as an Access Control Boundary

Developers routinely add a `.clineignore` file to their repository root expecting it to establish a secure sandbox around private keys, API credentials, and environment variables, only to discover that the agent can still inspect those exact files through shell commands. The original `.clineignore` mechanism was engineered as a prompt-slimming tool rather than an access-control boundary. It suppressed files from initial repository scans and directory listings, but it never restricted what the model could request through execution tools.

A .clineignore file is a pattern-based configuration file in Cline designed to prevent the AI agent from automatically ingesting sensitive keys, build artifacts, and private repository directories.

When an autonomous coding agent starts a task in a project without ignore rules, it walks the entire filesystem hierarchy to map project architecture. In a modern full-stack web application, package manager directories such as `node_modules`, `vendor`, or `.venv` can contain tens of thousands of individual source files. Build output targets such as `dist`, `build`, and `.next` contain compiled bundles and source maps, while local databases, cache stores, and test fixtures introduce megabytes of structured data.

Dumping these extraneous directories into the prompt context wastes input tokens, inflates API billing, and pushes relevant code out of the context window. Adding a .clineignore can cut your starting context from 200k+ tokens to under 50k, according to official Cline documentation. That reduction lowers latency and enables cost-effective model usage. When an agent only ingests the files necessary for its task, response times accelerate and the model maintains sharper attention over actual project logic.

The problem lies in how developers interpret exclusion files. Most engineering tutorials treat `.clineignore` as an authorization boundary. This assumption creates severe security blind spots. An agent given a prompt like "diagnose why database connections fail" might run a shell command like `cat .env` or `grep -rn "DB_PASSWORD" .`. Because `.clineignore` only controls automatic context population, the shell tool executes unobstructed, exposing database passwords or third-party API tokens to the model context.

Explicit `@` mentions in Cline, such as `@.env` or `@secrets/keys.pem`, also bypass `.clineignore` by design. The prompt engine treats an explicit mention as a direct user instruction to read the file, ignoring all exclusion patterns. Understanding this limitation explains why modern Cline workflows require active tool interception instead of passive file exclusion.

## How to Configure Legacy .clineignore Patterns and Rules

For teams maintaining existing projects, understanding `.clineignore` syntax remains necessary during the transition to modern hook-based guards. The file lives at the workspace root and adopts the exact pattern syntax of Git ignore files (`.gitignore`).

The parser evaluates rules line by line, ignoring blank lines and comments that begin with a hash character. Directory rules require a trailing slash, root-anchored rules begin with a leading slash, and glob patterns handle wildcard matching across directory depths.

### Pattern Syntax Rules and Matching Behavior

| Pattern | Matching Behavior | Target Asset Class |
| :--- | :--- | :--- |
| `node_modules/` | Matches the directory at any repository depth | Package dependencies |
| `/dist/` | Matches the directory at the project root only | Build output targets |
| `*.env*` | Matches any file name containing `.env` | Secret environment files |
| `secrets/**` | Matches all contents within the folder recursively | Local certificates and keys |
| `!important.csv` | Explicitly allows the named file despite wildcards | Required test fixtures |

A comprehensive `.clineignore` file addresses three distinct categories of files: dependencies, generated code, and local environment secrets.

```text
node_modules/
**/node_modules/
vendor/
.venv/

/build/
/dist/
/.next/
/out/
/target/
*.tsbuildinfo

/coverage/
*.lcov

.env
.env.*
*.pem
*.key
*.pfx

*.csv
*.xlsx
*.sqlite
*.parquet
*.dump

*.min.js
*.map
```

### Multi-Root Workspaces and Ignore Isolation

In multi-root configurations where an editor workspace spans multiple standalone repositories, each root directory requires its own `.clineignore` file. The patterns evaluate relative to their respective workspace root rather than the parent directory. If workspace root A contains a `.clineignore` that blocks `.env`, an agent operating inside workspace root B will not inherit those exclusions unless root B contains an identical file.

### Differentiating .clineignore from .gitignore

A repository often tracks large reference schemas, generated documentation, or local mock data in Git. While these files belong in version control, feeding them into Cline's agent context burns tokens without improving coding quality. Placing those files in `.clineignore` allows developers to decouple version control decisions from AI context consumption. Files tracked by Git can be safely excluded from the agent's automatic context window without altering repository commit history.

## Why Cline Is Phasing Out Built-in .clineignore Support

Cline has designated `.clineignore` as "deprecating soon" in official documentation and release deprecation matrices. The decision stems from real-world telemetry and user feedback regarding safety expectations.

When developers see a file named `.clineignore`, they draw an intuitive analogy to `.gitignore` or access control lists, assuming the agent cannot touch matching paths. Because `.clineignore` does not intercept tool calls, users regularly suffered credential leaks when agents used terminal commands (`run_commands`) to inspect repository files. To eliminate this false sense of security, the Cline core team decided to sunset `.clineignore` as a native feature and replace it with active interception mechanisms.

Context reduction and access control represent two distinct operational requirements. Context reduction optimizes token economy during repository exploration. Access control is an authorization boundary that must reject unauthorized tool requests regardless of how the agent attempts to access the file.

### Evaluating Modern Alternatives

Modern Cline architectures provide two paths for controlling file access:

1. **PreToolUse Hooks**: Custom executable scripts placed in `.clinerules/hooks/PreToolUse` (for VS Code) or `.cline/hooks/PreToolUse.sh` (for the CLI). The hook evaluates every tool call before execution and returns a structured response that cancels the action if an ignored path is targeted.
2. **Block Ignored File Access Plugin**: An official plugin (`gitignore-read-files-guard.ts`) installed via `cline plugin install`. It reads the project `.gitignore` and blocks tool-level file reads and edits. However, as documented in Cline's deprecation guide, the plugin does not inspect shell commands and should not be treated as an access-control boundary.

| Capability Dimension | Legacy .clineignore | Block Ignored File Access Plugin | PreToolUse Guard Hook |
| :--- | :--- | :--- | :--- |
| **Context Window Filtering** | Yes | Yes (via .gitignore) | No (intercepts tools only) |
| **Blocks read_files** | No (only hides listings) | Yes | Yes |
| **Blocks apply_patch and editor** | No | Yes | Yes |
| **Blocks Shell Commands** | No | No | Yes (token analysis) |
| **Protects Ignore Configuration** | No | No | Yes |
| **Enforcement Point** | Context builder | Tool dispatch | Hook execution barrier |

The PreToolUse hook provides the most complete protection profile because it evaluates file reads, patch applications, editor updates, and shell command arguments before the agent executes them.

## How PreToolUse Hooks Block File Reads and Shell Commands

The recommended method for enforcing file boundaries in modern Cline is the `PreToolUse` hook. By installing the official `PreToolUse_ClineignoreGuard.sh` script, developers can keep their existing `.clineignore` pattern file while upgrading its enforcement from a passive context filter to an active execution gate.

### Installing the Hook in the VS Code Extension

For the VS Code extension, hooks reside in `.clinerules/hooks/` for project-specific rules, or `~/Documents/Cline/Hooks/` for global enforcement across all repositories. The hook file must match the exact event name with no file extension, contain a shell shebang, and have executable permissions:

```bash
mkdir -p .clinerules/hooks
curl -o .clinerules/hooks/PreToolUse https://raw.githubusercontent.com/cline/cline/main/sdk/examples/hooks/PreToolUse_ClineignoreGuard.sh
chmod +x .clinerules/hooks/PreToolUse
```

After saving the script, open Cline extension settings and verify that the **Enable Hooks** toggle is activated.

### Installing the Hook in the Cline CLI

For command-line runs, the CLI looks for hooks in `.cline/hooks/` within the active workspace, `~/.cline/hooks/` globally, or a custom directory specified via `--hooks-dir`:

```bash
mkdir -p .cline/hooks
curl -o .cline/hooks/PreToolUse.sh https://raw.githubusercontent.com/cline/cline/main/sdk/examples/hooks/PreToolUse_ClineignoreGuard.sh
chmod +x .cline/hooks/PreToolUse.sh
```

### How the Guard Script Intercepts Tool Invocations

The script receives an execution payload over standard input. It normalizes differences between the VS Code extension (which passes stringified JSON parameters in `.preToolUse.parameters`) and the CLI (which sends structured objects in `.tool_call.input`).

```bash
tool=$(echo "$input" | jq -r '.tool_call.name // .preToolUse.toolName // ""')

case "$tool" in
  read_files|editor|apply_patch|run_commands) ;;
  *) echo '{"cancel": false}'; exit 0 ;;
esac
```

When Cline dispatches a tool, the hook evaluates the operation through a five-stage pipeline:

1. **Tool filtering**: The script isolates operations that touch files or run commands: `read_files`, `editor`, `apply_patch`, and `run_commands`. Non-filesystem tools pass through with `{"cancel": false}` immediately.
2. **Path extraction**: For `read_files` and `editor`, the script extracts file paths from arguments. For `apply_patch`, it parses the patch headers (`*** Add File:`, `*** Update File:`). For `run_commands`, it splits shell command lines into tokens to identify commands such as `cat .env` or `cp secrets/key.pem /tmp/`.
3. **Lexical path normalization**: Dot segments (`.` and `..`) are resolved lexically to prevent traversal evasion techniques such as `secrets/../.env`.
4. **Self-protection**: If the agent attempts to modify `.clineignore` using `editor` or `apply_patch`, the hook blocks the call. This prevents the agent from removing ignore patterns to grant itself access.
5. **Pattern evaluation via git check-ignore**: The script creates an isolated scratch directory and evaluates candidate paths using `git check-ignore --stdin --no-index` configured with `.clineignore` as the excludes file. This provides native Git pattern semantics without requiring the workspace itself to be a Git repository.

When an unauthorized path is detected, the script outputs a cancellation payload:

```json
{
  "cancel": true,
  "errorMessage": "Blocked read_files: .env matched a .clineignore pattern, so Cline may not access it. Update .clineignore if access should be allowed."
}
```

The cancellation halts the current task immediately. In VS Code, the interface displays an Aborted status. In the CLI, the run terminates until the user sends a follow-up message.

### Operational Limits of Shell Token Inspection

While PreToolUse hooks provide substantial security improvements over passive ignore files, developers must recognize their operational limits:

- **Token matching versus shell interpretation**: The shell guard checks command tokens rather than parsing full shell grammar. It stops direct invocations like `cat .env`, but indirect shell operations, variable assignments, or obfuscated commands could slip past token checks.
- **Symlink resolution**: The script normalizes paths lexically without resolving filesystem symlinks. If a repository contains a symlink pointing to an ignored file, add the symlink path to `.clineignore` as well.
- **CLI mode constraints**: In the Cline CLI, hooks do not execute when running with the `--yolo` flag. When working in sensitive repositories, use `--act` or `--plan` modes instead.

## Restricting Agent File Access Across Teams and Shared Workspaces

Client-side ignore files and local hook scripts provide useful workstation boundaries, but they remain fragile in collaborative team environments. A developer might forget to mark a hook script executable, disable hooks in settings, or clone a repository where `.clinerules/` is omitted from version control. Relying entirely on client-side controls leaves organizations vulnerable to accidental secret leakage.

A more dependable architecture isolates sensitive project documentation, configuration parameters, and shared deliverables in dedicated cloud workspaces. Instead of distributing production secrets or customer documents across individual developer laptops where autonomous coding agents have file system access, teams stage resources in centralized workspaces with strict access policies.

### Multi-Tiered Secret and Context Management

Engineering organizations balance productivity and safety by dividing agent storage into three distinct tiers:

1. **Runtime Secret Injection**: Credentials and API keys live in dedicated secret managers (such as Doppler or 1Password CLI) and inject directly into runtime memory during process startup. Plaintext `.env` files are never written to disk.
2. **Local PreToolUse Interception**: Workstation-level hooks prevent coding agents from inspecting local scratch directories, build artifacts, or private configuration files.
3. **Shared Cloud Workspaces**: Team documentation, architectural specifications, database migration plans, and client deliverables live in [Fast.io workspaces](/storage-for-agents/), where permissions and version history are managed centrally.

### Fast.io Workspace Architecture for AI Agents

Fast.io provides an intelligent workspace platform designed for human-agent collaboration. Instead of granting Cline unmetered access to local drives or relying on consumer cloud storage, organizations connect Cline to Fast.io through its remote Model Context Protocol (MCP) server.

The integration operates through distinct capabilities:

- **Remote MCP Server**: Cline connects to Fast.io using the remote endpoint (`https://mcp.fast.io/mcp` or `https://mcp.fast.io/mcp/key` with bearer token authentication). The MCP server operates over Streamable HTTP with legacy Server-Sent Events (`/sse`) support, requiring no local package installations or process daemons.
- **Granular Permissions**: Access controls can be granted at the organization, workspace, folder, or file level. An agent assigned to an engineering task can be restricted to a specific documentation folder, eliminating the risk of broader repository exposure.
- **Per-File Version History**: Every file in Fast.io maintains complete version history. If an agent writes or modifies shared documentation, previous revisions remain restorable, preventing accidental data loss during autonomous tasks.
- **Append-Only Audit Log**: Every action taken by human teammates or autonomous agents is captured in an append-only audit log, creating an immutable record of document retrieval, updates, and shares.
- **Collaborative Notes**: Teams and agents can co-edit notes in real time, grounding model context on live, shared documentation without reading raw filesystem files.
- **Ownership Transfer**: When an agent finishes scaffolding workspace structures or generating deliverables, it can transfer workspace ownership to a human administrator while retaining administrative access for scheduled updates.

### Team Pricing and Evaluation

Every organization starts with a 14-day free trial, which requires a credit card. | Plans are Starter at $29/mo, Business at $99/mo, and Growth at $299/mo on [Fast.io pricing](/pricing/). Teams can review full plan options to choose the right capacity for their agent deployments.

## Frequently asked questions

### Why is .clineignore being deprecated in Cline?

Cline is deprecating .clineignore because it provided a false sense of security. While .clineignore successfully excluded files from automatic context loading, it was never an enforceable security boundary. Agents could still read ignored files through explicit @ mentions or shell commands like cat .env. Modern Cline releases replace .clineignore with PreToolUse hooks and gitignore guard plugins that actively intercept and block tool execution.

### How do I ignore files in Cline?

To ignore files in Cline, you can install the official PreToolUse guard hook in your workspace (.clinerules/hooks/PreToolUse in VS Code or .cline/hooks/PreToolUse.sh in the CLI) and define patterns in a .clineignore file. Alternatively, you can install the Block Ignored File Access plugin to block file reads based on your project .gitignore file. For existing projects, legacy .clineignore files still filter automatic context loading during the deprecation transition.

### How do I prevent Cline from accessing .env files?

The most effective method is installing the PreToolUse_ClineignoreGuard hook, which inspects tool calls and blocks read_files, editor updates, apply_patch operations, and shell command arguments targeting .env files. Teams should also adopt runtime secret injection via secret managers rather than keeping plaintext credentials on disk, or store sensitive configuration files in permission-scoped cloud workspaces.

### Can shell commands executed by Cline bypass .clineignore?

Yes. The original .clineignore implementation only filtered the file paths loaded into the agent prompt during repository scanning. It did not monitor or restrict shell tool execution. An agent running bash commands could read, copy, or overwrite ignored files freely. Blocking shell command access requires an active PreToolUse hook that tokenizes terminal commands before execution.

### What is the difference between .clineignore and .gitignore?

A .gitignore file instructs Git which files to exclude from version control tracking. A .clineignore file instructs Cline which files to omit from the AI agent automatic context window. Files tracked in Git (such as large test fixtures, reference datasets, or generated documentation) can be excluded from Cline context using .clineignore without removing them from version control.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server at https://mcp.fast.io/mcp, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli.