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 (One-Shot Review) Scan a codebase directly via CLI: ```bash python -m ghostclaw.cli.ghostclaw /path/to/repo ``` Or invoke directly: ```bash ghostclaw /path/to/repo ``` Ghostclaw will: - Scan the code and rate "vibe health". - **Auto-generate** a timestamped `ARCHITECTURE-REPORT-<timestamp>.md` in the repository root. - Detect if a GitHub remote exists and suggest PR creation. **Flags:** - `--no-write-report`: Skip generating the Markdown report file. - `--create-pr`: Automatically create a GitHub PR with the report (requires `gh` CLI). - `--pr-title "Title"`: Custom title for the PR. - `--pr-body "Body"`: Custom body for the PR. - `--json`: Output raw JSON analysis data. - `--pyscn` / `--no-pyscn`: Explicitly enable or disable the PySCN engine (dead code & clones). - `--ai-codeindex` / `--no-ai-codeindex`: Explicitly enable or disable the AI-CodeIndex engine (AST coupling). You can also spawn ghostclaw as a sub-agent: ```bash openclaw agent --agent ghostclaw --message "review the /src directory" ``` ### 2. Background Watcher (Cron) Configure ghostclaw to monitor repositories: ```bash openclaw cron add --name "ghostclaw-watcher" --every "1d" --message "python -m ghostclaw.cli.watcher repo-list.txt" ``` Or integrate directly: ```python from ghostclaw.cli.watcher import main main() ``` 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 suggestions**: Precise edits, new abstractions - **Tech Stack Alignment**: How changes match framework idioms **Example**: ```text Module: src/services/userService.ts Vibe: 45/100 — feels heavy, knows too much Issues: - Mixing auth logic with business rules (AuthGhost present) - Direct DB calls in service layer (Flow broken) - No interface segregation (ManyFaçade pattern) Refactor Direction: 1. Extract IAuthProvider, inject into service 2. Move DB logic to UserRepository 3. Split into UserQueryService / UserCommandService Suggested changes... (patches follow) ``` ## Tech Stack Awareness Ghostclaw adapts to stack conventions: - **Node/Express**: looks for proper layering (routes → controllers → services → repositories), middleware composition - **React**: checks component size, prop drilling, state locality, hook abstraction - **Python/Django**: evaluates app structure, model thickness, view responsibilities - **Go**: inspects package cohesion, interface usage, error handling patterns - **Rust**: assesses module organization, trait boundaries, ownership clarity See `ghostclaw/references/stack-patterns.yaml` and `ghostclaw/references/stack-patterns.md` for detailed heuristics. ## Setup 1. Install dependencies: `pip install -e .` in the project root 2. Ensure system tools: `bash`, `git`, `gh` (optional for PRs), `jq` (optional for JSON output) 3. Create `repo-list.txt` in project root for watcher mode (list of repos to monitor, one per line) 4. Set `GH_TOKEN` env variable for PR automation 5. Test ad-hoc review: `python -m ghostclaw.cli.ghostclaw /path/to/target-repo` 6. Test comparison: `python -m ghostclaw.cli.compare --repos-file repo-list.txt` ## Files - `ghostclaw/cli/ghostclaw.py` — Main entry point (ad-hoc review mode) - `ghostclaw/cli/compare.py` — Trend analysis and comparison entry point - `ghostclaw/cli/watcher.py` — Cron watcher loop for repo monitoring - `ghostclaw/core/` — Modular analysis engine (Python) - `analyzer.py` — Main CodebaseAnalyzer class - `cache.py` — Caching layer for analysis results - `detector.py` — Code smell and pattern detection - `metrics.py` — Vibe scoring and metrics computation - `coupling.py` — Coupling analysis - `validator.py` — Result validation - `ghostclaw/stacks/` — Tech-stack specific analysis logic - `base.py` — Base stack analyzer interface - `python.py` — Python-specific patterns - `node.py` — Node.js/Express patterns - `go.py` — Go-specific patterns - `ghostclaw/lib/` — Utility libraries - `github.py` — GitHub API integration - `cache.py` — Caching utilities - `notify.py` — Notification system - `ghostclaw/references/stack-patterns.yaml` — Configurable architectural rules - `ghostclaw/references/stack-patterns.md` — Documentation of patterns ## Invocation Examples ```text User: ghostclaw, review my backend services Ghostclaw: Scanning... vibe check: 62/100 overall. Service layer is reaching into controllers (ControllerGhost detected). Suggest extracting business logic into pure services. See attached patches. $ python -m ghostclaw.cli.ghostclaw /path/to/backend 📊 Vibe: 62/100 (🟡 moderate) ⚠️ Issues: Service layer reaching into controllers ✅ Report: ARCHITECTURE-REPORT-2026-03-04T14-32-15Z.md User: show me the health trends for my microservices Ghostclaw: Running comparison... Average vibe: 74.5/100 (+4.2). 8/10 repos are healthy. $ python -m ghostclaw.cli.compare --repos-file repo-list.txt Comparing 10 repositories... 📈 Average Vibe: 74.5/100 (+4.2 from last run) 🟢 Healthy: 8/10 repos above threshold ``` --- **Remember**: Ghostclaw is not a linter. It judges the *architecture's soul*.