Sentience Governor — Documentation
Local-first governance for AI agents. Connect Claude Code, run sentience pulse, and get a shareable report of agent actions, tool calls, intent drift, policy violations, and per-turn token burn.
Installs from PyPI with one command. No account required. Nothing is sent automatically.
Start here (2 minutes)
Section titled “Start here (2 minutes)”- Install →
pipx install sentience-governor - Wire Claude Code →
sentience init claude-code - Run Claude Code normally
- Inspect the session → type
/sentience-pulseinside Claude Code, or runsentience pulse --latestin a terminal
Inside Claude Code, type /sentience-help or /sentience-pulse — sentience init claude-code installs the Claude Code skills for you (new in 0.2.8). See Quickstart.
Everything else can wait.
What you get after a run
Section titled “What you get after a run”Sentience turns an agent session into a local pulse:
- What the agent did
- Which tools ran, and which kinds of work rode the expensive turns
- Where it drifted from declared intent
- Which policy rules fired
- Which turns carried the most token/context burn
- What deserves inspection before you trust the output
Token burn means token/context footprint, not dollar cost.
Definitions
Section titled “Definitions”Session = one run of an agent Event = one action inside a session Trace = all events for a session
Where to go
Section titled “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.
- Cloud telemetry sunset — what changed in v0.2.8.3 and what remains local.
- Troubleshooting — common issues and their fixes.
- Changelog — what changed, and when.
CLI tools you get
Section titled “CLI tools you get”sentience→ view agent sessions and runpulsesentience-cli→ raw trace viewersentience-sync→ sunset stub for the removed Sync cloud telemetry CLIsentience-claude-code-hook→ Claude Code hook entry pointsentience-mcp-server→ the opt-in MCP server (new in 0.3.0); install withpip install "sentience-governor[mcp]"
A governance runtime
Section titled “A governance runtime”Sentience wraps your agent at the execution boundary with five control points:
AGENT_REGISTERED, INTENT_DECLARED, SCOPE_ASSERTED, CONTEXT_SNAPSHOT, MEMORY_WRITE_ATTEMPT.
It emits a structured event at each control point. Each event is evaluated against five default policy rules. Violations are annotated with the consequence real-time enforcement would apply — enforcement itself is planned for a future paid tier.
Nothing gets blocked. Everything is visible.
Claude Code support
Section titled “Claude Code support”For Claude Code, sentience init claude-code wires the local hook into your project and installs six /sentience-* skills. The hook observes tool calls, records governance events, and captures per-turn token burn from the session transcript.
That lets sentience pulse connect tool activity, policy signals, intent drift, and token burn in one report. Inside Claude Code, /sentience-pulse renders that report inline without switching to a terminal.
Governance Claude can call (new in 0.3.0). sentience init claude-code --mcp additionally registers an opt-in MCP server so Claude can call Sentience governance tools directly inside a session: read the methodology, read the last completed session’s pulse / intent / violations, read the current session’s structural status, and declare_intent (state the objective and scope it is working within, so subsequent matching activity stops flagging POL-001). Opt-in, stdio, local. See Commands.
The in-chat commands are operator-invoked, latest-session only, and read-only.
Trace files
Section titled “Trace files”Claude Code session traces land at ~/.sentience/traces/claude-code/. You can read, grep, diff, replay, or feed them into your own analysis.
Sync CLI
Section titled “Sync CLI”sentience-sync is a sunset stub for the removed Sync cloud telemetry CLI. See Cloud telemetry sunset.
The philosophy
Section titled “The philosophy”- Observe-only.
- Fail-open.
- No automatic network calls.
Who it is for
Section titled “Who it is for”- Claude Code users who want a local flight recorder for agent sessions.
- Operators running AI agents who need an audit trail.
- Teams adopting MCP or LangChain who need structured logs of tool-call behavior.
- Developers evaluating governance who want to see the open-tier surface before enforcement.
What the open tier does not do
Section titled “What the open tier does not do”Real enforcement — block, pause, scope contraction, retroactive revocation — is planned for a future paid tier. 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.
Stuck? → Troubleshooting