DEV Community

Arthur Palyan
Arthur Palyan

Posted on

We Renamed a File and Almost Lost Everything

#mcp #devops #ai #opensource

Series: The Nervous System - Part 6

We Renamed a File and Almost Lost Everything

Why we built drift_audit into The Nervous System v1.4.0

We came in for a quick task. Check a role description on the website. Should have been 5 minutes.

It turned into the most important feature we have ever built.

What Happened

Our system runs 12 AI agents on a $12/month VPS. Tamara manages operations. Roman handles content. Lily coaches players. Each one has a role defined in multiple places - config files, website pages, documentation, session handoffs.

We noticed the website said Roman was a "press/media" bot. Wrong. Roman is a teacher. Developer education. We changed that months ago.

So we dug in. How many other references were stale?

Six files still said the old role. A version reference said v1.3.0 when we were running v1.4.0. The session handoff said 14 tools when we had 12. A previous LLM session had "fixed" Tamara's config back to v5 because all the docs said v5 - but she was actually running v6.

That last one is the killer. An LLM session saw a mismatch between code and docs. It "helpfully" reverted the code to match the docs. The docs were wrong. The code was right. The fix broke Tamara.

The Real Problem

Configuration drift. Not the kind you get in Kubernetes. The kind you get when 12 agents, 28 processes, and a human are all making changes across dozens of files, and nobody checks if the references still match.

System prompts do not catch this. Code reviews do not catch this. You only find it when something breaks - or when a customer sees the wrong information on your website.

What drift_audit Does

drift_audit scans your system for inconsistencies across 5 scopes:

1. Roles

Checks that every family member's role description is consistent across all files that reference them. If Roman is "teacher" in one file and "press" in another, drift_audit flags it.

2. Versions

Checks that version numbers match across package.json, README, website, documentation, and session files. If package.json says 1.4.0 but the website says 1.3.0, that is drift.

3. Files

Checks that file references in documentation actually exist. If a config file references /root/tamara-v5.js but the actual file is /root/tamara-v6.js, that is drift.

4. Processes

Checks that running processes match what documentation says should be running. If docs say 14 tools but you have 12, that is drift.

5. Website

Checks that the public-facing website matches the actual system state. Role descriptions, tool counts, version numbers - all verified against the source of truth.

First Run: 98 Drifts

The first time we ran drift_audit on our own system, it found 98 inconsistencies across 114 checks.

Not 98 bugs. 98 places where what we said did not match what was true.

We fixed every single one. Got to zero drifts across all 5 scopes.

How to Use It

Install the Nervous System:

npx mcp-nervous-system
Enter fullscreen mode Exit fullscreen mode

Then call drift_audit:

{
  "tool": "drift_audit",
  "arguments": {
    "scope": "full"
  }
}
Enter fullscreen mode Exit fullscreen mode

Or check a single scope:

{
  "tool": "drift_audit",
  "arguments": {
    "scope": "versions"
  }
}
Enter fullscreen mode Exit fullscreen mode

Output Format 

{
  "status": "drift_detected",
  "scope": "full",
  "drift_count": 3,
  "clean_checks": 111,
  "total_checks": 114,
  "drifts": [
    {
      "scope": "versions",
      "file": "README.md",
      "expected": "1.4.0",
      "found": "1.3.0"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

When everything is clean:

{
  "status": "clean",
  "scope": "full",
  "drift_count": 0,
  "clean_checks": 114,
  "total_checks": 114
}
Enter fullscreen mode Exit fullscreen mode

The Closed Loop

This is the concept that makes drift_audit different from a linter or a test suite.

A linter checks code against rules. A test suite checks behavior against expectations. drift_audit checks your entire system state against what you claim that state to be.

Your docs say v1.4.0? drift_audit checks. Your website says 12 tools? drift_audit checks. Your config says Tamara runs v6? drift_audit checks.

The loop closes when every surface - code, docs, website, configs, handoffs - all agree. Zero drift means your system is what you say it is. No surprises for the next session, the next team member, or the next customer.

Free Tier

drift_audit is part of the Nervous System free tier. No API key needed. Install, run, get results.

npx mcp-nervous-system
Enter fullscreen mode Exit fullscreen mode

Install

Add to Claude Desktop:

{
  "mcpServers": {
    "nervous-system": {
      "command": "npx",
      "args": ["-y", "mcp-nervous-system"],
      "env": {
        "NS_PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Or run standalone:

npx mcp-nervous-system
Enter fullscreen mode Exit fullscreen mode

The Nervous System ships with 12 tools: preflight checks, violation logging, audit chains, emergency kill switch, session handoffs, health monitoring, dispatch, and now drift_audit. All enforced in bash and file locks - not prompts.

GitHub: github.com/levelsofself/mcp-nervous-system
npm: npx mcp-nervous-system@1.4.0
Built by Palyan Family AI System - 12 agents, $12/month, zero drift.

Top comments (0)