Skip to content
special-place-administrator edited this page Oct 11, 2026 · 7 revisions

SymForge Wiki

SymForge is a local-first MCP server that gives an AI coding agent a symbol-level view of a repository, so it can ask precise questions instead of reading whole files, running broad greps, or editing code with blind string replacement. It is written in Rust, parses with tree-sitter, holds the active workspace in memory, and answers over MCP on stdio or Streamable HTTP. Every answer carries a machine-readable trust envelope: what kind of match it was, how authoritative the source was, whether the result was complete, and where the evidence lives. When SymForge cannot answer exhaustively, it says so.

This wiki holds the full detail behind the repository README. The README is the short read; each of its topics links here.

Snapshot as of 11.7.0

Counts that move between releases are as of 11.7.0.

  • Tools. 40 advertised on the default full surface; 41 are registered. The forty-first is the compact-only symforge facade, which the full profile filters out because symforge_retrieve is its full-surface equivalent. A client reporting 40 is correct. SYMFORGE_SURFACE=compact exposes three tools: symforge, symforge_edit, status.
  • Resources and prompts. Six resources, four resource templates, eight prompts (including symforge-admin).
  • Protocol. MCP 2026-07-28 plus every legacy revision back to 2024-11-05, from a frozen allow-list. Transports: stdio, and Streamable HTTP via symforge serve.
  • Parsing. 19 tree-sitter grammars plus 6 text and config parsers.
  • Platforms. Windows x64, Linux x64, macOS arm64, macOS x64. npm needs Node 18+; there is no postinstall step.
  • Clients. symforge init defaults to --client all and knows 13: claude, claude-desktop, codex, gemini, grok, kilo-code, cursor, omp, cline, roo, vscode, copilot, continue. kilo-code, roo, vscode and continue are workspace-local.
  • Snapshots. Snapshot format 10.
  • Embedding. The engine compiles without the server behind symforge::embed; symforge::embed::parity serves every MCP tool, resource and prompt natively.
  • Toolchain. Rust 1.96.0, edition 2024.

Why SymForge

Coding agents burn most of their context window on finding code, not changing it. A whole-file read to inspect one function, a grep that returns 400 raw lines, a rename done with blind string replacement: each costs tokens, invites mistakes, and erodes trust in the result. SymForge answers the same questions from an in-memory, symbol-level index:

Instead of Use What changes
Reading a 2,000-line file get_file_context Outline, imports, consumers: decide before you read
Broad grep -r search_text Matches arrive grouped by enclosing symbol, not as raw lines
Guessing who calls a function find_references, get_symbol_context Exact call sites, imports, type usages
Find-and-replace refactors replace_symbol_body, batch_rename Structural edits validated against the index
Re-reading docs to recover a past decision search_knowledge Doc and spec evidence with heading context and file:line

What has and has not been measured about token savings, with method and date, is on Benchmarks-and-Token-Savings.

Scope. SymForge is for code intelligence and code editing. Use it before raw file reads, broad text search, or manual string edits when the task is about source code. Use the shell for builds, tests, package managers, containers and process work, and exact file reads when literal docs or config text is the thing being inspected.

What it gives an agent

Capability What it means in practice
Live repository index Symbols, references, file contents, and ranking signals (frecency from the files tool calls read, co-change from git history) held in memory and kept current by a filesystem watcher
Symbol-aware reading Outlines, imports, consumers, symbol bodies, and targeted excerpts; a raw file read becomes the exception
Search and exploration Symbols, text, paths, natural-language concepts, and AST-shaped structural patterns, with bounded output and stated ranking reasons
Repository knowledge Docs, specs, plans, ADRs, and safe configs indexed as a scope separate from code, so prose never contaminates symbol or reference results
Knowledge hygiene Read-only dossiers that separate implemented reality from declared intent; curation is preview-first and only ever writes a policy ledger, never your documents
Impact tracing Call sites, dependents, symbol diffs, changed files, and blast radius seeded from the symbols that actually changed
Structural editing Replace, insert, delete, batch-edit, and rename by indexed structure, with a pre-write snapshot and a receipt naming exactly what was written where
Snapshot warm start A current-format snapshot can skip the parse phase; a snapshot from 10.x (format 7) is an untrusted seed: it never confers authority, a copy goes under .symforge/v11/, and the first snapshot write moves the original into .symforge/quarantine/
Preventive index lifecycle One bad observation cannot publish mixed or false-current state. Candidates promote only when complete; queries run under a strict lease; answers that are not current say so
Content admission One gate decides what may be read, parsed, or disclosed; secret-bearing files fail closed to metadata-only under a versioned detector
Local daemon and HTTP serve Share one index across sessions, or run an operator server with a dashboard at /admin
Embeddable engine The indexing, search, parsing, and editing engine compiles without the server, behind a semver-stable facade plus a versioned MCP-parity namespace

Local state lives under .symforge/ in the workspace: the index snapshot and its quarantine directory, pre-write tee/ copies, idempotency records, and the optional frecency and coupling databases. The 11.7.0 server records no analytics and creates no analytics database. Nothing leaves the machine.

README and wiki

README Wiki
Purpose What SymForge is, the shape of the product, the quick start The detail: exact behavior, every flag and variable, internals
Install and symforge init Commands to copy Install-and-Client-Setup: every client, every file written
Tools The grouped list Tool-Reference: parameters, output shapes, examples
Architecture Diagram and the decisions that matter Architecture-and-How-It-Works and Runtime-Model
Embedding The facade at a glance Embedding-the-Engine
Measurements A link Benchmarks-and-Token-Savings

Claims on these pages are traced to source on the main branch and written for 11.7.0. Where a number is measured, the page names the file that records it, the version, and the date. A page that cannot cite a measurement does not state one.

Page guide

Each README section, and the page that holds its detail.

README section Wiki page
Why SymForge this page
How it works Architecture-and-How-It-Works
Install and quick start, Clients Install-and-Client-Setup
Tools Tool-Reference
Embedding Embedding-the-Engine
Index lifecycle and recovery Runtime-Model
Configuration (variables) Environment-Setup-Scripts
Configuration (daemon, serve) Runtime-Model
Benchmarks Benchmarks-and-Token-Savings
Development (languages, grammars) Supported-Languages-and-Config-Formats
Development (build, test, CI, releases) Development

Setup

  • Install-and-Client-Setup: npm and cargo install, platforms, WSL, update, what symforge init writes for each client, workspace-local clients, --scan, --apply, --serve-url, and every CLI command.
  • Agent-Setup-Prompt: a prompt to paste into your coding agent so it installs, configures the right client, confirms the connection, and prefers SymForge for code work.
  • Environment-Setup-Scripts: the reference for every SYMFORGE_* variable, with defaults, plus per-environment setup snippets.

Product and runtime

Reference

Integrating

Benchmarks

Contributing

Rule of thumb. Let SymForge own semantic code understanding and structural source edits. Let the shell own builds, tests, package managers, containers and runtime process work.

Clone this wiki locally