# Securely share passwords with your Agents

> Source: <https://github.com/inixiative/secret-scratch>
> Published: 2026-11-21 20:36:25+00:00

**Key takeaway:** Prefix secrets with $$ (or rely on recognized shapes like sk-, ghp_, AKIA, AIza and PEM keys) so the ACP proxy lifts them into a 0600 scratch pad and the agent only ever sees a † reference, then use secret_pipe to pass the value to a command's stdin.

Securely send secrets to your AI agent with `$$value` without the LLM, transcript, or logs ever seeing them.

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

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.

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

```
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
js
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](https://github.com/inixiative/secret-scratch/blob/main/docs/VERBS.md) for the complete public API table.

- **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`$$` .

Extracted from [Foundry](https://inixiative.com/foundry/), a source-available (BSL 1.1) local agent harness built by [inixiative](https://inixiative.com).

MIT
