What Happened

Simon Willison released scan-for-secrets version 0.1, a Python command -line tool designed to detect API keys and other credentials in local files before they are published. The tool was built specifically to address a gap in his workflow: publishing transcripts of Claude Code sessions via his claude-code-transcripts tool while ensuring no API keys leak into the log files.

The tool is installable and runnable without a full install via uvx, the runner bundled with the uv Python package manager. A basic scan looks like this:

uv x scan-for-secrets $OPENAI_API_KEY -d logs-to-publish/

Omitting the -d flag defaults to scanning the current working directory. The project is available on PyPI and the source is open.

Technical Deep Dive

The tool goes beyond simple literal string matching. It also detects common encodings of a secret, including backslash-escaped variants and JSON-escaped forms. This matters because log files generated by AI coding agents often serialize content to JSON, meaning a raw API key like sk-abc123 might appear as sk-abc123 or with escaped characters depending on how the logging layer serializes output.

For users who protect a fixed set of credentials repeatedly, scan-for-secrets supports a configuration file at ~/.scan-for-secrets.conf.sh. Each line in this file is a shell command whose stdout is treated as a secret to scan for. Willison's own config file reads:

llm keys get openai
llm keys get anthropic
llm keys get gemini
llm keys get mistral
awk -F= '/aws_secret_access_key /{print $2}' ~/.aws/credentials | xargs

This design delegates secret retrieval to existing credential stores (llm key management and AWS credentials files) rather than storing secrets in plaintext inside the config itself . The config file is executed as a shell script, so any command that echoes a secret to stdout is valid.

README-Driven Development with Claude Code

Willison used a workflow he calls README-driven development: he wrote the complete README first, specifying exact CLI behavior, flag names, config file format, and encoding detection requirements, then fed that README to Claude Code with an instruction to implement the tool using red/green test-driven development. The AI agent wrote the implementation and tests iteratively against the spec in the README. This approach treats the README as a formal specification document rather than documentation written after the fact.

Encoding Detection

The encoding-aware scanning is the most technically interesting aspect. An API key embedded in a JSON log might appear as a JSON string with escaped characters, or it might be base64-encoded in some logging pipelines. The tool normalizes both the candidate secret and the file content before comparison, catching variants that a plain grep would miss. The full list of supported encodings is documented in the project README on GitHub.

Who Should Care

  • Developers publishing AI session transcripts: Tools like Claude Code, Cursor, and similar agents produce verbose logs that may capture environment variables or clipboard content containing secrets.
  • Security-conscious teams using uv : The uvx runner makes this a zero-install scan step that can be added to a pre-publish chec klist or CI pipeline.
  • Anyone using Simon Willison's llm CLI : The config file example integrates directly with the llm keys credential store , making setup trivial for existing llm users.
  • Prompt engineers and researchers who share session logs publicly as examples or tutorials face the same risk this tool addresses.

What To Do This Week

Install and run a baseline scan on any AI session log directories you already have:

uvx scan-for-secrets $OPENAI_API_KEY $ ANTHROPIC_API_KEY -d ~/ai-logs/

Then create a ~/.scan-for-secrets.conf.sh file with commands that retrieve all credentials you regularly use. If you use the llm CLI, commands like llm keys get openai are the fastest path. If you store AWS credentials in ~/.aws/credentials, add the awk line from Willison's config.

Consider adding a scan step to any script or Makefile target you use before publishing transcripts or uploading log archives. Because uvx requires no prior installation of the package, this works on CI runners without adding scan-for-secrets to your project 's dependency list:

uvx scan-for-secrets $(llm keys get openai) - d ./transcripts/ && echo "No secrets found"

The tool is at version 0.1, so treat it as a useful safety net rather than a compliance-grade secret scanner. For production pip elines, pair it with established tools like gitleaks or truffleHog . For personal publishing workflows, it directly solves the problem it targets.