[!IMPORTANT] ContextLock 1.x is the stable CLI and MCP contract line. Pin a specific version in shared automation if you need repeatable behavior.

The npm package is intentionally CLI-only; importing contextlock as a library is not a supported API. See Stability Policy for the stable contracts, limitations, SemVer policy, and release checklist.

Why ContextLock?

AI coding agents are more useful with repository context, but real projects can contain .env files, private keys, database URLs, credentials, webhooks, and client data. ContextLock provides a controlled local boundary between an MCP-compatible AI client and a project:

AI coding client
      |
      | local stdio MCP
      v
 ContextLock
      |
      | block files + redact values + report risks
      v
 Local repository

• Local-first: repository content is processed on your machine.
• Blocked by policy: sensitive files never appear in safe file listings or reads.
• Redacted before return: supported secret patterns are replaced with clear placeholders.
• Inspectable: scan and report commands show what the active policy finds.
• Configurable: each project can maintain its own policy file.

Quick Start

ContextLock requires Node.js 22.13+. The stable npm line is contextlock@1; pin an exact version, such as [email protected], when automation must be fully repeatable.

Run it without installing:

npx --yes contextlock@1 --help

Initialize a policy in the repository you want to protect, then scan it:

cd /path/to/your/project
npx --yes contextlock@1 init
npx --yes contextlock@1 scan
npx --yes contextlock@1 report
npx --yes contextlock@1 doctor

Start the MCP server from the project being protected:

npx --yes contextlock@1 mcp

Or install it globally:

npm install -g contextlock@1
contextlock scan

Use a stronger starter policy for common project types:

contextlock init --android
contextlock init --node
contextlock init --python
contextlock init --mobile-ai

MCP Client Setup

Configure your coding agent to launch ContextLock from the repository you want to protect. The examples below use npx --yes contextlock@1 so the published stable npm package is used.

Coding agent	Setup method	Scope
Codex	codex mcp add	User configuration
Claude Code	claude mcp add	Current project by default
Cursor	.cursor/mcp.json	Current workspace
VS Code with GitHub Copilot	.vscode/mcp.json	Current workspace

Codex

From the repository you want ContextLock to protect:

codex mcp add contextlock -- \
  npx --yes contextlock@1 mcp
codex mcp list

Restart Codex or begin a new session in that repository, then ask it to use repo.scan_risks. See the official Codex MCP documentation for configuration details.

Claude Code

From the repository you want to protect, add ContextLock with local scope:

claude mcp add --scope local --transport stdio contextlock -- \
  npx --yes contextlock@1 mcp
claude mcp get contextlock

Start Claude Code in the same repository and run /mcp to check the server. Use --scope project instead if you intentionally want to share a .mcp.json configuration with collaborators. See the official Claude Code MCP documentation.

Cursor

Create .cursor/mcp.json in the repository you want to protect:

{
  "mcpServers": {
    "contextlock": {
      "command": "npx",
      "args": ["--yes", "contextlock@1", "mcp"]
    }
  }
}

Open that repository in Cursor, then open Settings > Tools & MCP and enable contextlock. Cursor should discover the five tools after the server starts. See the official Cursor MCP documentation.

VS Code with GitHub Copilot

Create .vscode/mcp.json in the repository you want to protect. VS Code uses a top-level servers key rather than mcpServers:

{
  "servers": {
    "contextlock": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "contextlock@1", "mcp"],
      "cwd": "${workspaceFolder}"
    }
  }
}

Run MCP: List Servers from the Command Palette, start contextlock, and accept the workspace trust prompt after reviewing the command. See the official VS Code MCP configuration reference.

Verify the Connection

After setup, confirm that the agent discovers these five tools:

repo.list_files
repo.read_file_safe
repo.search_safe
repo.scan_risks
policy.explain

Ask the agent to run policy.explain, then repo.scan_risks. If the server does not start:

