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.