Shadow-Core Sentinel — MCP Filesystem Telemetry

Shadow-Core Sentinel — MCP Filesystem Telemetry

Sentinel records every file change under a watched directory, with a SHA-256 ofeach file, so a change can be confirmed against what actually happened ondisk rather than assumed.

It records what changed, never whether the change is correct. It is afilesystem oracle, not a semantic one — it will not catch a deleted function, awrong value, or a broken test. Linters and tests remain the tools for that.

Key features

• Non-blocking — hashing is offloaded to a thread pool so OS events are notdropped while a large file is read.
• Cryptographically verified — every event carries a SHA-256, so "did thisfile revert to its original state?" is answerable.
• Context-optimised — recent_changes answers "did my edit land?" in tensof rows. query_events takes a whole date, which on a busy project is tens ofthousands (measured: 19,936 in one day).
• Multi-project — several projects watched at once, each with its owndatabase and audit directory. Adding a watch never removes another, so twosessions cannot silently stop each other's monitoring.
• Idle suspension with gap recovery — an inactive project suspends ratherthan being watched forever. Suspension is not removal: history stays intactand the next prompt resumes it. Changes made while suspended are reconstructedfrom a SHA-256 comparison and written into the trail marked asdetected-on-resume, so the unwatched period is visible rather than missing.
• Atomic-write aware — editors that write via a temp file and rename recordas a single MODIFIED of the real path, with no phantom DELETE of the filethey just replaced.
• Noise guard — high-churn directories (node_modules, .git, venv,build output) are ignored by default.

Requirements

Python 3.11. The pinned versions in requirements.txt are verified againstit.

Install

pip install -r requirements.txt

For development — this is what you need to run the test suite, whichrequirements.txt alone does not provide:

pip install -e ".[dev]"

Run

python main.py

Sentinel boots watching nothing and stays idle until a session callswatch_project. That is deliberate: it starts with the machine, and coming uprecording a directory nobody asked about means CPU spent hashing and an audittrail nobody reads.

To start it automatically at logon, see INSTALL.md.

--port is a deprecated alias for --dashboard-port.

Environment variables

Flush on start

SENTINEL_FLUSH_ON_START defaults to true: every start deletes allrecorded audit data, so a run begins with no history. This completes whatSentinel already did — it boots watching nothing, and its in-RAM ring startsempty — and it bounds disk, which nothing else did. Before this the trail hadreached 252 MB with no retention policy at all, 38% of it a dead projectcreated by a typo in a watched path.

What you lose, stated plainly: cross-restart forensics. list_audit_dates,get_daily_report and query_events can only answer about the current run,and "what changed while I wasn't looking" — the one question git cannot answer— is unanswerable across a restart, because the evidence is deleted first. Gapreconstruction still works, but only across a suspend/resume inside one run.

Set SENTINEL_FLUSH_ON_START=false to keep history.

The flush only removes things it recognises as its own: a directory holding asentinel.db or Sentinel's markdown artifacts, an empty project directory, ora loose sentinel.*/audit-*.md/snapshot-*.md/gap-*.md at the audit root.Anything else is left alone and logged, and an AUDIT_DIR closer than threepath components to a filesystem root is refused outright — a mis-setAUDIT_DIR must not be able to delete source.

MCP client configuration

Sentinel speaks MCP over SSE, not stdio. It is not spawned by theclient — it must already be running, and the client connects to it:

{
  "mcpServers": {
    "shadow-core-sentinel": {
      "type": "sse",
      "url": "http://127.0.0.1:7702/sse"
    }
  }
}

A "command"/"args" entry — the stdio spawn form — does not work here.The client launches the process, waits for stdio that never comes, and hangs,because main.py runs mcp.run(transport="sse", ...) and serves HTTP instead.

Verify it is up:

curl http://127.0.0.1:7702/health

Using it

At the start of a session:

watch_project(path="<absolute path of the working directory>")

Additive and idempotent — it never stops another session's watch, andre-calling it for an already-watched directory only renews its lease.

Before reporting that a change is complete:

recent_changes(minutes=15)

Compare files you intended to change against what the filesystem recorded.This catches an edit that silently did not land, and files changed that were notmeant to be touched. It is worth most after a build, install, or generated-filestep, where an exit code of 0 is not evidence that a file was written.

Endpoints

Selecting a dashboard tab is a client-side view change: it does not move theserver's default project or affect another session.

Tests

python -m pytest -m "not slow"

Layout