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:

CODEBLOCK0

Or invoke directly:

CODEBLOCK1

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.
• INLINECODE2: Automatically create a GitHub PR with the report (requires gh CLI).
• INLINECODE4: Custom title for the PR.
• INLINECODE5: Custom body for the PR.
• INLINECODE6: Output raw JSON analysis data.
• INLINECODE7 / --no-pyscn: Explicitly enable or disable the PySCN engine (dead code & clones).
• INLINECODE9 / --no-ai-codeindex: Explicitly enable or disable the AI-CodeIndex engine (AST coupling).

You can also spawn ghostclaw as a sub-agent:

CODEBLOCK2

2. Background Watcher (Cron)

Configure ghostclaw to monitor repositories:

CODEBLOCK3

Or integrate directly:

CODEBLOCK4

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:

CODEBLOCK5

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. 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: INLINECODE20
6. Test comparison: INLINECODE21

Files

• - ghostclaw/cli/ghostclaw.py — Main entry point (ad-hoc review mode)
• INLINECODE23 — Trend analysis and comparison entry point
• INLINECODE24 — Cron watcher loop for repo monitoring
• INLINECODE25 — Modular analysis engine (Python)

• - ghostclaw/stacks/ — Tech-stack specific analysis logic

• - ghostclaw/lib/ — Utility libraries

• - ghostclaw/references/stack-patterns.yaml — Configurable architectural rules
• INLINECODE42 — Documentation of patterns

Invocation Examples

CODEBLOCK6