What Kintsugi is, all the way down
The home page is the elevator pitch. This page is for the people who don't take "it's deterministic, trust us" for an answer — engineers, security folks, and anyone wiring Kintsugi into a real workflow. It walks the whole machine: how a command is read, why the block can't be talked out of, how untrusted input is tracked, what "reversible" actually promises, and — just as important — what Kintsugi cannot do.
The security spine
Everything else is built on four invariants that never bend. They're the reason a clever prompt can't turn the gate off:
How the gate reads a command
Substring matching is how scanners get fooled. Kintsugi parses real shell structure and takes the more cautious of two passes:
- A fast tokenizer for the common case, and
- a true bash AST parser (brush-parser, pure-Rust). The AST pass sees what text matching can't — commands hidden inside
$(…)/ backticks, here-documents fed to a shell, subshells, andif/for/whileblocks.
So both of these are caught, not waved through:
It fails toward caution: a line the parser can't fully understand is held, never assumed safe — and a parse failure can only add caution, never downgrade a catastrophic verdict. The hard guarantee, locked by a golden corpus, is zero catastrophic-classified-as-safe — verified at 0 / 176 dangerous commands across a MITRE ATT&CK + GTFOBins corpus.
The catastrophic categories map to the damage that actually matters: data destruction (rm -rf, DROP TABLE, git push --force, terraform destroy), disk/device writes (dd, mkfs), and secret reads (.env, ~/.ssh, ~/.aws, keychains).
Two tiers: deterministic rules, then an optional model
--features llama. Escalation-only: it can raise caution, never lower a rule's decision.Provenance & the lethal trifecta
The scariest failure isn't one bad command — it's a chain: an agent reads untrusted content, then reads a secret, then has a way to send data out. Any one leg is fine; all three together is how a prompt-injected agent exfiltrates your .env. Kintsugi tracks information flow to catch that combination deterministically.
.env, ~/.ssh, ~/.aws, keychains — a sensitive read in a tainted session.curl, wget, ssh, scp, git push, DNS tools — a way off the machine.All three present → the command is forced to the catastrophic floor and held. Taint is monotonic (it only ever adds caution; only an explicit policy reset clears it), durable (event-sourced and replayed on restart, so killing the daemon can't quietly clear it), and recorded by identifier only — a URL that smuggles a secret is redacted before it ever reaches the log.
Reversible by default
Before a destructive operation runs, Kintsugi snapshots the paths it will touch — copy-on-write reflinks where the filesystem supports them, a plain copy otherwise — so kintsugi undo (or undo --session) brings them back. A filesystem-watcher backstop records changes that slip past interception, so the audit trail and undo stay complete even for an agent in auto-approve mode.
The honest promise is nothing unrecoverable, not "transactional." An in-database DROP / TRUNCATE isn't a file — Kintsugi flags and records it, but recovery there is your database's PITR / backups. Unbounded targets (a glob, a device, /) may not be fully covered by a snapshot; the backstop is the net.
Where it sits — every agent, and your shell
Protection lives at the process / PATH layer, not inside any one tool, so anything that runs commands is covered. kintsugi init wires it all in one command:
- Native pre-tool hooks for Claude Code, Cursor, Codex, Qwen, Gemini, Copilot, OpenCode, and Google Antigravity.
- A
$PATHshim for rawbashshell-outs — even commands an agent runs without its own hook. - The
kintsugi-execMCP server for MCP-based agents. kintsugi guardforces the shim onto an agent's PATH so a "yolo" / auto-approve agent still hits the gate, and fail-closed makes an unreachable daemon block rather than run unguarded.
The managed posture
kintsugi init --enterprise adds the controls a shared or production host needs: a password lock (argon2id verifier + XChaCha20-Poly1305, one-time recovery key) so stopping, unhooking, or disabling Kintsugi requires the admin password — enforced daemon-side via a challenge-response (the password never crosses the socket) with brute-force lockout. An auto-restart watchdog relaunches a killed daemon within seconds; a passive recorder lands every human shell command on the same tamper-evident log for DBA/operator compliance. And a real Control Room — a native desktop app and a ratatui TUI — over the live log, with one-key approve/deny/undo.
An honest threat model
A safety tool that names its blind spots is one you can actually trust. Kintsugi is deliberate about what it is not:
- It is interception, not an unbypassable firewall. A tool invoked by absolute path, or a sufficiently clever escape, can dodge observation. The deterministic base rules still stand regardless — but coverage is "every surface we wire," not "every syscall."
- The lock defeats an agent or a non-root user — not root. The password lock turns a forced shutdown into a logged, recoverable event and stops an audited account from quietly disabling the gate. It does not stop a root adversary; that's a different threat class.
- Undo is a filesystem recoverer, not a transaction log. Files come back; in-database destruction needs your DB's backups.
Run kintsugi limits any time for the live version of this scope, straight from the binary.
Measured, not asserted
unsafe blocksEvery figure is reproduced by a committed test. The full adversarial stress + vulnerability assessment lives in the repo.
That's the whole machine.
Install is one command; it works immediately with no model and no setup beyond kintsugi init.