gensee-crate

Why Gensee Crate?

Gensee Crate helps you:

• Run risky agent work transactionally. Launch an agent in a disposable runtime, fork the full workspace for speculative changes, then merge, keep working, or discard the fork after review.
• Keep untrusted changes out of the main workspace. Summaries and diffs show what changed and what tests ran before a fork is allowed to merge back.
• Enforce policy before risky tools run. A deterministic, configurable policy can allow, ask, or deny secret reads, destructive ops, out-of-workspace writes, cloud-metadata access, control-plane writes, dangerous executable content, and more.
• Watch what your agent actually does. Capture prompts, tool calls, files read and written, commands run, packages touched, network targets reached, hook intent, alerts, and timeline context in one local store.
• Trace provenance across sessions. Lineage graphs link prompts, tool calls, filesystem effects, artifacts, alerts, and review verdicts so long-horizon safety issues such as memory poisoning, policy bypass, and data exfiltration can be understood and contained.
• Seamless integration with your current workflow. Run gensee watch beside an agent, launch an agent with gensee run, or use the tclone runtime for full-workspace fork, merge, and rollback flows. Manage policy with gensee policy and inspect activity in the local dashboard.

Preliminary Benchmark Results

Preliminary AgentCanary benchmark results show Gensee Crate improving defense rate across memory poisoning, long-horizon, and prompt-injection threat types with low runtime overhead.

Quick start

1. Install

One command installs Gensee Crate and checks or installs its command-line prerequisites on macOS. At the end, the installer can configure supported agent hooks for active safety policy enforcement, lets you choose GENSEE_HOME, and lets you keep the bundled default policy or create an editable local policy:

curl -fsSL https://raw.githubusercontent.com/GenseeAI/gensee-crate/main/scripts/install_oss.sh | bash

During an interactive install, choose the native dashboard prompt to provision its Tauri and frontend dependencies. For a non-interactive install, add GENSEE_CONFIGURE_DASHBOARD=1. This requires Node.js 18+; on Linux it also installs the WebKitGTK development packages required by Tauri.

For non-interactive installs that should configure Claude Code, Codex, and Antigravity hooks:

curl -fsSL https://raw.githubusercontent.com/GenseeAI/gensee-crate/main/scripts/install_oss.sh | GENSEE_CONFIGURE_CLAUDE=1 GENSEE_CONFIGURE_CODEX=1 GENSEE_CONFIGURE_ANTIGRAVITY=1 GENSEE_CONFIGURE_DASHBOARD=1 bash

To configure VS Code / GitHub Copilot hooks, use the VS Code toggle. VS Code also loads Claude-compatible hook settings; when both Gensee integrations are installed, Gensee suppresses an imported Claude invocation only after observing the matching native VS Code invocation for the same session, event, and tool:

curl -fsSL https://raw.githubusercontent.com/GenseeAI/gensee-crate/main/scripts/install_oss.sh | GENSEE_CONFIGURE_VSCODE=1 bash

Install platform prerequisites first.

On macOS:

xcode-select --install

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"

brew install jq

On Ubuntu/Debian Linux:

sudo apt update
sudo apt install -y build-essential pkg-config libssl-dev jq nftables git

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"

Build the CLI from source:

git clone https://github.com/GenseeAI/gensee-crate.git
cd gensee-crate
cargo build -p gensee-crate-cli

The binary is now at target/debug/gensee. For convenience, either add that directory to your PATH, or install gensee globally:

cargo install --path crate/gensee-crate-cli   # puts `gensee` on PATH

Gensee stores its local state under ~/.gensee by default. Set GENSEE_HOME to override it, and use the same GENSEE_HOME for watch, hooks, run, timeline, and the dashboard so the signals appear together. GENSEE_HOME is the Gensee data store, not the agent project/workspace folder:

export GENSEE_HOME="$HOME/.gensee"

For hook-based agents, there are two paths to keep straight:

• GENSEE_HOME: where Gensee records hooks, alerts, timelines, policies, and dashboard data. Use the same value across Claude Code, Codex, Antigravity, VS Code, Omnigent sidecars, gensee watch, gensee timeline, and the dashboard when you want one combined view.
• agent workspace/config path: where the agent looks for its hook settings. Claude Code uses ~/.claude/settings.json, Codex uses ~/.codex/hooks.json, Antigravity defaults to global ~/.gemini/config/hooks.json, and VS Code uses ~/.copilot/hooks/gensee.json. Antigravity also supports workspace-local .agents/hooks.json when you pass --hooks.

Avoid pointing GENSEE_HOME at the project workspace root. A repo-local store such as $PWD/.gensee-dev is convenient for development, while $HOME/.gensee-<agent> is better for long-running sidecars such as Omnigent so Gensee does not watch its own store writes.

The local store can include redacted prompts, commands, paths, policy alerts, and lineage data. Fresh telemetry stores are encrypted at rest by default with a local key in $GENSEE_HOME/gensee.key. Keep that key private and do not share it with store snapshots; sharing the key and store together gives readers access to the telemetry. Existing plaintext development stores remain readable rather than breaking hooks; move or remove the old GENSEE_HOME to start a fresh encrypted store. Set GENSEE_STORE_ENCRYPTION=0 only for local debugging stores.

• macOS and Linux for the stable v0.2 path. Linux host controls include /proc process attribution, fanotify sensitive-path enforcement, seccomp launcher profiles, and cgroup/nftables network controls.
• Claude Code, Codex, Antigravity, or VS Code / GitHub Copilot for hook-based enforcement. Other agents are planned.
• Rust toolchain (cargo) and jq.
• On Linux: build tools, pkg-config, OpenSSL headers, nftables, and git.

Install the required command-line tools on macOS:

xcode-select --install

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"

brew install jq

Install the required command-line tools on Ubuntu/Debian Linux:

sudo apt update
sudo apt install -y build-essential pkg-config libssl-dev jq nftables git

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"

To capture prompt/tool intent and enforce the safety policy, configure your agent's hooks to call the matching gensee hook endpoint. The installer offers Claude Code, Codex, Antigravity, Cursor, and opt-in VS Code setup. To run the setup step later for Claude Code:

gensee setup claude-code --gensee-home "$GENSEE_HOME"

If your team requires Claude Code traffic to pass through an inspecting LLM gateway, configure that during the same setup step:

gensee setup claude-code \
  --gensee-home "$GENSEE_HOME" \
  --anthropic-base-url https://llm-gateway.example.com \
  --anthropic-auth-token "$GATEWAY_TOKEN"

For local screening/blocking, start the bundled gateway and point Claude Code at it:

GENSEE_HOME="$GENSEE_HOME" \
GENSEE_BIN="$PWD/target/debug/gensee" \
GENSEE_GATEWAY_TOKEN="local-gateway-token" \
ANTHROPIC_UPSTREAM_API_KEY="$ANTHROPIC_API_KEY" \
node scripts/anthropic_gateway.mjs

./ta