shim-cli

Product Introduction

1. Definition: Shim-cli is an open-source, local-first command-line interface (CLI) tool and proxy designed to function as a privacy and security hook for AI-powered coding assistants. It operates as a middleware layer between clients like Claude Code, Codex, Copilot CLI, and VS Code and their respective AI models.
2. Core Value Proposition: Shim-cli exists to provide developers with visibility and control over the data their AI coding agents transmit. Its primary function is to detect and mask sensitive information—such as secrets, API keys, and personal data—in real-time before it reaches the AI model, thereby reducing the risk of accidental data exposure and providing cost transparency for Claude Code sessions.

Main Features

1. Multi-Client Privacy Hooks: Shim-cli integrates directly with specific coding agent clients using their native hook or plugin systems. For Claude Code, it actively masks detected secrets within files and tool results before the model processes them. For Codex and VS Code, it operates in a reporting or enforcement mode, alerting the user or blocking prompts containing sensitive data. In Copilot CLI, it replaces the original prompt sent to the model with a redacted version.
2. Comprehensive Secret Detection Engine: The tool employs a robust, pattern-matching engine with over 727 test cases to identify a wide range of sensitive data types. This includes email addresses, phone numbers, credit card numbers, API keys, passwords in configs, database URIs, IP/MAC addresses, US SSNs, and region-specific identifiers like Turkish national IDs. It also supports custom user-defined patterns for organization-specific data.
3. Session Audit and Cost Analysis (shim audit): A unique feature for Claude Code users, this command locally parses the agent's session history stored on disk. It provides a detailed, private breakdown of what data was sent to the model, categorized by data type, project, and transmission method, along with associated token usage and cost estimates, without transmitting any data externally.

Problems Solved

1. Pain Point: Developers inadvertently expose secrets and private data when using AI coding assistants, as these tools send context from open files, terminal output, and tool results to remote models for processing, creating a significant security and compliance risk.
2. Target Audience: Security-conscious software engineers, DevOps professionals, and development teams using AI coding assistants (Claude Code, GitHub Copilot, etc.) who work with proprietary code, customer data, or infrastructure secrets. It is particularly relevant for those in regulated industries or handling sensitive user information.
3. Use Cases: Essential for reviewing codebases containing configuration files with credentials, debugging production logs that may contain user PII, working with database query results, or any scenario where the coding agent's context may include data that should not be transmitted to a third-party AI service.

Unique Advantages

1. Strengths & Limitations (Pros & Cons):

   • Pros: Operates fully locally with no account, API key, or telemetry, ensuring maximum privacy. Offers granular, client-specific behavior (masking vs. reporting). Provides unique cost and data audit capabilities for Claude Code. Lightweight, with a median hook cost of ~70ms. Open-source (Apache-2.0) allowing for inspection and customization.
   • Cons: Detection is best-effort and not a guaranteed data-loss prevention boundary. Client support is uneven; for example, VS Code cannot mask data, only report or block. Does not inspect tool traffic for Codex/Copilot CLI. No support for Windows (only macOS/Linux). Cannot mask user-typed prompts in Claude Code/Codex due to client restrictions.

2. Key Alternatives & Differentiation:

   • GitHub Copilot with Built-in Filters: GitHub Copilot has rudimentary filters to block common secrets like API keys. Shim-cli differentiates by offering far more comprehensive detection (including PII), multi-client support, local-only operation, and detailed audit logs, whereas Copilot's filtering is a black-box, cloud-based service.
   • Manual Code Review/Pre-commit Hooks: Traditional methods like gitleaks or truffleHog in pre-commit hooks scan repositories for secrets. Shim-cli operates in real-time during AI interaction, protecting data during the development workflow, not just before commit. It addresses the unique threat vector posed by AI agents actively reading your workspace.
   • Enterprise Data Loss Prevention (DLP) Suites: Large DLP solutions are complex, expensive, and network-focused. Shim-cli is a lightweight, developer-centric tool focused specifically on the AI-pair-programming use case, is easy to install, and requires no corporate infrastructure.

Frequently Asked Questions (FAQ)

1. Does shim-cli send my data to a remote server? No, shim-cli is a local-first tool with a core principle of zero telemetry. All detection, masking, and audit analysis (shim audit) occurs entirely on your local machine. No data is sent to external servers.
2. Can shim-cli completely prevent secret leakage with AI coding assistants? No, shim-cli is a best-effort privacy tool, not an impermeable security boundary. Its detection may have false negatives, and its capabilities are limited by what each client's hook system allows (e.g., it cannot mask typed prompts in Claude Code). It significantly narrows the exposure window but should be part of a broader secret management strategy.
3. What is the difference between shim-cli and just using environment variables for secrets? While environment variables are a best practice, AI coding assistants often read the contents of .env files, config files, or command output that may print secrets. Shim-cli adds a layer of protection for these in-situ secrets that haven't been externalized, and for personal data that cannot be stored in environment variables.
4. How does shim audit work without connecting to the internet? The shim audit command reads Claude Code's session history files, which are stored locally on your disk. It processes these files offline to reconstruct and categorize what data was sent, calculating costs based on known token pricing, without ever needing to transmit the audit data.
5. Why does shim-cli behave differently for Claude Code vs. VS Code? The behavior is dictated by the capabilities of each client's hook or extension API. Claude Code's hook system allows shim-cli to intercept and modify data (masking). VS Code's extension API only allows shim-cli to inspect and potentially cancel requests (reporting/enforcement) but not alter the data that has already been fetched or displayed.