Repository navigation
Home
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.
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
symforgefacade, which the full profile filters out becausesymforge_retrieveis its full-surface equivalent. A client reporting 40 is correct.SYMFORGE_SURFACE=compactexposes 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 initdefaults to--client alland 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::parityserves every MCP tool, resource and prompt natively. - Toolchain. Rust 1.96.0, edition 2024.
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.
| 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 | 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.
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 |
-
Install-and-Client-Setup: npm and cargo install, platforms, WSL, update,
what
symforge initwrites 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.
- Architecture-and-How-It-Works: the index, admission, lifecycle and the edit pipeline.
-
Runtime-Model: daemon,
serve, snapshots, recovery, local state.
- Tool-Reference: every tool, resource and prompt.
- Supported-Languages-and-Config-Formats: grammars, text and config parsers, workflow facts.
-
Embedding-the-Engine: the
symforge::embedfacade and its MCP-parity namespace.
- Benchmarks-and-Token-Savings: the measurements the repository records, with method and date, and the ones nobody has taken.
- Development: building, testing, CI and releases.
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.
Need the short version? The README links each topic to its page here.
Install and client setup: Install-and-Client-Setup