kit

Why I built it

I build most things with AI agents now. The same friction kept showing up at the start of every project: API keys scattered across .env files, shell history and chat windows, secrets on the loose. Logins expired. Half the tools weren't installed. And every fresh agent session re-asked the same setup questions, burning tokens to rediscover what the last session already knew.

So I wanted one command that takes a repo from git clone to a working, secret-safe environment, the same way for a human at a new laptop or an agent in a fresh sandbox. Declarative config, real vaults instead of loose keys, a security baseline that doesn't depend on remembering to run it, and a deterministic tool that makes no model calls of its own, so it never leaks a key or bills you to think.

The bet: the boring, security-critical setup should be deterministic and auditable, and the intelligence should stay where you put it, not baked into the tool that holds your secrets.

What it does

Memory

Memory is the moat. The model is becoming a commodity; the system around it is not. kit memory gives a (swappable) model a verifiable second brain: it stores your raw conversation history and searches it before answering, so it pulls receipts instead of guessing. SQLite + FTS5, three hooks, no vectors, no model calls. It indexes transcripts from twelve coding agents (Claude Code, Codex, Gemini, Continue, Cursor, Amazon Q, AWS Kiro, Factory Droid, Aider, Antigravity, Cline and OpenCode), each parsed against the agent's own serialization format, never guessed.

A personal tier stays private, with an encrypted backup so a stolen laptop does not lose your context. A curated, area-organized shared tier travels with the repo and is reviewed like code. Governed cross-device memory lets kit memory push / pull sync your private store over your own encrypted transport — a private git remote or a command transport (S3/rclone/scp/USB), gzip-compressed inside AES-256-GCM, opt-in, no cloud ledger. In public-key mode (X25519) an ephemeral session pushes with no secret — just a public recipient string — so a throwaway container contributes its memory and nothing secret leaves it. And kit memory learn mines the store for instructions you keep re-typing, so you can turn them into a rule. Read the guide.

# index your history, then search it before you answer
$ kit memory install && kit memory index
$ kit memory search "what did we decide about X"
# zero-LLM core: pipe a review prompt to YOUR own model
$ kit memory suggest | your-llm
# sync across machines — public-key mode pushes with no secret
$ kit memory keygen && kit memory sync init --remote git@github.com:you/kit-memory.git
$ kit memory push   # from one machine
$ kit memory pull   # on another
# surface instructions you keep re-typing → make it a rule
$ kit memory learn

Context lock

Many accounts, many windows, many projects. A logged-in account and a selected project are not assumed to belong together, that assumption is how a deploy lands in the wrong org. Declare the exact account + project per repo in .kit.toml and kit verifies the live tools against it: a right account with the wrong project is a mismatch, not a pass.

# verify every CLI is on the declared account + project
$ kit context check
# activate the declared context (gcloud config + repo git identity)
$ kit context use
# block a push to the wrong org before it leaves the machine
$ kit hooks add context-check

Context pointers are non-secret and live in config; the credentials they authenticate with stay in the vault.

Where kit fits

The agent stack has layers. kit sits at the governance floor, deterministic, local-first, model-agnostic. Everything above stays swappable; the security-critical setup underneath doesn't move, and since 2.0 it is a floor you can prove (signed attestation, scanner-health gate) and build on (frozen, versioned contracts).

Not another scanner

You already have Semgrep, Snyk, Trivy, Grype. kit does not compete with them: it runs them, folds in their findings, and adds the layer they lack. One command from git clone to a working, secret-safe environment, and the single deterministic gate your agent runs before it acts. Zero LLM, local-first, no telemetry. Use kit with your scanners, not instead of them.

And since 2.0 it proves it ran them: a crashed or missing scanner fails the gate instead of passing green, a signed kit check --attest receipt records which scanners actually ran, and kit coverage maps that to OWASP ASVS L2, OWASP LLM Top 10, NIST SSDF, and the OWASP Agentic & MCP Top 10 as toggleable evidence maps (an evidence source for a GRC tool, never a compliance claim).

One audit, one verdict

kit review runs the four gates — environment + security (check), a11y and design tokens (design), code standards (standards), and architecture decisions (adr) — and returns one structured report: { ok, failed, stages }, exit 1 on red. The agent-facing kit_review MCP tool serializes the same report from the same core, so the CLI and the agent surface can never disagree about what ran or what green means. concise: true trims pass/skip rows for context economy — per-stage counts keep the totals honest, nothing is silently truncated.

# the one gate an agent runs before it acts — human-readable or structured
$ kit review
$ kit review --json   # { ok, failed, stages: check · design · standards · adr }

Your standards, not ours

kit ships zero opinions about your architecture, your framework choices, or your taste. There is no bundled ruleset to inherit and no vendor's "best practice" to adopt — the usual reason standards tooling feels like someone else's rules. You declare the standard: thresholds in .kit.toml, your own rules as standards plugins, architecture decisions (monolith vs. services, caching strategy, your React setup) as ADRs with kit-enforce blocks. kit enforces the declaration deterministically — and proves the checks ran.

