Sentience Governor — Documentation

See exactly what your AI agents did, why they did it, and where they crossed boundaries — in real time.

Installs from PyPI with one command. No account required.

Start here (2 minutes)

Install → pip install sentience-governor
Run → Quickstart
See your first trace

Everything else can wait.

Definitions

Session = one run of an agent Event = one action inside a session Trace = all events for a session

Where to go

Install — get the CLI on your machine.
Quickstart — from zero to your first trace in three minutes.
Commands — reference for every CLI command.
Sync privacy — what Sentience Sync sends, and what it does not.
Troubleshooting — common issues and their fixes.
Changelog — what changed, and when.

CLI tools you get

sentience → view agent sessions (start here)
sentience-cli → raw trace viewer
sentience-sync → optional cloud sync
sentience-claude-code-hook → auto hook (Claude Code)

A governance runtime

Wraps your agent with five control points: AGENT_REGISTERED, INTENT_DECLARED, SCOPE_ASSERTED, CONTEXT_SNAPSHOT, MEMORY_WRITE_ATTEMPT.

Emits a structured event at each control point. Each event is evaluated against five default policy rules; violations are annotated with the consequence the paid control plane would have applied.

Nothing gets blocked. Everything is visible.

Trace files

Per-session traces land at ~/.sentience/traces/. You can read, grep, diff, replay, or feed them into your own analysis.

Sync CLI

Send aggregated counts — not raw events — to Sentience Cloud. Manual, explicit, opt-in.

One run at a time. Never automatic.

The philosophy

Observe-only.
Fail-open.
No automatic network calls.

Who it is for

Operators running production AI agents who need an audit trail.
Teams adopting MCP or LangChain who need structured logs of tool-call behaviour.
Claude Code users who want a record of every editor tool invocation with four lines of config.
Developers evaluating governance who want to see what the open-tier surface looks like.

What the open tier does not do

Real enforcement — block, pause, scope contraction, retroactive revocation — is a paid control-plane capability. The open tier is the observability half of the same architecture.

The upgrade path is additive. Adopting open-tier today puts you on the path to full enforcement later.

Install →

Stuck? → Troubleshooting

Testing a pre-release or early-access build? Install instructions are here.