gensee-crate

Why Gensee Crate?

Gensee Crate helps you:

• Watch what your agent actually does. Capture files read and written, commands run, network targets reached, hook intent, alerts, and timeline context in one local store.
• Enforce policy before risky tools run. Enforces a deterministic, configurable policy that can allow, ask, or deny secret reads, destructive ops, out-of-workspace writes, cloud-metadata access, control-plane writes, dangerous executable content, and more.
• 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 and data exfiltration can be prevented in time and examined afterward.
• Seamless integration with your current workflow. Run gensee watch beside an agent or launch an agent in a sandbox with gensee run with additional safety. 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

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

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

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, and timeline so the signals appear together:

export GENSEE_HOME="$HOME/.gensee"

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. v0.1 supports macOS only; Linux and Windows support are planned.
• Claude Code or Codex for hook-based enforcement. Other agents are planned.
• Rust toolchain (cargo) and jq.

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

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 to do this for you. To run the setup step later for Claude Code:

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

Or for Codex:

gensee setup codex --gensee-home "$GENSEE_HOME"

If you are running from a source checkout instead of an installed binary:

./target/debug/gensee setup claude-code --gensee-home "$GENSEE_HOME"
./target/debug/gensee setup codex --gensee-home "$GENSEE_HOME"

The setup commands back up the previous hook settings, update ~/.claude/settings.json or ~/.codex/hooks.json, and use the absolute path to the gensee binary you invoked. Fully restart Claude Code after configuring Claude Code hooks. Open /hooks in Codex to review and trust the hook command before testing enforcement. Full manual config and what gets recorded (plus redaction details) are in docs/claude-code-hooks.md and docs/codex-support.md.

Rerun the installer to update gensee in place:

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

If you installed from a source checkout, pull the latest changes and reinstall:

git pull --ff-only
cargo install --path crate/gensee-crate-cli --force

2. Run

Gensee has three protection levels you can combine:

• Hooks only: Agent requests and tool calling are checked and protected by the safety policy rules. Require agent hook installation (part of Step 1 above). No running commands needed.

• gensee watch: performs system-level event watching such as file system operations, macOS EndpointSecurityLogger events, etc. On macOS, --system-events eslogger needs Full Disk Access for the host app and sudo so it can create an EndpointSecurity client.

gensee watch # optional flags: --workspace --watch-root --duration-seconds --system-events

If you use --system-events eslogger on macOS, open Apple menu > System Settings > Privacy & Security > Full Disk Access, click +, add the app hosting gensee (for example Terminal, iTerm, or Visual Studio Code), then quit and reopen that app. Run the command with sudo as well.

• gensee run: adds managed macOS sandbox confinement and staged, reviewable workspace writes around the launched agent.

gensee run -- claude # or: gensee run -- codex

Inspect what happened at any time:

gensee run list   # list guarded run sessions and staged workspaces
gensee timeline   # show prompts, tool intent, file effects, and policy decisions

See docs/watch.md and docs/run-and-sandbox.md for the full options.

3. Open the dashboard

The local dashboard reads the same GENSEE_HOME store as watch, hooks, and timeline. It shows live agent activity, policy decisions, alerts, file and request lineage, and the active policy document; users can record review verdicts and edit validated policy settings from the browser.

Launch it from the repository checkout against your active store:

cd /path/to/agent-shield
GENSEE_HOME="$PWD/.gensee-dev" npm --prefix "$PWD/dashboards/web" run dev
# open http://localhost:5173

If you launch it from another directory, use absolute paths and the same GENSEE_HOME that your hooks or gensee watch use:

REPO=/path/to/agent-shield
GENSEE_HOME="$REPO/.gensee-dev" npm --prefix "$REPO/dashboards/web" run dev

See dashboards/web/README.md for requirements, demo data, and policy editing notes.

The activity view brings policy decisions, timeline filtering, event details, and command/tool context into one local browser surface.

The lineage view links derived artifacts and shows the facts behind each path, including current risk state and the policy/query context used to inspect it.

The multi-turn view highlights long-horizon patterns across a session, including read-to-exfiltration chains, memory-poison signals, repeated artifact targeting, and policy decision