Graqle

Apply a governed atomic edit to a file using your project's knowledge graph. Provide a description to generate a diff, or provide a diff directly. Backup written to .graqle/edit-backup/ before any write. Default dry_run=True — never writes without explicit dry_run=False. Requires Team or Enterprise plan.

Pre-compiled intelligence gate — instant context for any module (<100ms). Returns risk level, impact radius, consumers, dependencies, constraints, incidents, and public interfaces from .graqle/intelligence/. No scanning needed. Use before modifying any file to understand blast radius. Run 'graq compile' first to populate intelligence.

Install or upgrade the GraQle governance gate for Claude Code. Creates .claude/hooks/graqle-gate.py and merges PreToolUse hooks into .claude/settings.json. Runs a self-test after install. Returns JSON with actions taken and self-test result.

Check the health of the installed governance gate. Reports whether the Claude Code governance gate hook is installed, the interpreter is valid, and the self-test passes. Returns JSON with: installed, enforcing, interpreter, interpreter_valid, self_test, hook_path.

Read GCC (Global Context Controller) status: active branch, latest commit, registry, and next steps. Equivalent to reading .gcc/registry.md + active branch commit.md.

Generate a governed code patch as a unified diff using your project's knowledge graph. Graph context activates before generation. Preflight and safety checks run automatically. Returns a CodeGenerationResult with diff patches, confidence, and audit metadata. Requires Team or Enterprise plan.

Create or switch git branches. Follows GCC naming conventions: feature-*, hotfix-*, experiment-*, spike-*. Blocked in read-only mode.

Create a git commit with a governed message. Runs patent scan before commit — blocks if trade secrets (internal-pattern-A..internal-pattern-D) are detected in staged changes. Blocked in read-only mode.

Show git diff. By default shows unstaged changes. Pass staged=True for staged diff, or base_ref to compare against a branch/commit.

Show recent git commit history with author, date, and message.

Show git working tree status — changed, staged, and untracked files.

Fetch the unified diff for a GitHub pull request via gh CLI. Returns the full diff text for code review.

Fetch GitHub pull request metadata via gh CLI. Returns title, state, author, body, branch names, additions/deletions/changed files, and review decision.

Find files matching a glob pattern. Returns file paths sorted by modification time. Use for discovering files before reading or editing.

Governance gate — run the 3-tier GovernanceMiddleware check on a diff or file. Returns tier (TS-BLOCK/T1/T2/T3), blocked (bool), gate_score (0.0-1.0), and reason. Exit code 1 equivalent when blocked=true. Used by WorkflowOrchestrator GATE stage and CI enforcement. TS-BLOCK is unconditional — no bypass, no approval overrides it.

GraQle Graph Health Check & Rebuild. Diagnoses the knowledge graph backend (local JSON/NetworkX or Neo4j), reports node/edge counts, activation strategy (chunk-level semantic vs keyword fallback), NPZ cache status, zero-vector count, and estimated reasoning latency. Optionally rebuilds the chunk_embeddings.npz incrementally (only embeds NEW chunks — never regresses existing vectors) and injects ADR→code REFERENCES and ADR↔ADR RELATED_TO links. Works for any user's project: auto-detects config from graqle.yaml.

Search file contents by regex pattern. Returns matching lines with file path, line number, and context. Supports glob filter and case-insensitive mode.

Trace the downstream impact of a proposed change through the dependency graph. Shows which components are affected and their risk level.

Ingest a specification or document into the GSM (Global Strategy Management) system. Creates a summary in .gsm/summaries/, updates .gsm/index.md, and optionally generates a graq_plan from extracted requirements.

Inspect the project knowledge graph structure. Show nodes, edges, stats, or details for a specific node.

T04 (v0.51.6): KG-write diagnostic snapshot. Reports recent write latencies, attempts, caller stacks, and current lock holders. Use this when WRITE_COLLISION surfaces to disambiguate self-race vs. external-process contention. Read-only; no I/O.

Teach the knowledge graph. Three modes: 1. 'outcome' (default) — Record a dev outcome, adjust edge weights 2. 'entity' — Add a business entity (PRODUCT, CLIENT, TEAM, etc.) 3. 'knowledge' — Teach domain knowledge (brand rules, copy, etc.) Call after completing a task, or to enrich the graph with business context.

Find lessons and past mistakes relevant to a specific operation. Returns matching lessons with severity levels and hit counts.

Session lifecycle hooks for development workflows. Call at key moments: session_start (load context), investigation_start (before debugging), fix_complete (after a fix). Returns relevant context, lessons, and graph status for each phase.

