# Digital Rain

[![License](https://img.shields.io/github/license/SSX360/digital-rain)](LICENSE)
[![Tests](https://github.com/SSX360/digital-rain/actions/workflows/test.yml/badge.svg)](https://github.com/SSX360/digital-rain/actions/workflows/test.yml)

Digital Rain is a privacy-first, read-only repo intelligence tool for AI coding agents. Point it at a local codebase and it returns a grounded brief: what the repo is, what fits it, what to install next, and what to watch before you scale the workflow.

## What it does

- Scans a local repo for languages, frameworks, package managers, notebooks, and launch signals
- Recommends relevant MCP servers, open-source repos, research papers, models, and market references
- Exposes a local MCP server under the public label `digital-rain-mcp`
- Previews editor config scaffolding before any write and only writes when explicitly allowed
- Runs as a local web app, a desktop companion, or a stdio MCP server

## What it does not do

- No auto-installs
- No arbitrary repo edits
- No hidden file mutation
- No required cloud account for core scans, search, or deterministic recommendations

## Why local, why read-only

Digital Rain is built for teams that want repo intelligence without shipping source code to a hosted analyzer by default. The scanner reads the workspace on disk, the vault stays local, and the MCP surface is read-only unless you explicitly opt into narrow editor-config scaffolding with `write=true`.

## Try it now

**macOS / Linux**

```bash
git clone https://github.com/SSX360/digital-rain.git
cd digital-rain
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python -m pip install .[mcp]
python ingest.py --seed
```

Run the dashboard:

```bash
source .venv/bin/activate
python app.py
```

Run the MCP server:

```bash
source .venv/bin/activate
python mcp_server.py
```

**Windows (PowerShell)**

```powershell
git clone https://github.com/SSX360/digital-rain.git
cd digital-rain
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
python -m pip install .[mcp]
python ingest.py --seed
```

Run the dashboard:

```powershell
.\.venv\Scripts\Activate.ps1
python app.py
```

Run the MCP server:

```powershell
.\.venv\Scripts\Activate.ps1
python mcp_server.py
```

Open the printed local URL, pick a folder in **Active Project**, and ask for a scan or recommendations. If you only want the MCP server, stop after the install path and start `python mcp_server.py`.

## MCP setup

Use `digital-rain-mcp` for every new install. Replace the placeholder paths once, then paste the block into your editor config.

### Cursor: `.cursor/mcp.json`

```json
{
  "mcpServers": {
    "digital-rain-mcp": {
      "type": "stdio",
      "command": "<ABSOLUTE_PATH_TO_DIGITAL_RAIN_VENV_PYTHON>",
      "args": [
        "<ABSOLUTE_PATH_TO_DIGITAL_RAIN>/mcp_server.py"
      ],
      "env": {
        "COPILOT_WORKSPACE": "${workspaceFolder}"
      }
    }
  }
}
```

### VS Code: `.vscode/mcp.json`

```json
{
  "mcpServers": {
    "digital-rain-mcp": {
      "type": "stdio",
      "command": "<ABSOLUTE_PATH_TO_DIGITAL_RAIN_VENV_PYTHON>",
      "args": [
        "<ABSOLUTE_PATH_TO_DIGITAL_RAIN>/mcp_server.py"
      ],
      "env": {
        "COPILOT_WORKSPACE": "${workspaceFolder}"
      }
    }
  }
}
```

### Claude Desktop: config file

```json
{
  "mcpServers": {
    "digital-rain-mcp": {
      "type": "stdio",
      "command": "<ABSOLUTE_PATH_TO_DIGITAL_RAIN_VENV_PYTHON>",
      "args": [
        "<ABSOLUTE_PATH_TO_DIGITAL_RAIN>/mcp_server.py"
      ],
      "env": {
        "COPILOT_WORKSPACE": "<ABSOLUTE_PATH_TO_TARGET_REPO>"
      }
    }
  }
}
```

Path note:
- macOS / Linux venv Python usually looks like `/absolute/path/to/digital-rain/.venv/bin/python`
- Windows venv Python usually looks like `C:\\absolute\\path\\to\\digital-rain\\.venv\\Scripts\\python.exe`

Compatibility note:
- If you previously used `matrixscroll-mcp` or `cursor-copilot`, keep that only as a temporary compatibility shim. New installs should use `digital-rain-mcp`.

## Point it at a real repo

The proof assets below come from real runs against this repo and the public trust surfaces it audits.

**Repo input:** `digital-rain`

**Observed repo grounding**
- Languages: `python`, `html`
- Frameworks: `flask`, `static-site`
- Notable SDKs: `anthropic`, `vercel`, `numpy`, `pandas`, `pytorch`
- Launch readiness: `ready`

**Observed recommendations**
- `GitHub MCP Server`
- `Playwright MCP`
- `Context7`
- `Sigstore Python`

**Observed trust audit**
- "Detected public site trust surface. 8 proof link(s) surfaced. No legacy naming found in the audited surface."

**Observed config preview**
- `scaffold_editor_integration(..., write=false)` returns a diff preview for `.cursor/mcp.json`
- `scaffold_editor_integration(..., write=true)` is the only narrow write path and is meant for explicit config scaffolding only

## Proof assets

These images are reused from the current demo output rather than mocked marketing art.

![Repo grounding proof](docs/media/repo-grounding-proof.png)

![Trust and rollout proof](docs/media/trust-rollout-proof.png)

![Setup write-gate proof](docs/media/setup-write-gate-proof.png)

## Tool surface

### Repo grounding

- `analyze_workspace`
- `brainstorm_workspace`
- `benchmark_openhuman`

### Trust and rollout

- `audit_trust_surface`
- `scaffold_editor_integration`
- `plan_repo_rollout`

Compatibility note:
- `plan_matrixscroll_rollout` still ships as a legacy compatibility alias so existing MCP clients do not break during the rename.

### Ecosystem intelligence

- `recommend_ecosystem`
- `build_usecase_blueprint`
- `scan_research_radar`
- `scan_market_radar`

## Local app

Digital Rain runs as:

- A local web dashboard via `python app.py`
- A floating desktop companion via `python desktop_launcher.py` or `run_desktop_companion.bat`
- Local HTTP APIs for scripts and QA
- A stdio MCP server via `python mcp_server.py`

The backend binds to `127.0.0.1` only by default.

## Desktop companion

**macOS / Linux**

```bash
source .venv/bin/activate
python desktop_launcher.py
```

**Windows**

```bat
run_desktop_companion.bat
```

The launcher starts or reuses the Flask backend on port `59712`, waits for `/api/health`, then launches the transparent companion. It uses the active workspace pointer from the dashboard or `COPILOT_WORKSPACE` when set.

## Project intelligence APIs

```bash
curl -s http://127.0.0.1:59712/api/health
curl -s http://127.0.0.1:59712/api/diagnostics
curl -s http://127.0.0.1:59712/api/project/status
curl -s "http://127.0.0.1:59712/api/ecosystem/recommendations?goal=browser%20testing"
```

```powershell
Invoke-RestMethod -Uri "http://127.0.0.1:59712/api/health"
Invoke-RestMethod -Uri "http://127.0.0.1:59712/api/diagnostics"
Invoke-RestMethod -Uri "http://127.0.0.1:59712/api/project/status"
Invoke-RestMethod -Uri "http://127.0.0.1:59712/api/ecosystem/recommendations?goal=browser%20testing"
Invoke-RestMethod -Uri "http://127.0.0.1:59712/api/research/radar?goal=agent%20memory"
Invoke-RestMethod -Uri "http://127.0.0.1:59712/api/market/radar?goal=agent%20memory"
Invoke-RestMethod -Uri "http://127.0.0.1:59712/api/usecase/blueprint?goal=agent%20memory"
Invoke-RestMethod -Uri "http://127.0.0.1:59712/api/benchmark/openhuman"
```

Useful local functions for scripts:

```python
from digital_rain_core import (
    analyze_workspace,
    brainstorm_workspace,
    recommend_ecosystem,
    build_usecase_blueprint,
)

profile = analyze_workspace("/path/to/project")
ideas = brainstorm_workspace("/path/to/project", goal="improve onboarding")
recommendations = recommend_ecosystem("/path/to/project", goal="browser testing")
blueprint = build_usecase_blueprint("/path/to/project", goal="launch an agent workflow debugger")
```

## Use Case Lab

The dashboard's Use Case Lab compiles a goal into a read-only blueprint:

- Power Stack: what to build locally, what to integrate, and what to monitor
- Patterns to Borrow: public product, launch, and OSS patterns worth adapting
- Build vs Integrate: explicit recommendations for custom code versus mature dependencies
- Research Edge: relevant arXiv papers and Hugging Face model candidates
- Market Proof: Uneed, MicroLaunch, DevHunt, and Hacker News signals
- Next Implementation Steps: concrete actions for the active repo

The market radar uses public pages and the official Hacker News API where possible, with deterministic seed fallbacks when a source is unavailable.

## Research Radar

Digital Rain tracks academic and model-release context in addition to open-source repo signals:

- Academic paper lookup through the arXiv API, with cached results and seed fallbacks
- Hugging Face model discovery using public Hub search metadata
- Topic selection from the active project stack, SDKs, notebooks, and user goal
- Local cache under `~/.digital-rain/cache`

Public sources:

- <https://info.arxiv.org/help/api/user-manual.html>
- <https://huggingface.co/docs/huggingface_hub/en/guides/search>
- <https://huggingface.co/docs/hub/en/models-the-hub>

## Ecosystem Ranking

Digital Rain combines local project facts with public open-source signals:

- Stack fit from detected languages, frameworks, SDKs, package managers, and goal terms
- Curated seed categories for MCP servers, coding-agent skills, RAG, memory, and vector database projects
- Cached OSSInsight and GitHub metrics such as stars, forks, issue pressure, contributors, recent growth, and freshness
- Install complexity penalties for heavier repository adoption
- Plain-language reasons and "why now" explanations

Metrics are cached under `~/.digital-rain/cache` by default. Set `OSS_INSIGHT_CACHE_TTL` or `DIGITAL_RAIN_CACHE_DIR` to change cache behavior.

## Privacy

Local project scanning stays on your machine. Digital Rain reads manifests, configs, README excerpts, notebooks, and local notes to build the project profile. OSSInsight and GitHub enrichment uses public repository names from the curated seed list; it does not upload your local source code.

Diagnostics redact secret-like environment keys and project metadata before returning support bundles. Market and research requests use public query terms and public source metadata; local source files are not uploaded to launch directories, HN, OSSInsight, GitHub, arXiv, or Hugging Face.

Safety tip:
- Review the source and run in a sandbox or VM if you are evaluating an unfamiliar checkout.

## Refresh data

```bash
python ingest.py --seed
python ingest.py --catalog-only
python ingest.py --no-catalog
```

The local index powers documentation search and catalog matching. Ecosystem recommendations also work from built-in seeds when the network is unavailable.

## QA

Automated tests ([`tests/`](tests/), CI: [`.github/workflows/test.yml`](.github/workflows/test.yml)):

```bash
python -m pytest tests/ -q
python -m py_compile app.py scanner.py brainstorm.py workspace_config.py search.py oss_insight.py research_radar.py market_radar.py usecase_synthesizer.py digital_rain_core.py immersive_web.py desktop_launcher.py
```

Manual demo scripts:

- [docs/QA_DEMO.md](docs/QA_DEMO.md)
- [docs/QA_DEMO_3D_METAVERSE.md](docs/QA_DEMO_3D_METAVERSE.md)
- [docs/MCP_FULL_SURFACE_DEMO.md](docs/MCP_FULL_SURFACE_DEMO.md)

For release evidence:

```bash
python -m qa.run_gates --workspace empty --report out/qa-report.json
python -m qa.release_evidence --output-dir out/release-evidence
```

## Optional signed-provenance upgrade

If local repo intelligence is no longer enough and you need signed commit-time provenance, Digital Rain can feed a stricter trust layer later. That upgrade path lives outside this repo: [matrixscroll.com](https://matrixscroll.com).

## License

Apache License 2.0. See [LICENSE](LICENSE).

## Configuration

| Variable | Default | Purpose |
| --- | --- | --- |
| `COPILOT_WORKSPACE` | unset | Active project directory override |
| `PORT` | random for `app.py`, `59712` for companion launcher | Backend port |
| `OPEN_BROWSER` | `1` | Whether `app.py` opens a browser |
| `LLM_BACKEND` | auto | Preferred generation backend |
| `ANTHROPIC_API_KEY` | unset | Claude backend |
| `GEMINI_API_KEY` | unset | Gemini backend |
| `OLLAMA_URL` | `http://localhost:11434` | Local Ollama endpoint |
| `OSS_INSIGHT_CACHE_TTL` | 12 hours | Ecosystem metrics cache TTL |
| `MARKET_RADAR_CACHE_TTL` | 6 hours | Launch and market-source cache TTL |
| `DIGITAL_RAIN_CACHE_DIR` | `~/.digital-rain/cache` | Ecosystem, research, and market cache directory |

Per-project settings live in `.cursor/co-pilot.json` for compatibility with existing installations. The file controls notebook limits, vault mode, and brainstorm preferences.