Taste is allowed to change. An ADR is superseded, not deleted — the decision, its date, and its why stay in history while the gate moves with you. And the baseline keeps day one honest: kit baseline freeze snapshots today's findings so gates trip only on net-new ones — no wall of legacy findings shaming a real repo into ignoring the tool.

# your architecture decisions as enforced gates — cited back to the ADR
$ kit adr check
✓ 3 enforced ADR(s) — no new violations
# taste changed in 2027? supersede the ADR — history keeps the why

Adopt with one pasted line

Paste one line into the repo's CLAUDE.md / AGENTS.md and the next agent session bootstraps kit itself — install, kit init, kit check — and asks the human only for what is genuinely theirs (interactive logins, suggested as commands you run yourself).

# the line you paste (before)
This project uses kit (github.com/sandstream/kit). If `kit` is missing:
`npm i -g sandstream-kit`, then `kit init`. Start every session with
`kit check` and act on its verdict; `kit <command> --help` self-documents.

Transparent end state: you should know exactly what a pasted line turns into. When the bootstrap completes, the rules file contains this managed block — visible BEGIN/END markers, idempotent, nothing outside them touched — and a drift test in kit's own CI pins the documented block to what the code actually writes:

<!-- BEGIN kit (managed block — edit outside the markers, not inside) -->
## kit
This repo is managed by kit (env, secrets, security gates). Hooks enforce
the hard rules; what you need to know:
- Start: `kit check` — on `fail`, run `kit fix`, then re-check.
- Prior decisions: `kit memory search "<query>"` (cross-session, cross-agent).
- Secrets: `kit secrets` (vault-backed); placeholders in `.env.example`, never plaintext in `.env*`.
- Un-gated deps (git repos, URLs, vendored code): `kit triage repo <target>` first.
- After a batch of edits: `kit check --category security`; halt on `fail`.
- Everything else: `kit --help` — the commands are self-documenting.
<!-- END kit -->

The block is an index, not an encyclopedia — every agent turn pays for these tokens, so anything a hook already enforces deterministically carries zero prose. The first install is your trust root (kit cannot triage its own bootstrap): releases carry SLSA provenance and cosign-signed images — verify before you paste the line into an org template.

Why deterministic

kit check and kit triage give the same result every run. The tool makes no model calls of its own: triage delegates to an external Python skill the operator configures, and adapters configure Claude Code / Codex / MCP, they don't invoke models. LLM-augmented triage is available as explicit opt-in, you bring the key.

Why: smaller attack surface. No vendor API key baked into kit. No token cost from running kit check. No vendor lock. The tool stays a tool; intelligence stays where you put it.

kit 5: a portable, fail-closed governance layer for the agent loop

5.0 takes kit from a point-in-time verifier to a continuous, portable, fail-closed governance layer for the agent loop. Four pillars land — hardware-rooted identity, an offline control plane, one exec-broker, and a traveling profile — all additive over 4.x (no stable command removed, enforced by a public-surface invariant). The 4.0 promise still holds underneath: a check that could not run fails the gate — green means every check actually ran (no false green).

It sits on everything before it: the provable local floor (signed attestation, scanner-health gate, provable air-gap) from 2.x, the org-governed control plane and governed cross-device memory from 3.x, and strict-by-default gating from 4.0 — now unified so the CLI gates, the MCP runtime, and kit doctor all read one signed decision.

Proven against the real world: 198 repos + a red-team

We pointed kit at 198 real repositories — the 100 most-used apps and libraries on GitHub across 15+ language ecosystems, then a fresh, harder 98 as a validation set — running kit init + kit check on each with fully isolated per-repo state, and recording every result to raw per-repo data. Across the 100-repo compatibility set: 0 crashes, 0 init errors, including monorepos at linux / next.js / elasticsearch / flutter scale. Scored against each repo's primary implementation language, kit 5.0.0 correctly identifies the stack on 187 of the 198 (reproduced in CI, not a one-off). The misses are documented edge cases — a compiler written in C++ (swift, julia), a Go+TypeScript monorepo (grafana), and a couple where GitHub's own language label is the odd one out — the analysis that motivated the Linguist-style source-byte census shipping in 5.0.

In parallel, a 14-probe adversarial battery attacked kit's core promise — no false green: scan-result poisoning, baseline-whitelisting of findings, symlinked findings files, a fully weaponized "green machine" repo, malicious-package triage. On every false-green attack kit stayed red / fail-closed. The red-team did find three real defects — a malformed baseline or .kit.toml could crash the gate, and one check was non-deterministic — every one a denial-of-verdict, not a false green, and all three were fixed with regression tests before release. Honest limits are documented too: manifest-based detection has documented misses on polyglot repos, and the degraded no-trufflehog secret path has known gaps.

What the floor found

Robustness is one thing; what the checks actually surface is another. Pointed at that same corpus with kit check --category security (kit 5.0.0, one command per repo, no model calls), 197 repositories returned results. The headline is how quiet it was.

