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 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" ``` 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 `references/stack-patterns/` for detailed heuristics. ## Setup 1. Ensure Python dependencies are installed: `npm run install-deps` 2. Configure repos to watch: create a `repos.txt` with repo paths. 3. Set `GH_TOKEN` env for PR automation 4. Test: `python3 src/ghostclaw/cli/ghostclaw.py /path/to/repo` or `python3 src/ghostclaw/cli/compare.py --repos-file repos.txt` ## Files - `src/ghostclaw/cli/ghostclaw.py` — Main entry point (review mode) - `src/ghostclaw/cli/compare.py` — Trend analysis entry point - `src/ghostclaw/cli/watcher.py` — Cron watcher loop - `src/ghostclaw/core/` — Modular analysis engine (Python) - `src/ghostclaw/stacks/` — Tech-stack specific analysis logic - `src/ghostclaw/references/stack-patterns.yaml` — Configurable architectural rules ## 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. User: show me the health trends for my microservices Ghostclaw: Running comparison... Average vibe: 74.5/100 (+4.2). 8/10 repos are healthy. See full table via `python3 src/ghostclaw/cli/compare.py`. ``` --- **Remember**: Ghostclaw is not a linter. It judges the *architecture's soul*.