Cline .clineignore: Setup, Deprecation, and PreToolUse Hooks

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.

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

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

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.

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.

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.

Isolate Sensitive Agent Files in Shared Workspaces

Connect Cline to Fast.io through remote MCP to keep secrets and build artifacts off your local filesystem. Every organization starts with a 14-day free trial.

Start 14-Day Trial

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:

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:

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).

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:

{
  "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.

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, 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. Teams can review full plan options to choose the right capacity for their agent deployments.