Known-vulnerable dependencies

Across the repos that commit a lockfile, npm audit reported this severity spread (summed):

■ 67 critical   ■ 122 high   ■ 108 moderate   ■ 14 low

With open network egress, osv-scanner resolved deeper across Go, Rust, Python and the JVM: 9,054 advisory IDs across 2,711 packages in 117 of the repos.

Secrets: counted, never named

121 repos carried secret-shaped strings in git history, almost entirely test fixtures and example connection strings, with zero verified-live. The two verified-live hits were vendored third-party test fixtures, not the projects' own credentials. Per responsible disclosure we report only the count: anything that could be a real leak goes privately to the maintainer first and is never named here.

Method: shallow clone → kit init --no-setup → kit check --category security → osv-scanner → npm audit, kit 5.0.0, run 2026-07. Machine-local checks excluded; clones deleted after each repo. Raw per-repo data is kept in a private research repository.

Integrations

kit's modules are pluggable, this is where it meets the outside world while the core stays deterministic. Secrets resolve from 12 secret backends (8 writable vaults + read-only sources); services and deploy targets provision through first-class adapters / plugins.

Writable vaults: 1Password · Infisical · HashiCorp Vault · AWS Secrets Manager · GCP Secret Manager · Azure Key Vault · Doppler · dotenvx
Read-only sources: Bitwarden · EAS · config · env

Services & deploy: Stripe · Supabase · Clerk · Vercel · Neon · PlanetScale · Upstash · Cloudflare · Fly.io · Railway · Sentry · Resend · Loops · PostHog · Tinybird · Inngest · Trigger.dev · Liveblocks · Flagsmith · Expo EAS · SearXNG · GitHub · Snyk · Wiz

What kit provides

The governance-floor capabilities kit ships out of the box — the parts a plain setup tool typically leaves to you, omits, or can't prove. Every row is a claim you can verify against the CLI, not a comparison against an unnamed competitor.

Quick example

# 1. clone a project
$ git clone git@github.com:you/your-app.git
$ cd your-app

# 2. one-shot bootstrap
$ kit setup
  → detects stack (Next.js + Supabase + Stripe)
  → installs node@22, pnpm, supabase-cli
  → logs into 1Password
  → materializes 14 secrets from op://Development/...
  → installs pre-commit + post-merge hooks
  → runs full security baseline

# 3. work normally, agents + humans both go
$ pnpm dev

Core commands

The commands you'll actually run, grouped by what you're doing. Every command is stable unless noted; kit <cmd> --help shows the full surface, and kit config knobs lists every power-user setting.

Get it

npx sandstream-kit setup

npm i -g sandstream-kit

docker run --rm -v "$PWD":/work -w /work sandstream/kit check

git clone github.com/sandstream/kit

Prereqs: Node 22+, git, and mise for installing tools (brew install mise on macOS, or curl https://mise.run | sh on Linux / Windows). The one-shot npx path needs no global install. The Docker image is a signed, multi-arch OCI image (version + latest tags) — verify it before you trust it:

# every release is keyless-signed (cosign) + ships a CycloneDX SBOM
$ cosign verify sandstream/kit:latest \
    --certificate-identity-regexp 'https://github.com/sandstream/kit/\.github/workflows/docker-build\.yml@.*' \
    --certificate-oidc-issuer https://token.actions.githubusercontent.com

# then, in a repo
$ kit init      # detect stack → .kit.toml
$ kit check     # what's set up vs missing
$ kit setup     # install tools, hooks, logins, secrets
$ kit context check  # lock each CLI to the right account + project

Documentation

Everything is in the repo. Read up before you wire it in.

FAQ

What is kit?

kit is a deterministic, local-first developer-environment manager for AI agents and humans. One command takes a repo from git clone to a working dev environment: it installs and pins tools, runs guided logins, materializes secrets from your vault, and wires agent config.

Does kit replace Semgrep, Snyk, or Trivy?

No — kit is not another scanner. It orchestrates and normalizes the scanners you already use (Semgrep, Snyk, Trivy, Grype, osv-scanner, plus opt-in GuardDog malware detection and its own supply-chain checks) into one deterministic gate with cited findings. Cloud-only tools like Socket that can't run air-gapped surface as an honest skip, never a false green. It does not rebuild SAST.

How is kit agent-native?

The core is deterministic and local — no LLM. kit externalizes agent state: a cross-harness memory store (Claude Code, Codex, Gemini, Cursor, …) and a per-CLI context lock that verifies each tool points at the right account and project, so you can switch agents without losing context or contaminating environments.

Does kit impose a coding standard?

No. kit ships zero opinions — you declare your standards (config thresholds, your own plugin rules, architecture decisions as ADRs with enforce blocks) and kit enforces the declaration deterministically, then proves the checks ran. Taste can change: supersede the ADR, and history keeps the why.

Is kit free and open source?

Yes. kit is MIT-licensed, published to npm as sandstream-kit with SLSA provenance, requires Node 22+, and sends zero telemetry.