EJWisner/ghost-architect-open

# 👻 Ghost Architect™ **v9.3.5** Ghost Watcher™ PR comments are now fully markdown-escaped. Finding titles and branch names can no longer inject markdown into GitHub PR comments. Ghost Architect™ is a CLI tool powered by Claude that helps developers, architects, and consultants deeply **understand** existing codebases. Not generate new code: illuminate what's already there. It works on any platform, any language, any stack. The most expensive moments in any engagement are not writing new code. They are the first weeks on an inherited codebase, and the gut-check before every risky change. A senior architect spending 2-3 days reading legacy code before contributing costs $3,000 to $5,000 in billable time. Ghost Architect compresses that to minutes. ## Install npm install -g ghost-architect-open Then run it from any directory: ghost That's it. On first run, Ghost walks you through a one-time setup wizard (API key, optional GitHub token, model preference, billing rates, context size). Your config is saved locally and every future run goes straight to the main menu. **Requirements:** Node.js 18 or higher, an Anthropic API key (pay-as-you-go, not the same as a Claude.ai subscription), and optionally a GitHub Personal Access Token for private repos. ## What's New in v9.3.5 Ghost Watcher™ PR comments are now fully markdown-escaped. - **Fix:** escapeMarkdown() helper added to watcher-commit.js - **Fix:** f.title and f.severity escaped in PHASE 1 and PHASE 2 finding loops - **Fix:** refName and actor escaped in main and clean-scan PR comment headers - **Fix:** Prevents markdown injection from LLM-authored finding titles or fork branch names ## Ghost Triple Crown™ -- Three Passes. One Complete Picture. Every Ghost Watcher™ commit triggers three passes automatically. **Leg 1 -- Blast Radius™** Maps every file that breaks if you change something. Know the impact before you touch the code. **Leg 2 -- Conflict Detection™** Finds where two sides of the codebase expect different things. Catches contract mismatches before they hit production. **Leg 3 -- Ghost Brief™** Generates a developer-ready remediation prompt for every finding. Paste directly into Claude Code, Cursor, Copilot, or any AI coding tool. Ghost Watcher™ runs the Ghost Triple Crown™ automatically on every commit. No configuration. No manual scans. Every push, every time. ## What's New in v9.3.4 HTML escaping in all Ghost Watcher email templates. Full test suite restored. - **Fix:** escapeHtml() added to all six Ghost Watcher email templates - **Fix:** f.title, f.detail, f.severity, f.files escaped in findings email - **Fix:** repo, shortSha, portalSlug escaped in all email templates - **New:** 10 smoke tests added to open repo test suite (14 total) - **New:** ad-hoc test directory added - **Fix:** Synthetic credential in verifier test fixture ## What's New in v9.3.3 Ghost Watcher™ now generates detailed LLM-authored remediation prompts for every finding. - **New:** Step 8e -- one batch API call per finding generates a developer-ready remediation prompt - **New:** Prompts replace buildPromptText output in brief.prompts after enrichment - **New:** Resume branch handles timeout -- basic brief ships immediately, detailed prompts follow on next push - **New:** enrichFindingsWithPrompts matches results back to findings by index - **New:** temperature: 0 and max_tokens: 4096 on all prompt generation requests - **Fix:** yaml dependency now properly installed in open repo ## What's New in v9.3.2 Blast Radius findings now carry file data in Ghost Watcher™. - **Fix:** extractBlastSectionFiles() recovers file paths from raw blast bullet lines - **Fix:** Section title file seeded as primary, dependent files follow in order - **Fix:** enrichBlastFindingFiles() fills empty files arrays and recomputes finding IDs - **Fix:** Pre-narration enrichment gives narrator real file paths to work with - **Fix:** Ghost Brief™ now generates after blast-only Ghost Watcher™ runs - **Fix:** briefPromptCount and blastFileCount now reflect actual findings ## What's New in v9.3.1 Ghost Watcher™ now emails the customer after every scan. - **New: Findings email** -- When Ghost Watcher™ finds issues, it emails a notification with per-finding detail (severity badge, title, affected files, and description) plus a severity summary (critical / high / medium / low counts). - **New: Clean scan email** -- When Ghost Watcher™ finds zero findings, it emails a confirmation that the commit is clean. - Both emails are fire-and-forget and never block the CI pipeline. ## What's New in v9.3.0 Cost-aware streaming vs batch transport menu on every scan mode, plus batch retrieval commands and transport metadata in every report. - **New: Streaming vs Batch transport menu** -- Every scan mode that calls the Anthropic API now opens with a cost-aware choice: run live (streaming) for real-time results, or submit to the Message Batches API for half-price processing you retrieve when ready. The menu shows the loaded file count, a token estimate, and the streaming and batch cost side by side. Pass --stream or --batch to skip the menu; CI and Ghost Watcher runs default to batch automatically. - **New: Batch retrieval commands** -- ghost batch-status lists every pending batch and whether it is ready. ghost batch-retrieve pulls a finished batch and produces the same report files a live run would have. - **New: Dynamic pending-batch menu rows** -- The main menu injects a row per pending batch, grayed out while processing and selectable once ready, so you can retrieve straight from the menu. - **New: Transport metadata in every artifact** -- The findings.json sidecar carries a transport block (method, timestamps, version), and the PDF, Markdown, TXT, and Ghost Brief HTML each carry a one-line footer, for example "Scan transport: Streaming (completed 9:49am)". - **New: Question mode batch support** -- Question mode joins Blast Radius in supporting the transport menu, batch submission, and batch retrieval. - **Fix: Deterministic output** -- Every Anthropic call site now sets temperature 0, so repeated scans of the same codebase produce consistent results. - **Fix: Setup wizard tier cap** -- The first-run wizard now defaults the context size to your actual tier cap (Open 50K, Pro 100K, Team 150K, Enterprise 200K) instead of a hardcoded 50K, sourced from the single canonical tier-cap table. - **Fix: Accurate source identity** -- The loader records the source of every scan (ZIP path for archive loads, owner and repo for GitHub loads), and batch repository names are derived from the git remote origin rather than the current directory name. ## What's New in v9.2.3 Ghost Brief™ now generates correctly after Batches API scans. - **Fix: Ghost Brief generates after batch Blast Radius** -- Raw batch output is now passed through the narrator before finding extraction, replicating the old streaming path. Ghost Brief receives findings with populated file arrays and generates prompts correctly. ## What's New in v9.2.2 Critical fix for Ghost Watcher™ Batches API on GitHub Actions. - **Fix: Replaced Anthropic SDK batch transport with native fetch** -- The SDK's internal HTTP client drops connections on GitHub Actions runners when calling /v1/messages/batches. Native Node.js fetch succeeds reliably. All four batch operations (submit, poll, cancel, preflight) now use native fetch directly. ## What's New in v9.2.1 Ghost Watcher™ batch submission is now more resilient to transient network drops in GitHub Actions. - **Fix: submitBatch retry with backoff** -- Batch submissions now retry up to 4 times with exponential backoff (2s→4s→8s) on transient connection errors (Premature close, ECONNRESET, socket hang up). Previously the SDK's 2 built-in retries were insufficient for CI network flakiness. - **New: Preflight reachability check** -- Before uploading the full codebase context, Ghost Watcher™ sends a tiny 1-token test batch to verify the Anthropic Batches API is reachable. If the endpoint is unreachable, the run exits cleanly with a clear diagnostic message instead of burning a 0.6MB upload. - **New: Body size logging** -- The batch request body size is logged on every submission so CI logs show the real payload size. ## What's New in v9.2.0 Ghost Watcher™ now uses the Anthropic Message Batches API for Blast Radius and Conflict Detection -- eliminating Premature close failures on large codebases entirely. - **Major: Anthropic Batches API** -- Ghost Watcher™ submits scans as async batch requests processed server-side. No streaming connection to drop. No more Premature close errors regardless of codebase size. - **Major: Auto-resume** -- If a GitHub Actions job is interrupted before results arrive, Ghost Watcher™ automatically retrieves and delivers the results on the next commit push. No manual intervention required. - **New: Incomplete run emails** -- When a run is interrupted, you receive an email explaining what happened and confirming results will be delivered automatically. - **New: Resume notification emails** -- When Ghost Watcher™ detects and resumes an incomplete scan, you receive emails at resume-detected and resume-complete milestones. - **New: Pending portal state** -- Ghost Portal shows a pending state entry immediately when a batch is submitted, rather than silence while processing. - **New: Configurable batch settings** -- Control poll interval and timeout via ghost-watcher.yaml batch section. - **Fix: GitHub Actions timeout raised to 90 minutes** -- Accommodates batch polling window. ## What's New in v9.1.4 Ghost Watcher™ Blast Radius and Conflict Detection now complete successfully in CI environments. - **Fixed: Premature close on Blast Radius and Conflict Detection in CI** -- All three Anthropic API stream calls in the analyst have been switched to non-streaming (stream: false) in CI environments. This eliminates mid-response stream closure on large context windows. Local dev still uses streaming as before. ## What's New in v9.1.3 Ghost Watcher™ now uses non-streaming Anthropic API calls in CI environments, eliminating Premature close failures on large context scans. - **Fixed: Premature close in CI** -- Ghost Watcher™ now detects CI environments and switches to non-streaming API calls (stream: false). This eliminates stream timeouts on large context windows (150K Team, 200K Enterprise). Local dev still uses streaming as before. ## What's New in v9.1.2 Ghost Watcher™ now correctly uses the full tier token allowance in GitHub Actions CI environments. - **Fixed: Ghost Watcher™ CI context cap** -- Team tier now uses 150K tokens in CI (was incorrectly clamped to 50K Open tier default). Enterprise now uses 200K. Added `ignoreSavedContext` flag to bypass stale configstore values on ephemeral CI runners. - **Fixed: Stream retry on transient errors** -- Premature close, ECONNRESET, and socket hang up errors now retry up to 2 times with exponential backoff before failing. Reduces false zero-findings runs caused by network blips in CI. ## What's New in v9.1.0 Ghost Architect™ scanned its own codebase using Ghost Brief™ and fixed 7 issues found in dogfood pass 10. Ghost Watcher™ confirmed zero findings after the push. - **Critical fixed:** Prompt injection defense hardened in consultant profile sanitization -- Unicode NFC normalization, zero-width character rejection, bidirectional override blocking - **High fixed:** Temp directory leak in Commit Forecast -- try-finally cleanup on all exit paths - **High fixed:** API error masking in agent loop -- `ok` field added to result, test coverage added - **High fixed:** LLM plan validation -- findings can no longer be silently dropped from reports without disclosure - **High fixed:** Manifest concurrent write race -- content verification added to post-write check - **High fixed:** Audit log failure threshold lowered from 3 to 1 -- warns on first failure with timestamp - **High:** File prioritizer error handling already present from pass 9 ## What's New in v9.0.8 ### 🔭 Ghost Watcher™ — Automatic commit monitoring **Fixes in v9.0.8:** - Team and Enterprise tier now correctly applies 150,000 token context cap in CI - License validation works on ephemeral GitHub Actions runners (fingerprint bypass in CI) - Custom branches added in Enable Watch wizard now correctly appear in GitHub Actions workflow trigger - PR comment portal link now uses correct lowercase slug - Enable Watch wizard version-pins the workflow to the installed Ghost version Ghost Watcher™ monitors every commit automatically. When a developer pushes to GitHub, Ghost fires — analyzing changed files against the full codebase, surfacing findings, and generating a Ghost Brief™ prompt pack. Results land in Ghost Portal before the PR reviewer opens the tab. **Available on Ghost Team and Ghost Enterprise memberships.** ## What's New in v8.2.5 **Ghost Partner Profiles — now in the top-level menu** Ghost Partner Profiles white-label every Ghost Architect output under your firm name. Your branding. Your methodology. Your billing rates. Across all seven report types. New in v8.2.5: Ghost Partner Profile is now accessible from the very first Ghost menu — no codebase selection required. Select a profile, activate it for your session, and every scan you run uses your branding automatically. # Access from the top-level menu ghost # Select: Ghost Partner Profile # Or create a profile directly ghost --create-profile # Or load a specific profile for one run ghost --profile ~/.ghost/profiles/my-profile.yaml # Set a profile as your default ghost --set-default-profile my-profile-slug **Executive Brief** — one-page business intelligence report for non-technical stakeholders. Health score 0-100, plain-language executive narrative, manual vs AI-assisted cost comparison table, three-phase remediation sequence. Available on Pro Max, Team Max, Enterprise Max. **Ghost Brief** — after every scan, Ghost generates a prompt pack. One prompt per finding. Structured. Sequenced. Blast-radius-aware. Paste into any AI coding tool. Available on Pro Max, Team Max, Enterprise Max. ## What's New in v8.1.2 **Ghost Brief™ dogfood pass 4.** Six fixes: prompt injection via consultant profile fields (narrator.js), freemium quota bypass closed (tier-gates.js), seat registration verification race fixed (enterprise.js), silent Tier 2 detector failures now surface to stderr, GitHub Enterprise Server URL parsing fixed for team-sync, GitHub API rate limit retry with user-facing progress messages and continue/stop prompt. ## What's New in v8.1.0 **Ghost Brief™ dogfood pass 1 and 2.** Ghost Architect™ scanned its own codebase using Ghost Brief™ and Claude Code fixed 19 findings across two iterative passes. Zero critical findings remaining. Test suite expanded with 4 new smoke test files. ## What's New in v8.0.3 **Ghost Brief™ prompt quality overhaul.** Prompts now include full remediation context, fix steps, constraints, confidence score, and effort estimate extracted directly from scan findings. Validation hints are now finding-specific. ## What's New in v8.0.2 ### Ghost Brief™ Convert any Ghost scan into a validated, blast-radius-aware Claude Code prompt pack. Feed `ghost-brief.json` directly into Claude Code, Cursor, or Copilot. Ghost briefs the AI. The AI fixes the code. **Run it:** ghost --brief --input=ghost-report.json Or select Ghost Brief™ from the interactive menu after any scan. Ghost auto-detects your most recent findings file and confirms before generating. Ghost reads your findings JSON, converts each finding into a structured prompt with blast-radius ordering, validation hints, and file context — and writes `ghost-brief.json` to disk. If Ghost Portal™ is configured, the Brief is pushed automatically. Ghost Brief™ requires Ghost Pro Max or higher. ## Works on any codebase Ghost is platform agnostic and language agnostic. Used in production on: - **Adobe Commerce / Magento 2** (most common) - **Shopify / Shopify Plus** - **Oracle Commerce / ATG** - **SAP Commerce (Hybris)** - **Salesforce Commerce Cloud** - **Microservices architectures**: distributed systems, event-driven platforms - **Mobile apps**: React Native, Expo, Swift, Kotlin - **Game engines and runtimes**: Unreal, raylib, EASTL - **Any language**: PHP, Java, Python, Node.js, TypeScript, Ruby, Go, C++, C#, Swift, Kotlin If it's code, Ghost reads it. ## Nine modes **💬 Question** Ask anything about the codebase in plain English. Ghost answers like a senior architect who has read every file. **🗺 Points of Interest Scan** Auto-generates a structured intelligence report organized into four categories: - 🔴 **Red Flags**: load-bearing technical debt, ticking time bombs, security risks - 🏛️ **Landmarks**: core logic everything else orbits around - ⚰️ **Dead Zones**: abandoned code nobody knows if they still need - ⚡ **Fault Lines**: fragile seams where assumptions don't match Every finding is severity-rated, includes effort and complexity estimates, a dollar-cost remediation range, and concrete fix steps. Findings are verified against actual source code; false positives are dropped or flagged before they reach the report. **💥 Blast Radius Analysis + Rollback Plan** Pick any file, class, method, or coordinated change set. Ghost maps the full impact (direct dependencies, ripple effects, danger zones, silent-failure risks) and produces a complete rollback plan so your team is protected if anything goes wrong. The rollback plan includes: - Pre-change snapshot of critical state - Numbered step-by-step rollback instructions with time estimates - Total rollback time estimate - Point of No Return: exactly when rollback becomes harder or impossible - Who to notify and what action they must take - Smoke test checklist to confirm rollback succeeded **⚡ Conflict Detection** Scan a codebase for places where two or more parts make conflicting assumptions about the same thing: shared config keys, API contracts, database schemas, data shapes, constants. Each candidate conflict is verified against the source code and rated as confirmed, possible, or false positive. Useful before deployments, integration work, or migrations. **🔮 Commit Forecast** Analyze your proposed changes against the production codebase and forecast the Blast Radius and Conflict impact before you commit or push. Ghost does not apply changes, does not commit, does not push — it shows you what *would* happen if you did. Two entry surfaces: - **Pre-commit:** Ghost auto-discovers your working-tree changes via `git diff --name-only HEAD`. Run it before every push. No arguments needed. - **Offline / received files:** Point Ghost at a folder of proposed files that mirrors the repo structure. Covers the offshore-review use case: an architect receives files from an offshore team and wants to assess impact before accepting them. **🧪 Prompt Triage** Audit prompts and prompt-driven workflows in your codebase for structural issues: missing context, ambiguous instructions, brittle assumptions, token bloat. Designed for teams building LLM-integrated applications who need to catch prompt drift before it reaches production. **🔍 Recon (sizing only)** A pre-engagement sizing report. Single planner call (~$0.05), no full scan. Produces a markdown or PDF deliverable describing what a full scan would surface, sized against the actual codebase. Useful for: - Quoting a fixed-fee engagement before committing scan budget - Showing a prospect what pre-engagement diligence looks like - Quick scoping during discovery calls When a Ghost Partner™ profile is loaded, recon reads in the consultant's voice and emphasizes their methodology's priorities. **🔍 Compare Reports** Diff two saved Ghost reports (before and after a refactor, upgrade, or fix cycle) to see exactly what moved: which findings were resolved, which are new, and where severity shifted. Quantifies remediation progress. **📊 Project Dashboard** Track remediation velocity across all your scanned projects. Shows critical/high/medium/low finding counts, resolved vs. remaining, and progress over time. Pro+ feature. ## 👥 Ghost Partner™: White-label consultant profiles Consultants and agencies can run scans on behalf of their client engagements with their own branding, methodology, and rates baked into the report. A **Ghost Partner™ profile** is a YAML file describing the consultant: their priorities, anti-patterns, red flags, billing rates, brand color, and contact info. When a profile is loaded with `--profile`, Ghost: - Applies the consultant's lens to the analysis (findings reflect their methodology) - Renders the report in the consultant's voice (no Ghost Architect branding in the output) - Uses the consultant's billing rates for cost estimates (per-tier overrides supported) - Produces a fully white-labeled PDF with the consultant's logo, accent color, and footer ### Creating a profile: the easy way Don't hand-write YAML. Use the built-in profile wizard: ghost --create-profile Ghost walks you through a short interactive flow asking for your name, firm, brand color, optional logo path, top priorities, anti-patterns, red flags, and per-profile billing rates. The wizard saves a fully-formed YAML file to `~/.ghost/profiles/{slug}.yaml` and prints the path you'll use to invoke it. You can also reach the wizard from the main menu: - Run `ghost` - Pick **Manage Ghost Partner Profiles** - Pick **Create new profile** The same menu lets you edit existing profiles, set a default profile (auto-applied to every scan unless overridden), open a profile in your `$EDITOR` for fine-grained YAML edits, or delete profiles you no longer need. ### Using a profile Three ways, in priority order: # 1. Per-run, explicit path ghost --profile ~/.ghost/profiles/my-profile.yaml # 2. Set a default: auto-applied to every scan ghost --set-default-profile my-profile ghost # default profile loads automatically ghost --no-profile # opt out of the default for one run ghost --clear-default-profile # remove the default # 3. List what you have ghost --list-profiles When a profile is active, the main-menu input options show a `[profile: ●]` annotation so you always know which lens is loaded before you scan. ### Editing a profile by hand Profiles are plain YAML files in `~/.ghost/profiles/`. You can edit them in any editor. Save your changes and the next scan picks them up: no rebuild step. ### Bring your own methodology document If you already have a written methodology (a Google Doc, a one-pager, a Notion page, a markdown audit guide) you don't need to use the wizard. Save the document as a `.md` or `.txt` file anywhere on your machine and point Ghost at it directly: # Markdown methodology: Ghost looks for ## Priorities, ## Anti-patterns, # ## Red flags, and ## Branding sections, plus optional YAML frontmatter ghost --profile ~/Documents/my-audit-methodology.md # Plain text: Ghost extracts the structure via Claude and caches the result ghost --profile ~/Documents/my-audit-methodology.txt Ghost auto-detects the format from the file extension: - **`.yaml` / `.yml`**: parsed directly. Free, instant. (This is what the wizard produces.) - **`.md` / `.markdown`**: Ghost looks for YAML frontmatter (between `---` markers at the top) and recognized section headings (`## Priorities`, `## Anti-patterns`, `## Red flags`, `## Branding`). Bullets under those headings become list entries; key/value lines under `## Branding` become the branding object. Anything else is preserved as prose context for the scan. Free, instant. - **`.txt` / anything else**: full prose extraction via Claude. Ghost reads the document, extracts the canonical schema, and caches the result at `~/.ghost/profiles/.cache/{hash}.json`. The extraction LLM call costs a few cents the first time; subsequent scans with the same file are free (the cache is keyed on content hash, so editing the file invalidates the cache automatically). **Recommended location:** save imported methodology files in `~/.ghost/profiles/` alongside wizard-generated profiles. They'll show up in `ghost --list-profiles` and in the menu's profile picker, and you can manage them all from the same place. **Recommended workflow:** start with whatever doc you already have. Run a scan with `--profile` pointing at it. Review the report. If you want to tighten the methodology, run `ghost` → **Manage Ghost Partner Profiles** → **Edit existing profile** to refine the structured fields, or open the cached YAML in your editor for direct edits. ### Profile schema Example of the canonical YAML schema (what the wizard produces, what `.md` and `.txt` files get extracted into): name: "Magento & Shopify Performance, Security & Server Cost Audit" author: "Satish Mantri" organization: "OSCProfessionals" priorities: - Site speed and Core Web Vitals on category and product pages - Server cost efficiency - Security exposure - Database query efficiency: N+1 patterns, missing indexes # ... anti_patterns: - Custom code overriding Magento core without preference patterns - Direct database queries bypassing the ORM # ... red_flags: - Missing Magento security patches - Admin URL using the default /admin path with no IP allowlist # ... # Per-profile billing rates (optional, partial overrides supported) rates: junior: 50 mid: 90 senior: 150 # White-label branding branding: company_name: "OSCProfessionals" accent_color: "#0B5394" footer_text: "OSCProfessionals: Performance, Security & Server Cost Audit" confidentiality: "Confidential: Prepared for client engagement use only" Profiles can be authored as `.yaml`, `.yml`, `.md`, or `.txt`. Markdown and plain-text profiles are extracted via Claude into the canonical schema and cached locally. **Ghost Partner™ profiles are a paid-tier feature** (Pro, Team, Enterprise). The free Open tier produces neutral Ghost-branded reports. ## Privacy and security **Your code never leaves the analysis moment.** Ghost Architect™ works like a filter: your codebase goes in, the analysis comes out, and the code itself is immediately discarded. It is never stored on any server, never written to any database, never retained between sessions. Think of it as running your code through an expert analyst who reads it, gives you the report, and forgets everything they saw. - **No code retention:** your codebase passes through Claude's analysis and is gone. Anthropic does not store API call content for training under standard API terms. - **Local config only:** your API key and all settings are stored exclusively in a config file on your own machine. They are never transmitted anywhere except to Anthropic's API to authenticate your calls. - **No third-party sharing:** Ghost connects only to Anthropic's API (and optionally GitHub for repo loading). No telemetry, no analytics, no phone-home. - **Reports stay local:** saved reports are written to your machine only. - **Source-available:** you can read every line of Ghost Architect's code and verify these claims yourself. This makes Ghost safe to use on proprietary enterprise codebases, client work, and confidential systems. ## Tier comparison | Feature | Open (free) | Pro | Pro Max | Team | Team Max | Enterprise | Ent. Max | |---|---|---|---|---|---|---|---| | Question | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Points of Interest scan | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Blast Radius + Rollback | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Conflict Detection | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Commit Forecast | 1 free / install | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Prompt Triage | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Recon sizing | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Reports saved as MD / PDF / TXT | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Project labels + history tracking | — | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Project Dashboard | — | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Compare Reports (before/after) | — | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Inheritance Audit (deal-grade) | — | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Ghost Partner™ profiles | — | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | White-label PDF rendering | — | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Per-profile billing rate overrides | — | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **Ghost Brief™** | — | — | ✅ | — | ✅ | — | ✅ | | **Unified Brief (all seats)** | — | — | — | — | ✅ | — | ✅ | | **Ghost Partner co-engagement** | — | — | — | — | — | — | ✅ | | Team sync features | — | — | — | ✅ | ✅ | ✅ | ✅ | | Custom enterprise gating | — | — | — | — | — | ✅ | ✅ | | Context cap | 50K tokens | 100K | 100K | 150K | 150K | 200K | 200K | | Pricing | Free, BYOK | $25/mo | $99/mo | $399/mo | $799/mo | $1,200/mo+ | $2,500/mo+ | **Ghost Brief™ tiers at a glance:** | Tier | Price | Ghost Brief™ | |---|---|---| | Ghost Open | Free | ❌ | | Ghost Pro | $25/mo | ❌ | | Ghost Pro Max | $99/mo | ✅ | | Ghost Team | $399/mo | ✅ | | Ghost Team Max | $799/mo | ✅ Unified Brief | | Ghost Enterprise | $1,200/mo | ✅ | | Ghost Enterprise Max | $2,500/mo | ✅ + Ghost Partner | The free Open tier is fully featured for individual scans. Project history, before/after comparison, white-label consultant rendering, deal-grade Inheritance Audit, and team sync are paid-tier capabilities. Ghost Brief™ is available on Pro Max and above. Pricing details and sign-up at [ghostarchitect.dev](https://ghostarchitect.dev). ## Before you install: getting your API key Ghost Architect™ uses the Anthropic API directly. This is **not** the same as a Claude.ai subscription: it is a separate pay-as-you-go developer account with no monthly fee. **Step 1: Create an Anthropic API account.** Go to [console.anthropic.com](https://console.anthropic.com) and sign up. You can use the same email as a Claude.ai account: they are separate accounts under the same company. **Step 2: Add a payment method and load credits.** The API is pay-as-you-go. Add $5 to $10 to get started: that's enough for many full sessions. **Step 3: Generate an API key.** In the console, go to **API Keys → Create Key**. Name it (e.g. `ghost-architect`). Copy the key: it starts with `sk-ant-` and is only shown once. ## Two ways to provide your API key **Method 1: Setup wizard (recommended for most users).** Run `ghost` and the interactive wizard handles everything on first launch. Your key is stored locally, masked during entry, and never displayed again. **Method 2: Environment variable (power users and CI/CD).** Set `ANTHROPIC_API_KEY` before running and Ghost skips the wizard entirely. # One-time in your current terminal session export ANTHROPIC_API_KEY=sk-ant-xxxx ghost # Inline for a single run ANTHROPIC_API_KEY=sk-ant-xxxx ghost # Permanent: add to your shell profile echo 'export ANTHROPIC_API_KEY=sk-ant-xxxx' >> ~/.zshrc source ~/.zshrc You can also set `GITHUB_TOKEN` the same way for private repo access: export GITHUB_TOKEN=ghp_xxxx ## What does it cost to use? Ghost shows a cost estimate **before** every scan and the actual cost **after**. No surprises. | Operation | Codebase size | Est. cost (Sonnet 4.6) | |---|---|---| | Recon (sizing only) | Any | ~$0.05 | | Question exchange | Any | ~$0.02 to $0.08 | | Commit Forecast | Any | ~$0.15 to $0.60 | | Points of Interest scan | Small (~50 files) | ~$0.15 | | Points of Interest scan | Medium (~150 files) | ~$1.50 | | Points of Interest scan | Large (~500 files) | ~$4.00 | | Blast Radius Analysis | Any | ~$0.10 to $0.30 | | Conflict Detection | Medium | ~$0.50 to $1.50 | **The real comparison:** a senior architect doing the same analysis manually bills $3,000 to $5,000. Ghost delivers comparable depth in minutes for under a few dollars. A typical full session (one POI scan, two blast radius analyses, and several questions on a medium enterprise codebase) runs roughly **$1.50 to $3.00 total.** Ghost uses **Claude Sonnet 4.6** by default. Switch to **Claude Opus 4.7** in settings for maximum analytical depth on the most complex codebases. At the end of every session, Ghost displays a summary of every operation run and the total session cost. ## Command-line flags For a complete, always-current flag reference, run `ghost --help` in your terminal. `--help` is the source of truth for every supported flag. ghost [options] Options: --max-context Override the context cap in tokens. Clamped to your tier limit. --exclude "" Exclude files matching a glob pattern. Repeatable. Example: --exclude "seeds/**" --exclude-presets a,b Apply named exclusion preset(s). Run `ghost --help` to see available presets. Ghost Partner™: white-label consultant profiles: --profile Load a profile from .yaml/.yml/.md/.txt and apply the consultant's lens + branding to all scans. --no-profile Run without any profile, even if a default is set. --create-profile Launch the interactive profile wizard, save the result to ~/.ghost/profiles/, then exit. --list-profiles List profiles in ~/.ghost/profiles/ and show which one is currently the default. Then exit. --set-default-profile Set the default profile by slug (filename without .yaml). Auto-applied to every scan unless --profile or --no-profile overrides it. --clear-default-profile Remove the default profile setting. Misc: --version, -v Print version. --help, -h Print help. When flags are omitted, Ghost runs interactively and uses your configured defaults. ## Workflows ### New Project Onboarding You've inherited a codebase you've never seen. 1. Clone or download to your machine 2. Run Ghost → Local directory or ZIP 3. Run Points of Interest scan 4. Save the report, label it with the project name 5. Read the findings before writing a line of code **Result:** in minutes you understand what's fragile, what's critical, what's dead weight, and where not to touch without a plan. Two weeks of senior-architect ramp-up, compressed. ### Pre-Engagement Diligence (consultants) *(Pro+)* Before quoting an engagement, run Recon to size the codebase and identify high-risk areas. Then if the prospect commits, run a full scan with your Ghost Partner™ profile loaded. 1. Recon scan with --profile loaded → ~$0.05, ~30 seconds 2. Send the recon PDF to the prospect (white-labeled, your branding) 3. On engagement, run full POI / Blast / Conflict scans with the same profile 4. Reports go to the client carrying your name, your methodology, your rates **Result:** a pre-engagement deliverable that establishes your value before you've billed an hour. Ghost's planner reads the codebase through your methodology lens and produces a sizing report the prospect can use to scope the engagement. ### Before / After Validation *(Pro+ for the Compare feature)* Confirm changes actually improved the codebase, and didn't introduce new problems. Round 1, Before: 1. Run POI scan, save report with label "pre-refactor" 2. Note all findings and their severity Make your code changes. Round 2, After: 1. Run POI scan on the same project 2. Save report with label "post-refactor" 3. Open both MD reports side by side (or use Compare Reports) 4. Confirm resolved issues are gone 5. Check no new issues were introduced **Result:** a clear before/after record of code quality improvement. Every finding resolved is documented. Every new issue introduced is caught before it reaches production. ### Pre-Change Risk Assessment Before touching anything significant (a shared interface, a payment class, a core configuration file) run a Blast Radius Analysis first. 1. Run Ghost → Blast Radius Analysis 2. Enter the file, class, or method (or pick multiple for a coordinated change set) 3. Read the full impact map and rollback plan 4. Make your change with full awareness of consequences 5. Follow the rollback plan if anything goes wrong **Result:** no more surprise production incidents from "minor" changes. The rollback plan means you're never stuck at 2am with no path back. ### Pre-Deployment Conflict Audit Run Conflict Detection before any major release, integration, or migration. 1. Run Ghost → Conflict Detection 2. Verify confirmed conflicts before deployment 3. Resolve config / schema / contract mismatches first 4. Save the report as part of the release record **Result:** catches contract drift, config-key mismatches, and schema disagreements before they become production incidents. ### Pre-Push Commit Forecast Before every push, know what your changes will break. 1. Make your changes in your working directory (as normal) 2. Run Ghost → Commit Forecast → Pre-commit 3. Ghost auto-detects your changed files via git diff 4. Read the blast radius and conflict forecast 5. Fix anything critical before you push **Result:** container-to-stage cycles drop from five to one. You find out what breaks before the push, not after a failed deploy. The offshore version of the same workflow — point Ghost at a folder of received files instead of your working tree, and assess impact before accepting the changes. ### Ongoing Technical Debt Tracking *(Pro+)* Run a POI scan at the start of every sprint or major milestone. Save each report with a date label. The Project Dashboard then shows your debt trajectory over time. ghost-poi-project-name-sprint-1-2026-03-01.txt ghost-poi-project-name-sprint-5-2026-05-01.txt ghost-poi-project-name-sprint-10-2026-07-01.txt **Result:** a timestamped record of how technical debt is growing or shrinking. Useful for client reporting, delivery reviews, and justifying refactoring investment. ## Input methods - **Local directory:** point at any folder using a path or drag-and-drop into Terminal - **ZIP file:** load a codebase archive directly - **GitHub repo:** any public repo, or private with a GitHub token ## Report outputs Every scan saves three formats simultaneously to `~/Ghost Architect Reports/`: **📄 Plain text (.txt):** terminal-friendly raw output. Opens anywhere, works in any system. **📋 Markdown (.md):** beautifully formatted document with severity badges, tables, and proper structure. Renders in VS Code, GitHub, Obsidian, Notion, or any Markdown viewer. **📑 PDF (.pdf):** branded professional report with cover page, color-coded severity sections, formatted remediation table, page numbers, and footer. The client-ready deliverable. When a Ghost Partner™ profile is loaded, the PDF is fully white-labeled with the consultant's branding. Every report is timestamped. Reports are automatically organized by project label (paid tiers) for easy comparison across scans. ## Private repository access Ghost supports private GitHub repositories via a Personal Access Token. **Setup:** 1. Go to `github.com/settings/tokens` 2. Click **Generate new token (classic)** 3. Select the **repo** scope 4. Copy the token (starts with `ghp_`) 5. Run Ghost → **Reconfigure Ghost Architect**, enter your token Your token is stored locally and never transmitted anywhere except GitHub's API. **Alternative:** for very large or sensitive private repos, download as ZIP and use the ZIP file loader. No authentication required and often faster. ## Philosophy Ghost Architect™ is a **thinking accelerator**, not a code generator. The goal is to help developers and their organizations think more deeply about systems they own. Every enterprise codebase contains institutional knowledge (patterns, decisions, warnings, traps) that lives nowhere but the code itself. When the developer who built it leaves, that knowledge disappears. Ghost surfaces it before it's gone, and makes it available to everyone who comes after. It is not here to replace senior architects. It is here to give them a running start. ## Built with - [Claude API](https://docs.claude.com) by Anthropic - [Inquirer.js](https://github.com/SBoudrias/Inquirer.js) for interactive CLI prompts - [Octokit](https://github.com/octokit/octokit.js) for GitHub API integration - [Chalk](https://github.com/chalk/chalk) and [Figlet](https://github.com/patorjk/figlet.js) for terminal UI - [Boxen](https://github.com/sindresorhus/boxen) for terminal panels - [Configstore](https://github.com/yeoman/configstore) for local config management - [Ora](https://github.com/sindresorhus/ora) for terminal spinners - [ADM-ZIP](https://github.com/cthackers/adm-zip) for ZIP file extraction - [PDFKit](https://github.com/foliojs/pdfkit) for PDF report generation ## Support Questions: [support@ghostarchitect.dev](mailto:support@ghostarchitect.dev) Pricing and upgrades: [ghostarchitect.dev/pricing](https://ghostarchitect.dev/pricing) Documentation and product info: [ghostarchitect.dev](https://ghostarchitect.dev) ## Ghost Portal™ Ghost Portal™ is a web-based dashboard that displays your scan reports in a living, shareable interface — organized by mode, project, and severity. Every scan you run automatically pushes its artifacts to your private GitHub repository and appears in your Portal within seconds. **Activate Ghost Portal™ (Pro and above)** 1. Visit [ghostarchitect.dev/portal-setup](https://ghostarchitect.dev/portal-setup) 2. Click **Connect GitHub** — Ghost will request permission to create one private repository in your account 3. Your Portal goes live immediately at `ghostarchitect.dev/portal-{your-github-username}` 4. Run any Ghost scan — reports push automatically, no additional configuration needed **What your Portal includes** - All scan modes: Points of Interest, Blast Radius, Conflict Detection, Commit Forecast, Fix Forecast, Inheritance Audit, Prompt Triage, and more - Per-project remediation tracking with progress over time - Client-ready PDF reports accessible from any browser - No file attachments — share a URL, not a document Ghost Portal™ is available on Ghost Pro, Team, and Enterprise tiers. Ghost Open users can upgrade at [ghostarchitect.dev/pricing](https://ghostarchitect.dev/pricing). *"The best architects don't write all the code. They help you understand what you have."* ## License Ghost Architect™ is licensed under the Business Source License 1.1 (BUSL-1.1). Free for personal, non-commercial, and small team use (up to 5 users). Commercial use beyond these limits requires a paid license: see [ghostarchitect.dev](https://ghostarchitect.dev). After 4 years from each version's release date, the code converts to GPL v3. See [LICENSE](./LICENSE) for full terms. **Copyright © 2026 Ghost Architect. All rights reserved.** Ghost Architect™ is proprietary software. Unauthorized use, reproduction, or distribution is strictly prohibited. *Not a code generator. A thinking accelerator.*

标签：AI代码分析, Claude, CVE检测, GitHub集成, LNA, MITM代理, 代码理解, 暗色界面, 自定义脚本