• Confirm node --version is 22.13 or newer.
• Confirm npx --yes contextlock@1 --help works in a terminal.
• Confirm the agent was opened in the repository you intend to protect.
• Check the agent's MCP server logs for process startup errors.

contextlock mcp-config prints a generic configuration snippet.

Trust Checks

ContextLock includes small diagnostics you can run before trusting an AI agent with a repository:

contextlock doctor
contextlock why .env
contextlock why build/generated/source.ts
contextlock test-policy

• doctor shows the active cwd, config status, package version, Node version, configured MCP transport, redactors, and a sample blocked-path check. It is a local configuration diagnostic, not a live MCP client handshake.
• why <path> explains whether a project-relative path is blocked and which pattern matched.
• test-policy verifies required baseline protections against the active policy, including generated build output, .env, .git, and mobile release artifacts.

Example Workflows

Use ContextLock when you want an AI coding agent to inspect a repository without handing it raw access to sensitive paths or likely secrets. The agent still gets useful context, but through safe MCP tools that block risky files and redact supported secret patterns before returning content.

Start a Safe Repo Inspection

Ask the agent to begin with policy and risk discovery before reading files:

Use ContextLock before inspecting this repository.
First run policy.explain, then repo.scan_risks.
After that, list files with repo.list_files and only read files through
repo.read_file_safe.

Typical tool flow:

1. policy.explain shows which paths and redactors are active.
2. repo.scan_risks summarizes blocked files and detected secret patterns.
3. repo.list_files returns files the active policy allows.
4. repo.read_file_safe reads allowed files with supported secrets redacted.

Review a Feature Without Opening Secrets

Use this when you want help understanding a code path, but the repository may contain .env files, private keys, local databases, or service credentials:

Use ContextLock to inspect the authentication flow.
Search for auth-related code safely, then read only the allowed files needed to
explain the flow.

The agent can use repo.search_safe for terms such as auth, token, session, webhook, or DATABASE_URL. Search results and file reads come back redacted, and blocked files are denied instead of returned.

Check Before Sharing Context

Run a local scan before asking an agent to work deeply in a project:

npx --yes contextlock@1 scan
npx --yes contextlock@1 report --fail-on high

This gives you a quick view of sensitive paths and detected secret patterns. For team projects, commit a reviewed contextlock.config.json so contributors and agents use the same baseline policy.

Handle Denied Access

If the agent asks for a blocked file, keep the boundary intact:

That file is blocked by ContextLock. Use policy.explain and repo.search_safe to
find a safe alternative, or explain what specific non-sensitive detail is needed.

Denied access is expected behavior. It means ContextLock is preserving the project policy instead of leaking raw context.

Agent Skill

ContextLock includes an optional Agent Skills workflow in skills/contextlock. The MCP server enforces blocking and redaction; the skill teaches an agent when to use the five safe tools, how to handle denied access, and not to bypass the active policy.

Install the skill in the repository you want to protect. Choose the directory for your coding agent:

Coding agent	Project skill directory
Codex	.agents/skills/contextlock/
Claude Code	.claude/skills/contextlock/
Cursor	.cursor/skills/contextlock/
VS Code with GitHub Copilot	.github/skills/contextlock/

For example, install it for Codex from the protected repository:

mkdir -p .agents/skills/contextlock
cp /absolute/path/to/contextlock/skills/contextlock/SKILL.md \
  .agents/skills/contextlock/SKILL.md

Use the corresponding directory from the table for another agent. Restart the agent or begin a new session after installation, then ask it to "inspect this repository safely with ContextLock." The agent should start with policy.explain and repo.scan_risks before reading project files.

The skill complements the MCP setup above; it does not install or start the ContextLock server by itself.

MCP Tools

Tool	Purpose
repo.list_files	List text files allowed by the active policy.
repo.read_file_safe	Read an allowed file with supported secrets redacted.
repo.search_safe	Search allowed text content and return redacted snippets.
repo.scan_risks	Summarize blocked files and detected secret patterns.
policy.explain	Show the active blocking and redaction policy.

