claude-sentinel

Local-first observability, policy, and audit tooling for Claude Code workspaces.

claude-sentinel exists to capture Claude Code hook activity into a project-local SQLite database, evaluate policy signals, expose live runtime state over HTTP and MCP, and keep packaged skill metadata available to operator tooling without requiring a hosted backend.

Why it exists

Claude Code workflows can be difficult to inspect after the fact. claude-sentinel adds a local runtime that helps you:

• capture hook events into a workspace-scoped audit trail
• inspect sessions, execution trees, metrics, and policy hits
• expose the runtime through an MCP server for Claude-aware integrations
• preserve governed skill metadata shipped in .claude/ and ai/skills/

The current runtime model is project-scoped. Running claude-sentinel init prepares the active workspace under .claude/sentinel/.

Package contents published to npm

The npm package is intentionally limited by package.json to the runtime artifacts needed for execution:

• dist/
• migrations/
• .claude/AGENTS.md
• .claude/skill-registry.md
• .claude/skills/
• ai/skills/

Because the package already uses the whitelist in package.json, an .npmignore file is not needed for publish readiness.

Requirements

• Node.js >=18.0.0 as declared in package.json
• npm for install and publish workflows
• a local environment that can install better-sqlite3

Native dependency note

claude-sentinel depends on better-sqlite3, which is a native module. Prebuilt binaries often cover common platforms, but some environments may still require native compilation support during install. If your install falls back to building from source, you may need:

• Python and C/C++ build tooling appropriate for your platform
• on Windows, Visual Studio Build Tools or an equivalent native toolchain

If npm install fails while building better-sqlite3, fix the native toolchain first and retry the package install.

Installation

Global CLI install

npm install -g claude-sentinel

One-off usage with npx

npx claude-sentinel help

Local development install from source

npm install
npm run build

Quick start

From the workspace you want to observe:

claude-sentinel init
claude-sentinel start
claude-sentinel doctor

What those commands do:

• claude-sentinel init creates the project runtime directories under .claude/sentinel/, prepares ignore entries, and configures inline hooks when not plugin-managed
• claude-sentinel start launches the local HTTP runtime API on 4242 and the packaged browser UI on 4243
• claude-sentinel doctor validates runtime home, database access, hook registration, process status, startup logging, the runtime API health endpoint at http://127.0.0.1:4242/api/health, and the UI health endpoint at http://127.0.0.1:4243/api/health

After startup, the packaged runtime exposes the local API at http://127.0.0.1:4242 through src/server/index.ts and serves the packaged Next browser UI at http://127.0.0.1:4243 from the published standalone build artifacts.

Public commands exposed by the package

The package exposes these npm bin commands through package.json:

| Command | Purpose | |---|---| | claude-sentinel | Main CLI for workspace initialization, lifecycle, diagnostics, and MCP helper startup | | sentinel-hook | Low-level hook entrypoint used by Claude hook integration | | sentinel-worker | Worker/flusher entrypoint | | sentinel-server | HTTP runtime server entrypoint | | sentinel-mcp | Standalone MCP stdio server entrypoint |

For most users, only claude-sentinel is the intended direct entrypoint. The other commands are primarily runtime plumbing and advanced integration surfaces.

CLI usage

claude-sentinel currently supports these commands:

| Command | Description | |---|---| | claude-sentinel init | Prepare the current workspace runtime and hook configuration | | claude-sentinel start | Start the local runtime API and packaged browser UI for the current workspace | | claude-sentinel status | Show whether the current workspace runtime API and browser UI are running | | claude-sentinel stop | Stop the current workspace runtime API and browser UI | | claude-sentinel doctor | Run health and configuration checks for both services | | claude-sentinel mcp-server | Launch the MCP server via the main CLI | | claude-sentinel help | Print command help |

Examples

Initialize and start Sentinel for the current project:

claude-sentinel init
claude-sentinel start

Check runtime status:

claude-sentinel status

Stop the runtime:

claude-sentinel stop

Run diagnostics:

claude-sentinel doctor

Start the MCP server directly:

sentinel-mcp

Or through the main CLI:

claude-sentinel mcp-server

MCP usage

The package includes MCP metadata in package.json and a stdio server implementation in src/mcp/index.ts.

Direct MCP command

sentinel-mcp

Package MCP metadata

Package consumers that read npm MCP metadata can resolve the server as:

• command: node
• args: dist/mcp/index.js

MCP tools currently exposed

src/mcp/tools.ts defines the current public MCP tool surface:

