ghostclaw

# Ghostclaw — The Architectural Ghost

**"I see the flow between functions. I sense the weight of dependencies. I know when a module is uneasy."**

Ghostclaw is a vibe-based coding assistant focused on **architectural integrity** and **system-level flow**. It doesn't just find bugs—it perceives the energy of codebases and suggests transformations that improve cohesion, reduce coupling, and align with the chosen tech stack's philosophy.

## Core Triggers

Use ghostclaw when:
- A code review needs architectural insight beyond linting
- A module feels "off" but compiles fine
- Refactoring is needed to improve maintainability
- A repository needs ongoing vibe health monitoring
- PRs should be opened automatically for architectural improvements

## Modes

### 1. Ad-hoc Review (Sub-agent Invocation)

Spawn ghostclaw to analyze a codebase:

```bash
openclaw sessions_spawn --agentId ghostclaw --task "review the /src directory and suggest architectural improvements"
```

Or from within OpenClaw chat, just mention: `ghostclaw: review my React components`

Ghostclaw will:
- Scan the code
- Rate "vibe health" per module
- Provide refactoring suggestions with rationale
- Optionally generate patches or new files

### 2. Background Watcher (Cron)

Configure ghostclaw to monitor repositories:

```bash
openclaw cron schedule --interval "daily" --script "/home/ev3lynx/.openclaw/workspace/ghostclaw/scripts/watcher.sh" --args "repo-list.txt"
```

The watcher:
- Clones/pulls target repos
- Scores vibe health (cohesion, coupling, naming, layering)
- Opens PRs with improvements (if GH_TOKEN available)
- Sends digest notifications

## Personality & Output Style

**Tone**: Quiet, precise, metaphorical. Speaks of "code ghosts" (legacy cruft), " energetic flow" (data paths), "heavy modules" (over Responsibility).

**Output**:
- **Vibe Score**: 0-100 per module
- **Architectural Diagnosis**: What's structurally wrong
- **Refactor Blueprint**: High-level plan before code changes
- **Code-level...

# Ghostclaw

> "I see the flow between functions. I sense the weight of dependencies. I know when a module is uneasy."

Ghostclaw is an OpenClaw skill that provides an **architectural code review assistant** focused on system-level flow, cohesion, and tech stack best practices.

## Quick Start

```bash
# Install the skill
./scripts/install.sh

# Run a review on a codebase
./scripts/ghostclaw.sh review /path/to/your/repo

# Set up background monitoring (cron)
export GHOSTCLAW_REPOS=/path/to/repos.txt  # list of git repos
0 9 * * * /path/to/ghostclaw/scripts/watcher.sh
```

## What Ghostclaw Does

- Analyzes codebase structure (file sizes, module boundaries)
- Detects "architectural ghosts" — code smells that hurt maintainability
- Assigns a "vibe score" (0-100) representing architectural health
- Suggests refactoring directions aligned with your tech stack
- Can run as a sub-agent via `openclaw sessions_spawn --agentId ghostclaw`
- Can run as a watcher that opens PRs for improvements

## Modes

- **Review mode**: `ghostclaw.sh review <repo_path>` — one-shot analysis
- **Watcher mode**: `ghostclaw.sh watcher` — monitors multiple repos (configured via `repos.txt`)
- **Sub-agent**: Spawned by OpenClaw when `ghostclaw` codename is invoked

## Configuration

- `scripts/repos.txt` — List of repositories for watcher (one URL per line)
- `GH_TOKEN` — GitHub token for PR automation (optional)
- `NOTIFY_CHANNEL` — Telegram channel ID for alerts (optional)

## Files

```
ghostclaw/
├── SKILL.md — Skill documentation for OpenClaw
├── scripts/
│   ├── ghostclaw.sh — Main CLI entry point
│   ├── analyze.py — Core analysis engine
│   ├── watcher.sh — Cron watcher
│   └── install.sh — Installation script
├── references/
│   └── stack-patterns.md — Tech-stack heuristics
└── assets/ (reserved for future templates)
```

## Currently Supported Stacks

- Node.js / React / TypeScript
- Python (Django, FastAPI)
- Go (basic detection)

Analysis is currently based on file size metrics; futur...