Labs · agentscrub · summary on jarvisosorio.com

agentscrub documentation

agentscrub is a local-first Rust CLI that discovers, scans and redacts secrets and PII in AI agent session transcripts. It runs offline, with no accounts and no telemetry.

Current version: 0.1.0. License: Apache-2.0, © Jarvis Osorio. Source: github.com/JarvisOsorio/agent-session-scrubber. Requires Rust 1.89+. It is not on crates.io or Homebrew yet.

Dry-run redaction is the default. Cursor sessions can be discovered and scanned, but rewrite is refused until SQLite/transcript mutation is proven safe. Retention planning is available; retention.enabled is false by default, and retention apply refuses deletion while that flag is off. This is not a credential revocation service — rotate secrets at the provider after a finding. CI is documented as green on Linux, macOS and Windows.

View the GitHub repository Short project page

What it is for

Developers who keep Claude Code, Codex, Cursor or generic JSONL/JSON agent transcripts on disk and want a local way to find and redact secrets and PII. Agent transcripts often store API keys, cloud credentials and PII in plain text.

Install

git clone https://github.com/JarvisOsorio/agent-session-scrubber.git
cd agent-session-scrubber
cargo install --path .
# or: cargo build --release && ./target/release/agentscrub --help

Usage (fixtures)

Copy fixtures first — never scrub the originals in-tree during experiments. Scan output is masked values and fingerprints only — no raw secrets. Fixtures under tests/fixtures/ are synthetic only.

mkdir -p /tmp/agentscrub-demo/.claude
cp tests/fixtures/claude/session_secrets.jsonl /tmp/agentscrub-demo/.claude/

agentscrub discover --path /tmp/agentscrub-demo
agentscrub scan --path /tmp/agentscrub-demo --format terminal
agentscrub scrub --path /tmp/agentscrub-demo/.claude/session_secrets.jsonl
agentscrub scrub --path /tmp/agentscrub-demo/.claude/session_secrets.jsonl --confirm
agentscrub verify /tmp/agentscrub-demo/.claude/session_secrets.jsonl --format json
# expect: clean=true, remaining_findings=0, exit 0

Against your own agent homes (defaults also look under ~/.claude, and Codex/Cursor roots when configured):

agentscrub discover
agentscrub scan --path ~/.claude --format json --output report.json

Commands

Command	Purpose
`discover`	List recognized session files
`scan`	Detect secrets/PII; exit `8` if the scan is incomplete
`report`	Re-render a saved JSON report (or re-scan)
`scrub`	Dry-run redaction by default; `--confirm` to write
`verify`	Post-remediation check
`retention`	`status` / `plan` / `apply` / `verify` (apply refuses while the flag is off)
`config`	Show effective config

Exit codes: 0 ok · 1 general · 2 bad args · 3 unsupported · 4 permission · 5 validation / unclean verify · 6 remediation · 7 policy · 8 incomplete scan. Incomplete is not clean. Unclean verify exits 5.

Configuration defaults

See config/default.toml. Key defaults:

retention.enabled = false
detection.enable_pii = true
dry-run scrub unless --confirm
local HMAC fingerprint key (never transmitted)

Adapters (v0.1)

Adapter	Read	Redact	Notes
`claude_code`	yes	yes	JSONL sessions
`codex`	yes	yes	JSONL sessions
`cursor`	yes	no	JSONL + SQLite `state.vscdb` scan only — rewrite intentionally disabled
`generic_jsonl`	yes	yes	Configurable text fields
`generic_json`	yes	yes	Single JSON documents

Unsupported or malformed files are skipped and reported, never silently modified.

Limitations

Cursor: discovery and scan work; redaction/rewrite is refused until SQLite/transcript mutation is proven safe.
Retention: retention plan / status are read-only. retention.enabled is false by default; retention apply refuses deletion while the flag is off.
Not a credential revocation service — rotate secrets at the provider after a finding.
Not on crates.io or Homebrew yet — install from the GitHub repository.

Security posture

Local-only; no telemetry; no network for scan, scrub or verify
Never logs raw secrets; reports use masked values and fingerprints
Atomic same-filesystem replace, exclusive lock and pre-write hash recheck
Symlink targets refused for modification
Redaction does not erase backups, snapshots or provider-side copies — rotate leaked credentials at the issuer

Further docs in the repository: SECURITY.md, privacy, threat model, redaction.

Develop

cargo fmt
cargo clippy --all-targets --all-features -- -D warnings
cargo test
cargo audit --deny warnings

CI matrix: test on Ubuntu, macOS and Windows; fmt / clippy on Ubuntu; release builds for x86_64-unknown-linux-gnu, aarch64-apple-darwin and x86_64-pc-windows-msvc; blocking cargo audit --deny warnings on Ubuntu.

Release history: Labs changelog and CHANGELOG.md.