Governed memory-file read/write/index maintenance. Use for ALL ~/.claude/projects/*/memory/*.md operations. Native Write/Edit to memory paths is blocked by CG-17.

Run one or more SCORCH audit dimensions on the current page. Analyzes the live page for behavioral UX issues, accessibility violations, mobile problems, security gaps, brand inconsistency, and more. Results feed into GraQle KG. Works on any website.

Open a browser and navigate to a URL. Returns a screenshot and summarized DOM structure (buttons, links, forms, inputs, headings, landmarks). Supports authenticated sessions via saved auth profiles. This is the starting point for all Phantom computer skill interactions. Requires: pip install graqle[phantom] && python -m playwright install chromium

Click an element on the current page. Supports targeting by visible text content, CSS selector, or x,y coordinates. Returns the page state after the click (new URL, screenshot, any modals/dialogs that appeared). Requires an active Phantom session.

Auto-discover all navigable pages from a starting URL. Crawls the sidebar, navigation menus, and in-page links to build a complete route map. Returns structured list of all discovered pages with paths, titles, and authentication requirements.

Execute a multi-step user journey. Define a sequence of actions (navigate, click, type, wait, screenshot, assert, scroll, audit) and Phantom executes them in order, capturing screenshots at each step and recording pass/fail assertions. Works on any website.

Capture the current page state as a screenshot. Optionally analyze it with Claude Vision (Bedrock) to identify UX friction, visual bugs, layout issues, or answer questions about the page.

Manage Phantom browser sessions and authentication profiles. Create sessions, save/load auth states, list active sessions, and clean up resources.

Type text into a form field or input element. Can target by CSS selector, label text, placeholder text, or input name. Supports clearing existing content, pressing Enter to submit, and typing with delay (to trigger autocomplete/search-as-you-type).

Decompose a high-level goal into a governance-gated DAG execution plan. Uses the knowledge graph (impact_radius, CALLS/IMPORTS edges, causal tiers) to order steps, assign risk levels, insert governance checkpoints, and estimate cost BEFORE any code runs. Returns a reviewable ExecutionPlan — does NOT execute anything. Pass the plan_id to graq_workflow to execute.

Run governed reasoning over the knowledge graph and — if confidence is sufficient — write the compound prediction as a new subgraph into the graph permanently. Future similar queries activate the predicted subgraph directly without re-reasoning. Use for compound pattern detection, sub-threshold signal analysis, and latent failure chain discovery.

Run a governance preflight check before making code changes. Returns relevant lessons, past mistakes, applicable architectural decisions, and safety boundary warnings. Call this BEFORE modifying any file.

Profile the performance of a graq_reason invocation: per-step latency, token cost, and confidence at each reasoning phase. Identifies bottleneck steps, flags slow/expensive nodes, and writes a CodeMetric KG node so future reasoning can learn from profiling history. Returns a ProfileSummary with recommendations for tuning confidence_threshold, beam_width, or context window.

Read a file's contents with optional line range. Returns file text with line numbers. Supports offset/limit for large files.

Run graph-of-agents reasoning over the project knowledge graph. Each relevant node becomes an agent that reasons about your question, exchanges messages with neighbors, and collectively produces a synthesized answer.

Run multiple reasoning queries in parallel over the knowledge graph. Each query gets its own graph-of-agents reasoning session, running concurrently with semaphore-controlled parallelism. Use for analyzing multiple questions at once (e.g., batch code review). Set mode='predictive' to run each query through the full PSE prediction pipeline. fold_back applies to the entire batch (all-or-nothing).

Pre-publish governance gate. Composes a correctness-focused diff review with a risk prediction and returns a structured verdict (CLEAR / WARN / BLOCK) with blockers, majors, and opaque risk + confidence scores. Use before `git tag`, `pypi` upload, or VS Code Marketplace publish.

Force-reload the knowledge graph from disk. Use after external changes to graqle.json (e.g., after graq learn, graq scan, or manual edits).

Perform a structured code review on a file or diff. Checks correctness, security, style, test coverage, and complexity using the knowledge graph for impact context. Returns structured comments with severity: BLOCKER, MAJOR, MINOR, INFO.

Smart query router — classifies your question and recommends whether to use GraQle tools or external tools (CloudWatch, grep, git). Call this BEFORE investigating to get the most efficient tool strategy. Returns: category, recommended tools, confidence, and reasoning. CG-19: pass available_tools (and optionally permission_tier) to pre-filter the recommendation to tools the calling client can actually invoke.

Query live runtime observability data from your cloud environment. Auto-detects AWS CloudWatch, Azure Monitor, GCP Cloud Logging, or local Docker/file logs. Returns classified runtime events (errors, timeouts, throttles) with severity levels and hit counts. Use this for debugging production issues — it bridges the gap between static code knowledge and live system behavior.

Combined safety check: chains impact → preflight → reasoning into a single call. Gives a complete safety picture before making a change. Reasoning is only triggered if risk is medium or high (cost-aware). Equivalent to running graq_impact + graq_preflight + graq_reason in sequence.

Scaffold a new module, class, API endpoint, or test suite from a specification. Uses existing patterns in the knowledge graph to match project conventions. Returns a set of file creation requests (dry_run by default). Blocked in read-only mode.

WCAG 2.1 AA/AAA accessibility audit: color contrast scanner, missing aria-labels, focus order validation, heading hierarchy, landmark structure, form labels, image alt text. Requires: pip install graqle[scorch]

Run a full SCORCH v3 audit: screenshots + CSS metrics + 12 behavioral UX tests + Claude Vision journey psychology. Returns pass/fail, issue list, journey score. Requires: pip install graqle[scorch] && python -m playwright install chromium

Authenticated user journey audit: tests login/signup/onboarding flows, verifies redirect behavior, session indicators, post-auth navigation. Runs both unauthenticated and authenticated (if auth_state provided). Requires: pip install graqle[scorch]

Run ONLY the 12 behavioral UX friction tests (Phase 2.5). Fast, no AI cost. Tests: dead clicks, silent submissions, unexplained jargon, ghost elements, missing CTAs, copy-paste friction, missing inline editors, incomplete generation, feature discoverability, flow continuity, upsell integrity, action-response feedback.

Brand consistency audit: color palette compliance against brand rules, typography adherence, font size compliance, logo presence, spacing consistency, button/link/heading style uniformity. Uses brand_rules from ScorchConfig. Requires: pip install graqle[scorch]

Conversion funnel analysis: CTA inventory and placement (above/below fold), form quality analysis, trust signal detection (testimonials, badges), pricing clarity, micro-copy quality, exit-intent indicators. Requires: pip install graqle[scorch]

Before/after SCORCH comparison: compares current report against a previous one. Shows resolved issues, new issues, persistent issues, journey score delta, severity count changes, and overall improvement percentage. No Playwright needed — works on saved report files.

Internationalization audit: html lang attribute, hardcoded strings, RTL support, date/currency formatting patterns, mixed language content detection, Unicode support checks. Requires: pip install graqle[scorch]

Mobile-specific audit: touch target sizes (44px minimum), viewport meta validation, text readability at mobile sizes, horizontal scroll detection, input type correctness, pinch-zoom restriction check. Runs on mobile viewport only. Requires: pip install graqle[scorch]

Core Web Vitals audit: LCP, FID, CLS measurement per page, resource count/size analysis, render-blocking resource detection, DOM size, image optimization checks. Requires: pip install graqle[scorch]

Read and summarize a SCORCH audit report from disk. Returns pass/fail status, issue counts, journey score, and top recommendations.

Frontend security audit: CSP headers, exposed API keys (OpenAI/AWS/GitHub/Stripe), inline scripts without nonce, mixed content, insecure form actions, sensitive data in localStorage, missing security headers (HSTS, X-Frame-Options). Requires: pip install graqle[scorch]

SEO audit: title/meta description, canonical URLs, Open Graph + Twitter Card tags, structured data (JSON-LD), heading hierarchy, internal/external link analysis, image alt coverage, robots meta. Requires: pip install graqle[scorch]

Semantic search over knowledge graph nodes. Returns top matches by relevance.

NS-08: Compact a conversation's turn history by rolling up the N oldest turns into a single summarised record. Keeps conversations.jsonl bounded. Returns {compacted: N, retained: M, session_id, skipped}. skipped=true when turn_count < threshold (default 20). keep_last controls how many recent turns are preserved (default 10).

NS-07: List chat conversation history (most-recent first). Reads append-only JSONL from .graqle/conversations.jsonl. Returns {conversations: [{id, last_active, summary, workspace_fingerprint, turn_count, status}], count: N}. Optional filters: workspace_fingerprint (exact), limit (default 50, max 500).

NS-09: Load a prior conversation's context for injection into the current session. Returns {found, session_id, last_active, turn_count, status, summary, context_bundle}. context_bundle is a formatted text block suitable for prepending to a system prompt. Returns found=false when session_id is unknown.

Run pytest on a target (file, directory, or test ID) and parse the results into structured CodeMetric output. Captures: pass/fail/skip counts, coverage %, failing test names, and durations. Feeds the test_coverage_gate output gate. Blocked in read-only mode (executes subprocesses).

Manage a governed todo list for the current session. Replaces Claude Code's native TodoWrite with audit trail. Pass the full updated todo list each time (replacement semantics).

Download vendor JavaScript/CSS files from npm/unpkg/cdnjs by package name and version. Saves to a local vendor/ directory. Useful for offline-first Studio builds.

Check VS Code Marketplace for whether a proposed version already exists. Returns {exists, currentVersion, suggestedBump, versions}. Use before `git tag` + `vsce publish` to prevent duplicate-version CI failures.

Search the internet for solutions when the knowledge graph is stuck. REQUIRES explicit user permission before every search. Shows the user exactly what will be searched. Results are learned into the KG. Use only when graq_reason returns low confidence and you need external knowledge. Supports direct URL fetch or search engine queries.

Orchestrate multi-step coding workflows that chain multiple tools together. Built-in workflows: 'bug_fix' (grep→read→generate→write→bash→git), 'scaffold_and_test' (scaffold→generate→write→bash), 'governed_refactor' (git_branch→impact→preflight→refactor→bash→gate→git). Blocked in read-only mode for write steps.

Atomically write or overwrite a file. Uses NamedTemporaryFile→fsync→os.replace. Creates parent directories if needed. dry_run=True (default) previews without writing. Patent scan runs before write — blocks if trade secrets detected.