Ghostclaw

Architectural code review and refactoring assistant that perceives code vibes and system-level flow issues. Use for analyzing code quality and architecture,...

Security Scan

The skill's code and instructions broadly match an architectural-review tool, but there are several mismatches and omissions (missing referenced modules/files, undeclared GH_TOKEN usage, and hook/auto-PR capabilities) that make the package inconsistent and worth closer inspection before trusting it with repository access or credentials.

Purpose & Capability

Name/description align with the included analyzer, watcher, and CLI code: the package is built to scan repos, compute metrics, and optionally open PRs. However some source references (ghostclaw.lib.* modules like VibeCache, GitHubClient, Notifier) are referenced by the CLI/watcher but are not present in the provided file manifest or file listing — this is an internal inconsistency that will likely cause runtime failures.

Instruction Scope

SKILL.md and HOOK.md instruct the agent to clone/pull repositories, scan arbitrary repositories (local or remote), write timestamped report files into target repositories, and open PRs automatically. Those instructions imply reading and modifying arbitrary repos on disk and network access to GitHub; those behaviors are consistent with the stated purpose but are sensitive (access to repo contents and the ability to create commits/PRs). The skill also instructs being run as a hook reacting to system/command events — this expands its runtime surface significantly if enabled.

Install Mechanism

No formal install spec in registry; SKILL.md suggests 'pip install -e .' and the code contains an update routine that uses git pull or pip to self-update. There are no suspicious remote download URLs in an install spec, but the self-update logic will run 'git pull' and 'pip install' which can execute code fetched from whatever remote the installed package is tracking — this is standard but worth noting if provenance is uncertain.

Credentials

The registry metadata lists no required env vars, but SKILL.md and code clearly expect credentials: GH_TOKEN (or --gh-token / gh CLI auth) for PR automation, optional Telegram tokens for notifications, and it uses dotenv. These credentials are not declared in requires.env. The skill asks for ability to run 'gh' and 'git' and to write into repos; those privileges should be considered sensitive and should be tied to explicitly-declared, scoped credentials. The mismatch between what's declared and what the code uses is problematic.

Persistence & Privilege

always:false (good). However HOOK.md documents enabling Ghostclaw as an OpenClaw hook that listens to command/system events and can run automatically and open PRs. Enabling such a hook gives ongoing background access to analyze and modify repos — a powerful capability that should only be granted if you trust the skill's provenance. The skill itself does not request to be always-enabled, but can be made persistent by user action.

Scan Findings in Context

[no_pre_scan_signals] expected: The regex-based pre-scan reported no injection signals. That doesn't offset the other inconsistencies (missing referenced modules, undeclared env vars). Absence of findings is not proof of safety.

What to consider before installing

What to consider before installing or enabling Ghostclaw: - Missing/undeclared pieces: The code references helper modules (ghostclaw.lib.* like VibeCache, GitHubClient, Notifier) that are not present in the provided manifest. This will likely break at runtime — ask the publisher for the full package or inspect the missing files before use. - Credentials: The tool uses GH_TOKEN (or --gh-token) and can open PRs and push branches. Do NOT supply a full-all-scopes token. If you must provide a token, create a narrowly-scoped GitHub token with the minimum permissions (or use gh CLI auth with limited scope), and only for repositories you trust. - Hooks & autonomy: Enabling the hook gives the skill ongoing access to analyze and modify repositories on events. Only enable hooks if you trust the author's provenance and reviewed the code. The skill is not 'always' forced on by default, but enabling hooks grants background capability. - Self-update risk: The CLI can run 'git pull' and 'pip install' to update itself. That means new code could be pulled and executed. Prefer installing from pinned, auditable releases or from a trusted package index; avoid enabling automatic self-updates without review. - Run in isolation first: Try running the tool in a sandbox or on a non-sensitive/local test repo to observe behavior (and confirm missing modules) before letting it scan important repos or giving it credentials. - Ask for provenance: The registry lists no homepage/official source in metadata; HOOK.md references a GitHub URL. Verify the upstream repository, publisher identity, and release artifacts before trusting automated write/PR behavior. If you want, I can: (1) list the exact import/filename mismatches found so you can ask the author for missing files, or (2) suggest exact minimal GitHub scopes for a token if you decide to run it with limited privileges.

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:

python -m ghostclaw.cli.ghostclaw /path/to/repo

Or invoke directly:

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:

openclaw agent --agent ghostclaw --message "review the /src directory"

2. Background Watcher (Cron)

Configure ghostclaw to monitor repositories:

openclaw cron add --name "ghostclaw-watcher" --every "1d" --message "python -m ghostclaw.cli.watcher repo-list.txt"

Or integrate directly:

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:

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

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.