{
  "markdown": "# Symvanta plugin for Claude Code\n\nOne-step setup for working in a [Symvanta](https://symvanta.com)-indexed\ncodebase. Installing this plugin:\n\n- registers the Symvanta MCP server (default `https://mcp.symvanta.com/mcp`,\n  configurable for on-prem / self-hosted, OAuth on first connection), so you do\n  not edit `.mcp.json` by hand;\n- injects standing context once at the start of every session so the agent\n  reaches for the Symvanta code-graph tools instead of shell search;\n- ships a `symvanta` skill with the full tool decision matrix and conventions;\n- adds slash commands that wrap the common graph workflows.\n\n## Commands\n\nEach command routes to the right Symvanta MCP tool so you do not have to\nremember tool names:\n\n- `/symvanta:ask [question]`: answer a behavior question (how does X work, why\n  does Y happen) via `ask_codebase`, with file citations.\n- `/symvanta:blast [symbol]`: blast-radius safety check before editing a symbol.\n- `/symvanta:trace [symbol]`: map a function's call chain, callers, and\n  dependencies.\n- `/symvanta:route [METHOD /path]`: find the handler for an HTTP route.\n- `/symvanta:status`: connection and index health snapshot (project,\n  repositories, freshness, edge counts).\n- `/symvanta:architecture`: high-level module map (Louvain functional modules,\n  PageRank hubs, cross-module coupling, and the repo-wide load-bearing functions)\n  via `map` view:\"architecture\".\n- `/symvanta:scope [symbol or change]`: pre-flight scope/impact estimate before\n  you size a change (`estimate_scope`).\n- `/symvanta:branch [name | clear]`: pin this session's reads to a tracked\n  feature branch, or clear the pin (`ref`).\n- `/symvanta:working-tree`: overlay your uncommitted edits so the graph reflects\n  changes you have not pushed (`ref` op:\"index_working_tree\").\n- `/symvanta:tests [symbol]`: find the tests that cover a symbol\n  (`list_tests_for`).\n- `/symvanta:recent [path]`: recently changed files and recent commits\n  (`history`).\n- `/symvanta:setup [local]`: write the Symvanta routing block into the\n  project's `CLAUDE.md` (or `CLAUDE.local.md` with `local`). Re-running\n  replaces the marked block in place. Subagents read CLAUDE.md, so the\n  routing reaches them too.\n\n## Install\n\nIn Claude Code:\n\n```\n/plugin marketplace add https://symvanta.com/plugin/marketplace.json\n/plugin install symvanta@symvanta\n```\n\nSign in with OAuth when prompted on first connection. Your workspace's\nGetting Started page in the Symvanta dashboard shows the exact marketplace URL\nfor your account.\n\n## Configuration\n\nThe plugin points at Symvanta Cloud (`https://mcp.symvanta.com/mcp`) by default,\nso Cloud users configure nothing. To point at a different Symvanta server, set\nthe **Symvanta MCP server URL** (`mcpUrl`) plugin option: accept or change it\nwhen you enable the plugin, or later via the `/plugin` interface\n(Symvanta -> configure). Leave it blank to fall back to the Cloud default.\n\nUse the **full endpoint URL including the `/mcp` path, with no trailing slash**,\nfor example `https://mcp.your-company.com/mcp`. A bare host or a trailing slash\nwill fail to connect.\n\n**Authentication.** Every Symvanta MCP server (Cloud, staging, or on-prem)\nadvertises its own OAuth endpoints, so Claude Code signs you in with OAuth on\nfirst connection whatever URL `mcpUrl` points at, nothing to configure in the\nplugin. On-prem supports the same OAuth flow: its gateway completes sign-in\nagainst your Symvanta cloud / license and the server verifies the issued token.\nStatic API-key / bearer-token auth also exists for headless automation, but that\nis configured on the server or in your own MCP settings, not in this plugin.\n\n## Updating\n\n```\n/plugin update symvanta@symvanta\n```\n\nThen **restart Claude Code**. Claude Code reads the plugin (including\n`hooks/hooks.json`) when it loads, not continuously, so a running session keeps\nthe previously loaded version until you restart. Until then a `/plugin update` is\ndownloaded but not active.\n\n## What runs on your machine\n\nThe plugin executes small, readable Node hook scripts locally:\n\n- [`session-start.js`](hooks/session-start.js): prints standing context once at\n  the start of a session. Sends nothing anywhere.\n- The **augment hook family** (on by default): five hooks sharing one core\n  ([`lib.js`](hooks/lib.js)). Each can only **add** context, never block:\n  every error, timeout, or missing token is a clean pass-through, and the\n  intercepted tool always runs untouched.\n  - [`grep-augment.js`](hooks/grep-augment.js): on `Grep`/`Glob`, looks up\n    matching indexed symbol **definitions** (scoped to the repo you are\n    searching, up to two identifiers from the pattern in parallel, 60s cache)\n    and adds them alongside the raw search results.\n  - [`edit-augment.js`](hooks/edit-augment.js): on `Edit`/`Write` of a code\n    file, injects the edited symbol's **blast radius** (upstream symbol count,\n    files, layers, cross-repo edges, risk tier) before the change lands; a\n    Write over an existing file lists the definitions the overwrite replaces.\n    New files and non-code files stay silent.\n  - [`read-augment.js`](hooks/read-augment.js): on the **first** `Read` of a\n    code file per session, injects the file's symbol skeleton (names, kinds,\n    line bounds) plus any architecture decision records anchored to it.\n    Repeat reads exit instantly.\n  - [`grep-rescue.js`](hooks/grep-rescue.js): after a `Grep` that found\n    **nothing**, suggests graph candidates (auto text/semantic search) so a\n    dead end becomes a lead; a grep with results exits right after the stdin\n    parse, no reads, no network.\n  - [`prompt-augment.js`](hooks/prompt-augment.js): identifier-shaped tokens\n    in your message (backticked spans, snake_case, camelCase) resolve to\n    indexed definitions at turn start. Plain prose never qualifies, so\n    conversational prompts stay silent.\n\n### What the augmenters read, send, and write, exactly\n\nTo call the graph they need your Symvanta MCP token. They reuse the one Claude\nCode already stored when you connected, so there is no setup. The read is\ndeliberately narrow and each script is short enough to audit in minutes:\n\n- They read **only** `mcpOAuth[<the Symvanta entry>].accessToken` from\n  `~/.claude/.credentials.json` (on macOS, Claude Code stores this in the\n  login Keychain instead, under service `Claude Code-credentials`, so the\n  hooks read that when the file is absent). Never your Anthropic token\n  (`claudeAiOauth`) or any non-Symvanta server's token.\n- That token is sent **only** to the Symvanta MCP server, the same place it\n  was issued for.\n- What leaves the machine per lookup: extracted identifier **terms**, matched\n  **symbol names**, and repo-relative **file paths**. Never file contents, and\n  never your message text (the prompt hook sends at most two identifier\n  tokens, not the prompt).\n- They write local files under `~/.symvanta/`, never uploaded anywhere:\n  `grep-cache/` (the 60s result cache, one small file per key),\n  `repo-cache.json` (path-to-repo memo), `keychain-cache.json` (macOS only: a\n  5-minute memo of the Keychain read, so a busy session doesn't shell out to\n  `security` on every tool call), `read-seen/` (per-session first-read\n  markers), and `grep-augment.log` (one JSONL line per run: hook, terms, repo,\n  match count, latency, cache hit). The log exists so `/symvanta:status` can\n  show what the hooks are doing; delete any of these files anytime.\n\nSwitches (restart Claude Code after changing):\n\n```\n# Supply your own token instead (dashboard -> Settings -> MCP connection ->\n# regenerate gives a Passport mcp:read token); the credentials file is then\n# never read:\nexport SYMVANTA_MCP_TOKEN=\"<token>\"\n\n# Turn the whole family off (no reads, no network on any tool call):\nexport SYMVANTA_AUGMENT=off        # the legacy SYMVANTA_GREP_AUGMENT=off also works\n\n# Or turn off individual hooks:\nexport SYMVANTA_EDIT_AUGMENT=off   # Edit/Write blast radius\nexport SYMVANTA_READ_AUGMENT=off   # first-read skeleton + ADRs\nexport SYMVANTA_GREP_RESCUE=off    # empty-grep suggestions\nexport SYMVANTA_PROMPT_AUGMENT=off # prompt term lookup\n```\n\nYou can also delete any hook's block from\n[`hooks/hooks.json`](hooks/hooks.json) to remove it entirely.\n\n`Bash` and every tool without a hook above run untouched. All code navigation\nhappens through the Symvanta MCP server over HTTPS, gated by OAuth. No\ntelemetry, no background processes.\n\n### How the Grep/Glob augmenter works\n\nEvery gate fails safe to the same pass-through, and both pass-through and\nsuccess land on \"Grep runs normally\": the hook can only add context, never\nblock or delay the search to failure. `SYMVANTA_GREP_AUGMENT=off`\nshort-circuits before anything is read or sent.\n\n```mermaid\nflowchart TD\n    A[Agent runs Grep or Glob] --> B{{Claude Code fires the PreToolUse hook}}\n    B --> D{SYMVANTA_GREP_AUGMENT = off?}\n    D -->|yes| RUN[Grep/Glob runs normally; results unchanged]\n    D -->|no, default| TX[Extract up to 2 identifiers from the pattern; derive the repo from the search path]\n    TX --> CACHE{Fresh 60s cache hit?}\n    CACHE -->|yes| F[Format matching definitions as additionalContext]\n    CACHE -->|no| TOK[Token: SYMVANTA_MCP_TOKEN, else the stored Symvanta token from ~/.claude/.credentials.json (macOS: login Keychain)]\n    TOK --> C[quick_lookup per term, in parallel, repo-scoped, hard cap 1.5s; falls back to locate mode:symbol]\n\n    subgraph cloud[\"Symvanta cloud (only the search TERMs leave your machine)\"]\n        C --> M[mcp.symvanta.com]\n        M --> DB[(Code graph in Postgres)]\n        DB --> M\n    end\n\n    C --> OK{Token valid and matches, in time?}\n    OK -->|no, error, or timeout| LOG[Append one line to ~/.symvanta/grep-augment.log]\n    OK -->|yes| CW[Cache for 60s] --> F\n    F --> EM[Emit JSON to Claude Code] --> LOG\n    LOG --> RUN\n    RUN --> O[Agent sees its grep results PLUS the Symvanta definitions, then reaches for find_node / relate / ask_codebase]\n```\n\n## Uninstall\n\n```\n/plugin uninstall symvanta@symvanta\n/plugin marketplace remove symvanta\n```\n\n## Layout\n\n```\n.claude-plugin/plugin.json   manifest + MCP server registration\nhooks/hooks.json             SessionStart + augment family wiring (PreToolUse, PostToolUse, UserPromptSubmit)\nhooks/session-start.js       standing-context injector\nhooks/lib.js                 shared augment core (auth, transport, cache, log)\nhooks/grep-augment.js        Grep/Glob definition augmenter\nhooks/edit-augment.js        Edit/Write blast-radius augmenter\nhooks/read-augment.js        first-read file skeleton + ADR augmenter\nhooks/grep-rescue.js         empty-grep graph suggestions (PostToolUse)\nhooks/prompt-augment.js      prompt identifier lookup (UserPromptSubmit)\nhooks/augment-stats.js       local activity summary for /symvanta:status\ncommands/                    slash commands (ask, blast, trace, route, status, architecture, scope, branch, working-tree, tests, recent)\nskills/symvanta/SKILL.md     tool decision matrix and conventions\nscripts/                     sync-skill.mjs (SKILL from source) + check-tool-prefixes.mjs (CI guard)\n```\n\n## License\n\nMIT\n",
  "bytes": 11087,
  "sha": "7aec0c8b0cf5789d5494f3e2a115adaf07deb9d65355bcaf280d778f830670e6",
  "repo_slug": "symvanta/claude-plugin",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_symvanta_code_graph_391b142a/readme"
}