Troubleshooting

Quick checks (try these first)

sentience status
sentience list
sentience open --latest

Most common issue

Hook not firing → check PATH or restart Claude Code.

---

Install

pip install sentience-governor fails with externally-managed-environment

Modern macOS and Linux Pythons block pip install outside a virtualenv (PEP 668). Use pipx instead:

pipx install sentience-governor

pipx install fails with ensurepip exit status 1

pipx defaulted to a Python with a broken ensurepip. Force a known-good version:

PIPX_DEFAULT_PYTHON=python3.12 pipx install sentience-governor

pipx is not installed

brew install pipx          # macOS
# or:
python3 -m pip install --user pipx   # Linux / WSL
pipx ensurepath

Restart your shell after pipx ensurepath.

sentience: command not found after install

Run pipx ensurepath, then restart your shell. The pipx bin directory needs to be on your $PATH.

Python version too old

Sentience Governor requires Python 3.10 or newer. Confirm with python3 --version. If older, install a newer Python (brew install python@3.12).

---

Claude Code hook

sentience status says hook is not firing

Cause: One of: wrong settings file, CLI not on PATH, Claude Code started before you saved the config, or no tool calls happened in the session.

Fix:

1. Confirm config location: ~/.claude/settings.json (user-global) or .claude/settings.json (project-local, takes precedence).
2. Confirm CLI resolves: which sentience-claude-code-hook from Claude Code’s launch shell.
3. Restart Claude Code — it reads settings at startup.
4. Make actual tool calls — the hook only fires on tool invocations.

sentience open --latest shows no events, but the hook fired

Cause: The curated viewer is hiding baseline-noise events in --summary mode.

Fix:

sentience-cli ~/.sentience/traces/claude-code/<session-id>.jsonl
# Or drop --summary:
sentience open <id>

---

Sentience Sync — registration

register requires --email and --name

Cause: Sync is an opt-in communication channel; contact info is how we reach you.

Fix:

sentience-sync register --email you@example.com --name "Your Name"

Not registered / Registration incomplete (exit code 3)

Two subcases. The CLI prints a different message for each.

Subcase A — never registered:

sentience-sync: Not registered. Run 'sentience-sync register --email ... --name ...' first.

Cause: No state file. First-time use.

Fix:

sentience-sync register --email you@example.com --name "Your Name"

Subcase B — incomplete or outdated:

sentience-sync: Registration incomplete or outdated. Run 'sentience-sync register --email ... --name ...' again.

Cause: Local state has an installation_id but no installation_secret — either upgrading from pre-0.2.0, state hand-edited, or secret cleared server-side.

Fix:

sentience-sync register --email you@example.com --name "Your Name"

Your installation_id is preserved. Only the secret refreshes.

Authorization failed

Cause: Server had your bearer token but something changed (state file deleted, support rotated the server-side hash).

Fix:

sentience-sync register --email you@example.com --name "Your Name"

Re-register refreshes the secret. No duplicate installations.

register times out

Cause: Cold-start on the Lambda (3–6s). Default CLI timeout is 5s.

Fix:

SENTIENCE_SYNC_TIMEOUT_SECONDS=15 sentience-sync register --email you@example.com --name "You"

Or edit ~/.sentience/sync-config.json:

{
  "timeout_seconds": 15
}

---

Sentience Sync — run

”Already uploaded for this window”

Cause: Server already has this (installation_id, window_start, window_end) tuple.

Fix: Not an error — exits 0. Common from cron overlaps or manual re-runs.

Run claims 0 events even though my agent has been active

Cause: Either log_sources points at wrong path, or the agent isn’t writing events.

Fix:

sentience-sync status                         # verify config paths
ls -la /path/to/your/log.jsonl                # file exists?
wc -l /path/to/your/log.jsonl                 # has content?
head -1 /path/to/your/log.jsonl | python3 -m json.tool  # valid NDJSON?

Run shows 0 Claude Code events specifically

Cause: Claude Code’s default sink writes one file per session to ~/.sentience/traces/claude-code/<session_id>.jsonl. Sync’s log_sources takes static paths — per-session files aren’t picked up.

Fix: Set the hook to unified-file mode and point log_sources at it.

export SENTIENCE_CLAUDE_CODE_SINK_PATH=/var/log/sentience/claude-code-unified.jsonl

Restart Claude Code. Then add the path to log_sources in ~/.sentience/sync-config.json. Every new session appends to that one file.

Network error on run

Cause: Network down, firewall blocking outbound HTTPS, cold-start timeout, or Sentience Cloud down.

Fix:

sentience-sync run --dry-run    # confirms local aggregation works

If dry-run works, the network is the only thing left to investigate. For cold-start: see the timeout section above.

”Server rejected upload” (exit code 4)

Cause: Server returned non-2xx. Payload malformed, auth issue, or transient server problem.

Fix:

• 401 → see Authorization failed above.
• 400 → payload mismatch. pip install --upgrade sentience-governor.
• 5xx → wait a few minutes; retry.

---

Sync state and local storage

Permission denied on ~/.sentience/sync-state.json

Cause: File copied from another user with different ownership.

Fix:

ls -l ~/.sentience/sync-state.json        # check owner + perms
chown $USER ~/.sentience/sync-state.json
chmod 600 ~/.sentience/sync-state.json

State file perms warning on Windows

Cause: Windows file-permission model doesn’t always match POSIX 0600 cleanly.

Fix: Not a functional failure. State was saved; only the extra hardening didn’t stick — your installation_secret is still stored.

Starting over

Cause: Corrupted state, or you want a clean install.

Fix:

rm -rf ~/.sentience/
sentience-sync init
sentience-sync register --email you@example.com --name "Your Name"

Your server-side row from the previous installation_id remains until you contact support to remove it.

---

Claude Code vs. library-integrated — which viewer?

• Claude Code sessions → sentience (curated).
• MCP wrapper / LangChain callback → sentience-cli (raw).

---

Still stuck?

Reach out via support on getsentience.ai.

Include:

• The exact CLI command that failed
• Full stderr output
• sentience-sync status --json output (safe to share)
• OS and Python version

---

Stuck? → Troubleshooting