Metadata-Version: 2.4
Name: digital_corpus_callosum
Version: 1.0.0
Summary: Digital Corpus Callosum™ - Local Repository Desktop Agent
Home-page: https://github.com/highpower-tech/digital-corpus-callosum
Author: Derek Adamson (High Power Technical Solutions LLCnical Solutions LLC)
Author-email: derek@highpower.tech
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.md
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python
Dynamic: summary

# 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.

```bash
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
```text
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:
```bash
python3 digital_corpus_callosum.py --print-schema
```

### Registry JSON Schema Definition
```json
{
  "$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:
```bash
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`):

```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**:
   ```bash
   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**:
   ```bash
   launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.highpower.digital_corpus_callosum.plist
   ```

To verify it is loaded, run:
```bash
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**:
   ```bash
   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:
   ```bash
   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.