Default Protection

Running contextlock init creates contextlock.config.json. The default policy blocks common sensitive or generated paths, including:

• .env files, private keys, credentials, service-account files, and database files
• dependency and build output such as node_modules, dist, .next, and .turbo
• Android/mobile local artifacts such as .gradle, .idea, .kotlin, APK/AAB, keystore/JKS files, screenshots/captures, and common local model files
• Git internals under .git

Path protection is case-insensitive, so case variants such as .ENV, BUILD, and uppercase protected extensions receive the same treatment. Allowed text files are scanned for supported API keys, structured secret assignments such as OPENAI_API_KEY=... and TOKEN=..., JWTs, database URLs, private keys, and Slack or Discord webhook URLs. Email redaction is available but disabled by default.

Example configuration:

{
  "schemaVersion": 1,
  "blockedPatterns": [
    ".env",
    ".env.*",
    "**/*.pem",
    "**/*.key",
    "**/credentials.json",
    "**/node_modules/**",
    "**/.git/**",
    "**/dist/**",
    "**/build/**",
    "**/.gradle/**",
    "**/*.apk",
    "**/*.aab",
    "**/*.keystore",
    "**/*.tflite"
  ],
  "redact": {
    "apiKeys": true,
    "jwt": true,
    "databaseUrls": true,
    "privateKeys": true,
    "webhooks": true,
    "emails": false
  }
}

ContextLock reads contextlock.config.json from the process working directory (cwd), which is also the root for relative paths and policy matching. It does not automatically move to the nearest Git root. Set the MCP process cwd to the repository you intend to protect.

Configuration is additive. blockedPatterns adds unique patterns to the baseline list, and redact can enable additional redactors; config cannot turn off baseline protections. schemaVersion: 1 is required when a config file is present. Unknown fields, unsupported schema versions, invalid values, and symlinked config files are rejected with an error.

Use contextlock init --preset <name> or the shortcut flags above to bootstrap project-specific defaults. Available presets are default, android, node, python, and mobile-ai.

[!WARNING] ContextLock reduces accidental exposure; it is not a secret manager, malware scanner, sandbox, or guarantee that every sensitive value will be detected. Keep credentials out of source control and review your project policy before granting an AI client access.

Development

Clone the repository when you want to contribute or test local changes:

git clone [email protected]:LutaElbert/contextlock.git
cd contextlock

pnpm install --frozen-lockfile
pnpm test

The aggregate test command covers scanner and policy behavior, CLI and MCP smokes, the bundled skill, type checking, and installation from the generated npm tarball. CI runs it on the minimum Node.js 22.13 release and Node.js 24.

For development against this repository:

pnpm dev -- scan
pnpm dev -- mcp
pnpm dev -- mcp-config --local

Roadmap

• Expand secret detection and policy test coverage.
• Improve audit reports and machine-readable findings.
• Add richer project-type policy packs.
• Add premium team policy sync, database sanitization, and enterprise audit exports without weakening the local-first core.

Core promise: No cloud required. Your code stays local.

Releases

npm packages and GitHub releases are published through the Release workflow after the package version is updated on main.

1. Update package.json to the next version in a pull request.
2. Merge the pull request into main.
3. Open the Release workflow and choose Run workflow.
4. Enter the matching tag, such as v1.1.0 or v1.1.0-rc.1, set the prerelease input consistently, and run it.

The main-only workflow validates the tag and prerelease state before installing dependencies, runs the complete suite, publishes with provenance, and creates a GitHub release. Prereleases use npm's next tag. Retrying is safe when the npm version or GitHub release already exists. The workflow requires an NPM_TOKEN repository secret with npm package publishing permissions.

Contributing

Contributions are welcome. Read CONTRIBUTING.md before opening a pull request, follow the Code of Conduct, and use only synthetic or redacted test data.

Report vulnerabilities privately according to SECURITY.md.

License

ContextLock is licensed under the Apache License 2.0.