secret-scratch
Pass secrets to coding agents as $$value without the LLM, transcript, or logs ever seeing them. Drop-in ACP proxy, stdio MCP server, and zero-dependency TypeScript library.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 21 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/inixiative/secret-scratch with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/inixiative/secret-scratch'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/inixiative--secret-scratch)HTML
<a href="/listings/inixiative--secret-scratch"><img src="/api/listings/inixiative--secret-scratch/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Wrap any ACP agent command with `npx @inixiative/secret-scratch --`:
npx -y @inixiative/secret-scratch -- <your-acp-agent-command> [args...]
Or install globally:
npm install -g @inixiative/secret-scratch secret-scratch -- <your-acp-agent-command> [args...]
Example: Zed (`settings.json`)
{
"agent_servers": {
"Claude Code (secret-scratch)": {
"command": "npx",
"args": ["-y", "@inixiative/secret-scratch", "--", "claude-agent-acp"]
},
"Codex (secret-scratch)": {
"command": "npx",
"args": ["-y", "@inixiative/secret-scratch", "--", "codex-acp"]
},
"Gemini CLI (secret-scratch)": {
"command": "npx",
"args": ["-y", "@inixiative/secret-scratch", "--", "gemini", "--experimental-acp"]
}
}
}When a session starts, the proxy:
- Injects the `secret-scratch` stdio MCP server into `session/new`, `session/load`, `session/resume`, and `session/fork` (preserving all other MCP servers). - Lifts `$$value` markers and recognised secret shapes on `session/prompt` before forwarding to the agent, attaching usage guidance on the first turn that carries a secret. - Rejects `session/request_permission`, `fs/read_text_file`, `fs/write_text_file`, and `terminal/create` calls targeting held files, `.private` paths, or `~/.secret-scratch`. - Scrubs held values out of `session/update` notifications.
CLI flags
secret-scratch [options] -- <acp-agent-command> [args...] secret-scratch mcp --dir <path> --thread <id> [--cwd <path>] secret-scratch list [--dir <path>] [--thread <id>] secret-scratch clear <thread> [--dir <path>] Options: --dir <path> Scratch pad directory (default: ~/.secret-scratch) --private <glob> Extra private path glob to block (repeatable) --no-lift-shaped Only lift explicit $$value markers --no-scrub Disable scrubbing held values from session/update
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 146 lines
- # secret-scratch
- Pass secrets to coding agents as `$$value` without the LLM, transcript, or logs ever seeing them.
- 
- ```text
- You type: Put $$sk_live_9876543210 into .env.local as STRIPE_KEY, then push it to GitHub Actions.
- Agent sees: Put †m1.1 into .env.local as STRIPE_KEY, then push it to GitHub Actions.
- Agent calls: secret_scratch(action: "env", ref: "†m1.1", path: ".env.local", key: "STRIPE_KEY")
- secret_pipe(envFile: ".env.local", key: "STRIPE_KEY", command: "gh secret set STRIPE_KEY")
- Agent gets: { ok: true, exitCode: 0 }
- Agent tries: cat .env.local -> BLOCKED (.env.local is held by secret-scratch)
- ```
- Zero runtime dependencies. Works with Node.js 20+ and Bun 1.4+. Ships three ways to integrate:
- 1. **Drop-in Agent Client Protocol (ACP) middleware proxy** (`secret-scratch -- <acp-agent-command>`) wrapping Claude ACP, Codex ACP, Gemini CLI ACP, or any ACP agent inside hosts such as Zed and JetBrains.
- 2. **Stdio MCP server** (`secret-scratch mcp`) exposing `secret_scratch` and `secret_pipe`.
- 3. **TypeScript library** (`@inixiative/secret-scratch`) for custom harnesses and agent runtimes.
- ## Why
- Pasting an API key or private key into a coding agent chat sends the secret to the model provider, writes it into session transcripts, and leaves it in tool logs and crash dumps.
- `secret-scratch` intercepts secrets before they reach the model:
- 1. **Lift before inference.** Any word prefixed with `$$` (plus common shaped tokens such as `sk-...`, `ghp_...`, `AKIA...`, `AIza...`, and PEM private keys if you forget the prefix) is moved into a `0600` per-thread scratch pad file in `~/.secret-scratch/` (`0700`) and replaced with an opaque reference like `†m1.1`.
- 2. **Use by reference.** The agent receives two MCP tools: `secret_scratch` (`list`, `env`, `write`, `consume`) and `secret_pipe` (pipes a secret to a shell command's `stdin`, discards `stdout` and `stderr`, returns only `exitCode`).
- 3. **Block access to held files.** Every file written by `secret_scratch` is recorded in `held-files.json`. ACP permission requests, filesystem calls, and terminal calls targeting a held file, a `.private` path, or the scratch pad directory are denied at the proxy boundary.
- 4. **Scrub outgoing updates.** Held values (6+ characters) are scrubbed from outgoing `session/update` frames back into their `†` reference as defense in depth.
- ## Quick start (ACP proxy)
- Wrap any ACP agent command with `npx @inixiative/secret-scratch --`:
- ```bash
- npx -y @inixiative/secret-scratch -- <your-acp-agent-command> [args...]
- ```
- Or install globally:
- ```bash
- npm install -g @inixiative/secret-scratch
- secret-scratch -- <your-acp-agent-command> [args...]
- ```
- ### Example: Zed (`settings.json`)
- ```json
- {
- "agent_servers": {
- "Claude Code (secret-scratch)": {
- "command": "npx",
- "args": ["-y", "@inixiative/secret-scratch", "--", "claude-agent-acp"]
- },
- "Codex (secret-scratch)": {
- "command": "npx",
- "args": ["-y", "@inixiative/secret-scratch", "--", "codex-acp"]
- },
- "Gemini CLI (secret-scratch)": {
- "command": "npx",
- "args": ["-y", "@inixiative/secret-scratch", "--", "gemini", "--experimental-acp"]
- }
- }
- }
- ```
- When a session starts, the proxy:
- - Injects the `secret-scratch` stdio MCP server into `session/new`, `session/load`, `session/resume`, and `session/fork` (preserving all other MCP servers).
- - Lifts `$$value` markers and recognised secret shapes on `session/prompt` before forwarding to the agent, attaching usage guidance on the first turn that carries a secret.
- - Rejects `session/request_permission`, `fs/read_text_file`, `fs/write_text_file`, and `terminal/create` calls targeting held files, `.private` paths, or `~/.secret-scratch`.
- - Scrubs held values out of `session/update` notifications.
- ### CLI flags
- ```text
- secret-scratch [options] -- <acp-agent-command> [args...]
- secret-scratch mcp --dir <path> --thread <id> [--cwd <path>]
- secret-scratch list [--dir <path>] [--thread <id>]
- secret-scratch clear <thread> [--dir <path>]
- Options:
- --dir <path> Scratch pad directory (default: ~/.secret-scratch)
- --private <glob> Extra private path glob to block (repeatable)
- --no-lift-shaped Only lift explicit $$value markers
- --no-scrub Disable scrubbing held values from session/update
- ```
- ## Library usage
- ```ts
- import {
- SecretScratchPad,
- SHAPED_SECRET_PATTERNS,
- privatePathGate,
- scratchTarget,
- } from '@inixiative/secret-scratch';
- const pad = new SecretScratchPad('~/.secret-scratch');
- // 1. Lift before sending to the LLM
- const { text, refs } = pad.lift(
- 'Set STRIPE_KEY to $$sk_live_example1234567890 in .env.local',
- { thread: 'thread_1', message: 'm1' },
- { patterns: SHAPED_SECRET_PATTERNS },
- );
- // text === 'Set STRIPE_KEY to †m1.1 in .env.local'
- // 2. Write safely inside cwd (rejects .., symlink escapes, .git, .claude, .ssh)
- const target = scratchTarget(process.cwd(), '.env.local');
- pad.env({ ref: refs[0]! }, 'thread_1', target, 'STRIPE_KEY', { consume: true });
- // 3. Pipe straight to a CLI without returning stdout/stderr
- const { exitCode } = await pad.pipe(
- { envFile: target, key: 'STRIPE_KEY' },
- 'thread_1',
- 'gh secret set STRIPE_KEY',
- );
- // 4. Gate agent file/shell tools
- const gate = privatePathGate({
- scratchDir: pad.dir,
- heldFiles: pad.heldFiles(),
- });
- gate({ toolName: 'Bash', toolInput: { command: 'cat .env.local' } });
- // { behavior: 'deny', message: '.env.local is private: ...' }
- ```
- See [docs/VERBS.md](docs/VERBS.md) for the complete public API table.
- ## Security model and boundaries
- - **Prevents accidental exposure to the LLM, agent transcripts, and tool output.** Secrets lifted at the prompt boundary never enter model context, prompt caches, or downstream agent session transcripts. `secret_pipe` discards `stdout` and `stderr` and kills the whole process group on timeout.
- - **On-disk storage is `0600` plaintext in a `0700` directory.** Scratch pads live at `~/.secret-scratch/<thread>.pad` until consumed or cleared (`secret-scratch clear <thread>`). They protect against LLM and transcript leakage, not against another process running as your OS user.
- - **Shell gating and `secret_pipe` defend against accidental leaks, not a hostile sandbox.** If a downstream agent runs shell commands directly inside its own process without asking the ACP host via `session/request_permission` or `terminal/create`, the ACP proxy cannot intercept those local subprocess calls. Likewise, an adversarial model that can pass arbitrary shell commands to `secret_pipe` could write stdin to an untracked file or encode bytes in the exit code. For enforcement against an untrusted model, pair `secret-scratch` with an OS sandbox or a harness that routes all tool calls through `privatePathGate` and restricts allowed pipe commands.
- - **Single-word marker.** `$$value` lifts up to the next whitespace. Multi-line secrets (such as PEM private keys) are lifted by shape automatically; arbitrary multi-line secrets should be passed by file or env key rather than `$$`.
- ## Origin
- Extracted from [Foundry](https://inixiative.com/foundry/), a source-available (BSL 1.1) local agent harness built by [inixiative](https://inixiative.com).
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.