
SymForge
Symbol-aware code intelligence and structural editing for AI coding agents — local-first, trust-labeled, token-efficient.
Install · How it works · Tools · Embed · 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 stdio or Streamable HTTP. The same engine also compiles without the server, as a library.
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 rather than guessing confidently.
[!IMPORTANT] 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, and process work, and exact file reads when literal docs or config text is the thing being inspected.
Why SymForge
Coding agents spend most of their context window finding code, not changing it. SymForge answers those questions from an in-memory, symbol-level index:
- Read by symbol. Outlines, imports, consumers, and symbol bodies, so a whole-file read becomes the exception.
- Search with structure. Text matches arrive grouped by enclosing symbol; symbol, path, concept, and AST-pattern search come with bounded output and stated ranking reasons.
- Trace impact. Call sites, dependents, symbol diffs, and blast radius seeded from the symbols that actually changed.
- Edit structurally. Replace, insert, delete, and rename by indexed structure, validated before anything touches disk, with a pre-write snapshot and a receipt naming what was written where.
- Keep knowledge separate. Docs, specs, ADRs, and safe configs are indexed as their own scope, so prose never contaminates code results.
- Fail closed on secrets. One admission gate decides what may be read or disclosed; secret-bearing files drop to metadata-only.
Details: Home, Why SymForge and What it gives an agent.
How it works
%%{init: {"flowchart": {"htmlLabels": false, "wrappingWidth": 400}}}%%
flowchart TD
accTitle: SymForge architecture
accDescr: MCP clients reach the server over stdio or HTTP, embedders call the engine in-process. Startup restores a current-format snapshot or treats an older file as an untrusted seed, then the preventive lifecycle and admission scout feed the live index, which backs the tool, read-gate, and edit lanes.
subgraph Clients["Clients"]
MCP["MCP clients\nClaude · Codex · Gemini\nCursor · Grok · Kilo"]
LIB["Embedding platforms\nsymforge::embed, no MCP"]
end
subgraph Surfaces["Server surfaces"]
STDIO["stdio MCP server"]
HTTP["symforge serve\nStreamable HTTP\n/mcp + /admin"]
DAEMON["optional shared daemon\nloopback, token auth"]
end
subgraph Startup["Index startup"]
SNAP["format-10 snapshot\nor untrusted older seed"]
SCOUT["metadata-first scout\none disposition per file"]
PARSE["tree-sitter, 19 grammars\n+ 6 text/config parsers"]
KNOW["knowledge lane\ndocs, specs, safe configs"]
LIFE["preventive lifecycle\ncandidates, leases, verify"]
end
subgraph Core["Live index"]
IDX["LiveIndex\nsymbols, refs, content"]
SIG["ranking signals\nfrecency, co-change"]
VERIFY["background verify\nreconcile vs disk"]
end
subgraph Lanes["Answer + write lanes"]
TOOLS["40 advertised tools\nresources + prompts\ntrust envelopes"]
GATE["read_gate\nadmit_disk_read"]
EDITS["structural edit engine"]
end
MCP --> STDIO
MCP --> HTTP
STDIO --> DAEMON
DAEMON --> IDX
HTTP --> IDX
STDIO --> IDX
LIB --> IDX
SNAP --> LIFE --> IDX
SCOUT --> PARSE --> IDX
SCOUT --> KNOW --> IDX
SIG --> IDX
IDX --> VERIFY --> IDX
IDX --> SNAP
IDX --> TOOLS
TOOLS --> GATE
TOOLS --> EDITS
EDITS --> IDX
The read path is deliberately local: symbol spans depend on the exact bytes in the workspace, so SymForge serves from an in-process index whenever it can. Every lane that reopens a file from disk goes through one gate, admit_disk_read, which classifies the exact buffer it read and returns it only on a permit. A current-format snapshot lets startup skip the parse phase and reconcile against disk in the background; answers carry SnapshotRestore / Pending trust labels until that verification completes. After an edit, the index is rebuilt from the bytes that actually landed on disk, never from the in-memory buffer.
Details: Architecture, How it works, The life of an edit, and What makes it different.
Install and quick start
Prerequisite: Node.js 18+ and npm.
npm installs a JavaScript launcher plus the native binary for your platform: Windows x64, Linux x64, macOS arm64, macOS x64. There is no postinstall step; installing downloads nothing and configures no client. Update in place with symforge update. cargo install symforge builds from source instead; it needs a C compiler, because the tree-sitter grammars, the vendored libgit2, and the bundled SQLite are C code compiled through the cc crate. A cargo install build also lacks the vendored rmcp patch (vendor/rmcp/SYMFORGE-PATCH.md), because Cargo ignores [patch] for crates.io installs: a client that opens with server/discover and then falls back to initialize can be refused on later requests. The npm binaries carry the patch.
[!CAUTION] WSL: if the shell inherits the Windows npm prefix, the install pulls the Windows binary and the launcher reports a missing
symforge-linux-x64package. Give WSL its own Linux npm prefix ahead of any/mnt/*entries onPATH, then reinstall.
To teach your agent which tool to use when, paste the Agent Setup Prompt into its instructions.
Details: Install and Client Setup, Install and Troubleshooting.
Clients
symforge init knows 13 clients: claude, claude-desktop, codex, gemini, grok, kilo-code, cursor, omp, cline, roo, vscode, copilot, continue. Plain init means --client all: it registers the user-level clients already present, prints a skipped: line for each one it passes over, and always prints a skipped: Kilo Code ... line. Kilo Code, Roo, VS Code, and Continue are workspace-local: all never writes their project files, and it prints nothing at all for Roo, VS Code, and Continue, so run symforge init --client <name> from the repository. Naming a client always registers it. symforge init --scan reports attach status without writing anything.
The same binary also runs serve (Streamable HTTP at /mcp plus an operator dashboard at /admin, default 127.0.0.1:8787), a shared local daemon, setup, admin, hook, trust, analytics, and update.
Details: Configure a client, Workspace-local clients, and Commands.
Tools
SymForge advertises 40 tools over MCP tools/list; 41 are registered. The forty-first is the compact-surface symforge facade, which the full profile filters out because symforge_retrieve is its full-surface equivalent. A client reporting 40 is correct.
Opt-in core profile. SYMFORGE_SURFACE=core lists a smaller set of 13 tools (about 27 KB of tools/list instead of 63 KB): status, get_repo_map, get_file_context, get_file_content, search_text, search_symbols, get_symbol, find_references, replace_symbol_body, edit_within_symbol, batch_edit, index_folder, symforge_retrieve. The other tools in the table below are not listed there but still answer a call by name (most clients only let the model call listed tools, so this mainly serves hooks and pinned clients); the compact-only symforge facade refuses outside SYMFORGE_SURFACE=compact.
| Group | Tools |
|---|---|
| Orient | health · health_compact · status · get_repo_map · explore · ask · conventions · context_inventory · investigation_suggest |
| Read | get_file_context · get_file_content · get_symbol · get_symbol_context · inspect_match |
| Search | search_symbols · search_text · search_files · symforge_retrieve |
| Knowledge | search_knowledge · review_knowledge · curate_knowledge |
| Trace impact | find_references · find_dependents · what_changed · diff_symbols · analyze_file_impact · detect_impact · validate_file_syntax |
| Edit | edit_plan · replace_symbol_body · edit_within_symbol · insert_symbol · delete_symbol · batch_edit · batch_insert · batch_rename · symforge_edit · secret_remediate |
| Index | index_folder · checkpoint_now |
Alongside the tools: six resources, four resource templates, and eight prompts. The protocol layer is rmcp 3.5.0, serving MCP 2026-07-28 plus every legacy revision back to 2024-11-05 from a frozen allow-list. SYMFORGE_SURFACE=compact collapses the surface to three tools (symforge, symforge_edit, status); it is an escape hatch for token-sensitive setups, not the default, and unlike core it refuses calls to any other tool.
The seven structural edit tools (replace_symbol_body, edit_within_symbol, insert_symbol, delete_symbol, batch_edit, batch_insert, batch_rename) accept an optional working_directory naming a sibling git worktree; symforge_edit accepts and forwards it without advertising it in its schema. Passing it is explicit routing consent: SymForge validates the worktree, writes there, and reports wrote_to, indexed_path, and rerouted, so parallel agents can each edit their own worktree against one index.
Details: Tool Reference, Protocol, Compact surface, and Runtime Model, Worktree-aware editing.
Embedding
Building with --no-default-features --features embed compiles the parsing, indexing, search, editing, and git core without the daemon, sidecar, protocol server, or CLI, so server-side breakage cannot reach an embedder.
= { = "11", = false, = ["embed"] }
Open one EmbeddedSourceHandle through ProcessIndexRuntime: search returns claims with provenance, refresh returns a receipt, and refusals are a typed SourceRefusalKind. symforge::embed is semver-public and pinned by a compile-time contract test. symforge::embed::parity (versioned by its own API_VERSION) serves every MCP tool, resource, and prompt natively; known differences are in the parity census. Moving from 10.x: docs/migrations/v11-index-lifecycle.md.
Details: Embedding the Engine, Build and dependency and MCP parity.
Index lifecycle and recovery
The 11.x binary runs the preventive index lifecycle: incomplete observations cannot publish as current, candidates promote only when complete, and an answer that is not current says so. Snapshot format 10 is current. A snapshot written by 10.x (format 7), or any older format, is an untrusted seed and is never restored as current. On load a copy lands under .symforge/v11/quarantine/index-snapshots/; the first snapshot write after that moves the original into .symforge/quarantine/index-snapshots/ and refuses that one write. Rolling back to 10.x means copying a preserved .bin back to .symforge/index.bin.
When a snapshot goes wrong: checkpoint_now(verify_after_write=true) forces a byte-exact write and verification; health or health_compact report the load source, verification state, and mismatch paths; corrupt or version-incompatible snapshots are preserved under .symforge/quarantine/index-snapshots/ with metadata rather than served. Rebuilding from source is deliberately explicit: run the serving process with SYMFORGE_INDEX_FOLDER_RESET=1, then call index_folder; while the variable is set every index_folder call resets, so unset it afterwards. Use index_folder reset when health, verification, or quarantine evidence shows the snapshot is not a valid recovery source. repair_index is intentionally retired; get_index_run and cancel_index_run remain retired. No durable run IDs are exposed: recovery is a sequence you drive, not a job you poll.
Details: Runtime Model, Index lifecycle (V11) and Recovery.
Configuration
Workspace state lives under .symforge/: the snapshot and its quarantine, 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. The variables you are most likely to want:
| Variable | Effect |
|---|---|
SYMFORGE_HOME |
Home for the installed binary and daemon metadata (default ~/.symforge) |
SYMFORGE_SURFACE |
compact collapses tools/list to three tools and core lists 13; default full. symforge init writes it into each client's env block, which wins over the shell |
SYMFORGE_TOOLS |
Per-process tool allow-list: comma-separated tool names or groups (read, edit, knowledge, impact, service). Only those are listed and callable (resources and ask routes included), with full descriptions. Groups are by topic, to cut context cost, not a permission boundary: secret_remediate, index_folder and curate_knowledge write outside edit; serve --tools <list> does the same and overrides it. It filters the full surface, so SYMFORGE_SURFACE=core/compact beside it is reported as a conflict. Unknown names make serve refuse to start and appear in status on stdio. It governs MCP tools and resources only; the hook and sidecar routes that feed client hooks (outline, repo map, impact data) are not covered. Not used by the embed lane |
SYMFORGE_NO_DAEMON |
Any value other than empty or 0 forces local in-process mode; symforge init sets it to 1 for Codex on Linux |
SYMFORGE_DAEMON_AUTH_TOKEN |
Bearer token the daemon requires on every route except /health; generated at daemon start when unset |
SYMFORGE_INDEXING_THREADS |
Cap the parse thread pool, for tight-RAM hosts and PID-1 embedders; default is rayon's |
SYMFORGE_WORKTREE_AWARE |
Worktree routing for edit calls that pass working_directory; enabled when unset, and any value other than empty, 1, true, yes, on, or explicit turns it off |
[!WARNING] The daemon and
serveHTTP are local coordination surfaces, not remote production APIs. The daemon binds loopback only unlessSYMFORGE_DAEMON_ALLOW_NON_LOOPBACKis set, and that opt-in warns.
Details: Environment Setup Scripts, Variable reference, Network exposure, and Runtime Model, Serving modes.
Benchmarks
The recorded evidence is thin, and the wiki says so. The only token measurement from the 11.x line, a five-pair cohort dated 2026-10-05, during the 11.x line, is inconclusive: in total the SymForge-available sessions used 603,609 fewer tokens (3,198,434 against 2,594,825), but the paired median was -40,011 and three of five pairs cost more, so the predeclared rule (positive total and positive median) returns NO_WIN. The one positive end-to-end result, 24.8% fewer tokens, was measured on 8.14.1, and its own report limits what it proves. No general percentage is claimed.
Details: Benchmarks and Token Savings, What is recorded and Where the evidence says it does not help.
Development
SymForge parses 19 languages with tree-sitter grammars plus 6 text and config formats with native parsers. The toolchain is pinned by rust-toolchain.toml (Rust 1.99.1, edition 2024).
&&
Do not pass --all-targets to cargo test with --test-threads=1; the criterion bench rejects the flag. Run the embed-feature suite in its own pass. PR CI also runs version sync, the embed build for glibc and musl, a macOS serve-port test, a windows-native job, npm tests, and the tool-correctness harness against the release binary. Releases are driven by Release Please on main.
Details: Supported Languages, Language table, Development, Test, CI gates on pull requests, and Releases.
License
SymForge is licensed under the PolyForm Noncommercial License 1.0.0.
[!CAUTION] You may inspect, study, and use the source code for noncommercial purposes. Commercial use requires a separate license.