digital-corpus-callosum 1.0.0

Digital Corpus Callosum™ - Local Repository Desktop Agent

Digital Corpus Callosum™ - Local Repository Desktop Agent

The Digital Corpus Callosum™ (DCC) is a lightweight, zero-dependency Python desktop agent designed to bridge the gap between your local development environment and your cloud-based AI Research Assistant.

By scanning specified local directories for Git repositories, compiling their status (branch, uncommitted files, last commits, remote URLs), and writing a structured registry file directly to your Google Drive sync directory, this agent allows the cloud AI assistant to safely and securely "see" the status of your local codebase repositories.

---

🛠️ Features

• Zero Dependencies: Relies 100% on standard Python libraries. No pip install required.
• Deep Git Integration: Gathers current branch, active file modifications, untracked counts, staged files, last commit info, and remote repository URLs.
• Auto-Pruning: Intelligently skips large directories (like node_modules, venv, dist, .git) to ensure lightning-fast execution.
• Automated Scheduling: Includes built-in generators for macOS launchd background daemons and traditional Cron schedules.
• Standardized Schema Validation: Integrates a formal JSON Schema to ensure other developer tools can standardly parse and validate the registry outputs.
• Built-In MCP Server: Operates as a native Model Context Protocol (MCP) server over standard input/output (stdio), allowing any modern agent-based IDE or assistant to query local workspace status.
• Privacy First: Operates purely on-device. The data is only synchronized via your own secure, existing Google Drive application.

---

🚀 Quick Start

1. Manual Scan

You can run a scan on demand by running the Python script directly. Specify the directories you want to scan and where you want to write the output.

python3 digital_corpus_callosum.py --scan-dirs ~/Projects ~/Documents/Development --output "~/Google Drive/My Drive/digital_corpus_callosum.json"

Note: For the cloud AI assistant to read this file, the --output path must reside inside your local directory that is synchronized with Google Drive.

2. Available Options

options:
  -h, --help            show this help message and exit
  --scan-dirs SCAN_DIRS [SCAN_DIRS ...]
                        One or more directory roots to scan for Git repositories.
  --output OUTPUT       Full file path where the compiled repository registry JSON should be written.
  --exclude EXCLUDE [EXCLUDE ...]
                        Directory names to ignore during scanning.
  --generate-plist      Outputs a macOS launchd plist configuration and exits.
  --generate-cron       Outputs a crontab schedule string and exits.
  --print-schema        Prints the standardized registry JSON Schema and exits.
  --mcp                 Runs the script as a built-in stdio Model Context Protocol (MCP) server.

---

📋 Schema Standardization Specification

To support the wider developer ecosystem, Digital Corpus Callosum™ implements a formal and strict JSON Schema. Any software parsing the repository registry file can validate its conformity against this standard.

Printing the JSON Schema

To output the full JSON Schema directly on your terminal, run:

python3 digital_corpus_callosum.py --print-schema

Registry JSON Schema Definition

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Digital Corpus Callosum™ Registry Schema",
  "type": "object",
  "required": [
    "agent_name",
    "last_updated",
    "scanned_roots",
    "repository_count",
    "repositories"
  ],
  "properties": {
    "agent_name": { "type": "string" },
    "last_updated": { "type": "string", "format": "date-time" },
    "scan_duration_seconds": { "type": "number" },
    "scanned_roots": {
      "type": "array",
      "items": { "type": "string" }
    },
    "repository_count": { "type": "integer" },
    "repositories": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["name", "path", "branch", "last_commit", "status", "remotes"],
        "properties": {
          "name": { "type": "string" },
          "path": { "type": "string" },
          "last_scanned": { "type": "string", "format": "date-time" },
          "branch": { "type": "string" },
          "last_commit": {
            "type": ["object", "null"],
            "properties": {
              "hash": { "type": "string" },
              "author_name": { "type": "string" },
              "author_email": { "type": "string" },
              "date": { "type": "string" },
              "subject": { "type": "string" }
            }
          },
          "status": {
            "type": "object",
            "required": ["clean", "modified_count", "untracked_count", "staged_count", "total_changes"],
            "properties": {
              "clean": { "type": ["boolean", "null"] },
              "modified_count": { "type": "integer" },
              "untracked_count": { "type": "integer" },
              "staged_count": { "type": "integer" },
              "total_changes": { "type": "integer" }
            }
          },
          "remotes": {
            "type": "object",
            "additionalProperties": { "type": "string" }
          }
        }
      }
    }
  }
}

---

🤖 Built-In Model Context Protocol (MCP) Server

For modern AI developer environments (like Cursor, Claude Desktop, or custom developer agents), Digital Corpus Callosum™ serves as a fully integrated Model Context Protocol (MCP) server communicating via a standard JSON-RPC 2.0 protocol over standard input/output (stdio).

Running the MCP Server

To initiate the stdio server, run:

python3 digital_corpus_callosum.py --mcp

Note: Any standard status logs or warnings will automatically be piped to stderr to avoid corrupting the stdout JSON-RPC communications channel.

Client Configuration

To connect your favorite AI assistant tool, add the following configuration block to your client settings file (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "digital-corpus-callosum": {
      "command": "python3",
      "args": ["/absolute/path/to/digital_corpus_callosum.py", "--mcp"]
    }
  }
}

Provided Tools

Tool Name	Parameters	Description
get_repository_registry	None	Reads the compiled local repository registry file (digital_corpus_callosum.json) and returns the current cached status of all Git repositories.
scan_repositories_now	None	Triggers an immediate, recursive filesystem scan of your local paths, writes the updated registry file to Google Drive, and returns the live results to the client.

---

⏰ Background Automation Setup

For the assistant to always stay updated with your local repositories, you can schedule the agent to run automatically in the background (e.g., every hour).

Option A: macOS Automation (iMac) using launchd

macOS uses launchd to manage background daemons. The script can automatically generate a .plist file matching your exact scan configurations.

1. Generate the configuration plist:

   python3 digital_corpus_callosum.py --scan-dirs ~/Projects --output "~/Google Drive/My Drive/digital_corpus_callosum.json" --generate-plist > ~/Library/LaunchAgents/com.highpower.digital_corpus_callosum.plist
   

2. Load and start the background daemon:

   launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.highpower.digital_corpus_callosum.plist
   

To verify it is loaded, run:

launchctl list | grep digital_corpus_callosum

Log files will be output to:

• Standard logs: ~/Library/Logs/digital_corpus_callosum.log
• Error logs: ~/Library/Logs/digital_corpus_callosum_err.log

---

Option B: Linux / macOS using cron

If you prefer traditional cron jobs, the script can generate a crontab line for you:

1. Generate the crontab line:

   python3 digital_corpus_callosum.py --scan-dirs ~/Projects --output "~/Google Drive/My Drive/digital_corpus_callosum.json" --generate-cron
   

2. Add it to your system crontab: Open your crontab manager:

   crontab -e
   

   Paste the generated line at the bottom of the file and save.

---

🔒 Security & Privacy

Because the script only writes a structured JSON file containing repo names, paths, status counts, and commit headers, no raw code is uploaded or read. The cloud assistant only looks at metadata, preserving complete code privacy. Since the sync medium is your own Google Drive account, no third-party APIs or web servers are exposed.