• get_skill_system_summary
• get_skill_definition
• recommend_skill_route
• execute_skill_control_plane
• get_recent_events
• search_audit_log
• execute_sentinel_command
• get_active_sessions
• get_execution_tree
• get_policy_violations
• get_audit_decisions
• get_metrics

Claude Code plugin-managed flow

If you are using the Claude Code plugin packaging documented in plugin/README.md, the plugin can register hooks and the MCP server without mutating .claude/settings.json. In that mode, claude-sentinel init detects CLAUDE_PLUGIN_ROOT and skips inline hook mutation.

HTTP runtime surface

The local runtime server in src/server/index.ts exposes endpoints including:

• GET /api/health
• GET /api/stream
• GET /api/events/recent
• GET /api/sessions
• GET /api/tree/:sessionId
• GET /api/metrics/summary
• GET /api/search
• GET /api/projects
• GET /api/policies
• GET /api/policy-hits
• GET /api/decisions
• GET /api/skill-system

The packaged local runtime API defaults to port 4242 through DEFAULT_PORT. The packaged Next UI uses port 4243, matching ui/package.json, and is built into the published package during npm run build.

Configuration summary

The public configuration surface is intentionally small and mostly environment-variable based.

Workspace resolution

• CLAUDE_PROJECT_DIR or CLAUDE_PROJECT_PATH: overrides the workspace path resolved by resolveProjectPath()

Plugin-managed execution

• CLAUDE_PLUGIN_ROOT: signals plugin-managed installation to isPluginManagedInstall()
• CLAUDE_PLUGIN_DATA: alternate plugin data directory used by sentinel-hook

Retention settings

• SENTINEL_RETENTION_DAYS: overrides event retention days in getDefaultConfig()
• SENTINEL_ARCHIVE_RETENTION_DAYS: overrides archive retention days in getDefaultConfig()
• SENTINEL_COMPRESS_ARCHIVES: set to false to disable archive compression in getDefaultConfig()

Default runtime paths

Within a workspace, Sentinel uses the following defaults from src/shared/constants.ts:

• runtime home: .claude/sentinel
• database: .claude/sentinel/sentinel_active.db
• spool: .claude/sentinel/spool
• archive: .claude/sentinel/archive
• runtime state: .claude/sentinel/runtime

Minimal library usage

The package root currently re-exports the shared module through src/index.ts. This is a conservative utility surface, not a broad application SDK.

Available exports come from src/shared/index.ts and include:

• shared constants such as DEFAULT_PORT
• path helpers such as getProjectRuntimeHome() and resolveProjectPath()
• redaction helpers from src/shared/redaction.ts
• skill-system helpers from src/shared/skill-system.ts

Example CommonJS usage:

const { DEFAULT_PORT, getProjectRuntimeHome } = require('claude-sentinel');

console.log(DEFAULT_PORT);
console.log(getProjectRuntimeHome(process.cwd()));

Consumers should treat this root export surface as low-level and subject to change outside the CLI and MCP contract.

Runtime behavior and publish caveats

• the package is CLI-first; the main supported product surface is the local runtime plus CLI and MCP entrypoints
• the runtime is currently workspace-scoped, not a fully implemented global daemon, as indicated by src/cli/index.ts
• successful use depends on Claude hook execution or equivalent runtime inputs; a fresh install with no events will naturally show limited data
• users installing from npm need the package to include built dist/ output; the publish flow enforces that with prepublishOnly

Development and build

Install dependencies:

npm install

Build the package:

npm run build

Useful scripts from package.json:

| Script | Purpose | |---|---| | npm run clean | Remove dist/ | | npm run build | Compile TypeScript and run scripts/prepare-package.cjs | | npm run lint | Type-check without emitting files | | npm run pack:check | Inspect npm package contents with npm pack --dry-run | | npm run publish:dry | Run npm publish --dry-run | | npm run prepublishOnly | Clean and rebuild before a real publish |

scripts/prepare-package.cjs verifies that published bin targets exist and ensures each generated executable has a Node shebang.

Publishing notes for maintainers

For first public npm publish readiness:

1. confirm package.json metadata remains accurate for version, license, engines, files, and bin entries
2. run npm install
3. run npm run clean
4. run npm run build
5. run npm run pack:check
6. run npm run publish:dry
7. inspect the tarball contents to confirm it includes dist/, migrations/, .claude/, and ai/skills/ artifacts expected by runtime and MCP flows
8. publish only after confirming npm account, package name ownership, and registry access outside this repository

The maintainer-oriented checklist is documented in MAINTAINER_RELEASE.md.

License

MIT. See LICENSE.