Repository navigation
Install and Client Setup
How to get SymForge onto a machine and attach it to an MCP client. This page is
the full detail behind the README's Install and Configure a client sections. It
describes the 11.7.0 behavior of symforge init as implemented in
src/cli/init.rs
and its neighbours under
src/cli/.
Installing and configuring are separate steps. Installing never touches a
client's configuration; symforge init is the only thing that does.
Prerequisite: Node.js 18 or newer, and npm.
npm install -g symforge
symforge --versionThe symforge package is a small JavaScript launcher. The native binary ships
in a platform package that npm installs as an optional dependency and picks
for your OS and CPU:
| Platform | npm package |
|---|---|
| Windows x64 | symforge-windows-x64 |
| Linux x64 | symforge-linux-x64 |
| macOS arm64 | symforge-macos-arm64 |
| macOS x64 | symforge-macos-x64 |
No other platform has a prebuilt binary. The same binary runs the stdio server, the shared daemon, and the HTTP server, so there is nothing else to install.
There is no postinstall step: installing does not download anything, stop processes, or write any MCP client configuration.
symforge must land in the npm global prefix of the OS you are running, and that
prefix's bin directory must be on PATH. On Windows the default prefix
(%APPDATA%\npm) already is. On macOS and Linux, if npm install -g fails with
a permissions error, do not use sudo. Point npm at a user-writable prefix and
reinstall:
npm config set prefix "$HOME/.npm-global"If an older symforge elsewhere on PATH shadows the one you just installed,
both the launcher and symforge init print a warning naming the shadowing path.
Registered client entries are unaffected, because init writes the absolute
path of the binary it ran from; only your own bare symforge commands resolve
through PATH.
A WSL shell often inherits the Windows PATH and a shared Windows npm prefix.
The global install then lands in the Windows prefix and pulls the Windows
binary, which cannot run under Linux; the launcher reports a missing
symforge-linux-x64 package. Give WSL its own Linux npm prefix first, put it
ahead of any /mnt/* entries on PATH, install, and confirm with
which symforge. Per-environment setup snippets are on
Environment-Setup-Scripts.
The crate is also published on crates.io, and the release workflow publishes it with every release:
cargo install symforgeThis compiles from source. The default server feature builds the symforge
binary. A C compiler is required: the tree-sitter grammar crates, the vendored
libgit2 (git2 with vendored-libgit2), and the bundled SQLite (rusqlite
with bundled) all compile C sources through the cc crate. The repository pins Rust 1.96.0 in
rust-toolchain.toml. From a checkout, cargo build --release produces
target/release/symforge.
symforge init registers the absolute path of the binary it is running from, and
refuses to register a binary inside the system temporary directory or a
symforge-smoke-* worktree, because those paths vanish. Run init from the
installed copy, not from a scratch build.
symforge updatesymforge update updates an npm-managed install. It skips the swap when
nothing is behind. Otherwise it installs the new version into a staging
directory first and verifies the staged binary, swaps it in while keeping the
old files until the new binary answers an initialize request, checks that
symforge --version reports the latest release, restarts only the daemon, and
re-runs init for the clients that already carry a SymForge entry. Running
stdio sessions are not terminated. A failed swap restores the previous files
and exits non-zero. It does not downgrade. A cargo install is updated by running cargo install symforge again.
symforge init # same as --client all
symforge init --client claude # one client
symforge init --client all # every client that is already installed--client accepts: claude, claude-desktop, codex, gemini, grok,
kilo-code, cursor, omp, cline, roo, vscode, copilot, continue,
all. Four aliases exist: desktop (claude-desktop), kilo (kilo-code),
oh-my-pi (omp), vscode-portable (copilot).
Two rules decide what runs:
- A named client always runs, and creates its config directory if it is missing.
-
allruns only the user-level clients already present on the machine, using the same test asinit --scan. For each user-level client it passes over it prints oneskipped: <client> (no <directory>; run symforge init --client <name>)line on stderr, and it always prints a fixedskipped: Kilo Code (...)line. The workspace-local clientsroo,vscodeandcontinueare never written byalland print nothing; run them by name.
Every init message goes to stderr. A normal run ends with
symforge init complete.
--client |
Config written | Format | Reached by all when |
|---|---|---|---|
claude |
~/.claude.json, ~/.claude/settings.json, ~/.claude/CLAUDE.md
|
JSON, Markdown |
~/.claude.json or ~/.claude/ exists |
claude-desktop |
Windows %APPDATA%\Claude\claude_desktop_config.json; macOS ~/Library/Application Support/Claude/claude_desktop_config.json; Linux ~/.config/Claude/claude_desktop_config.json
|
JSON | the config file or its directory exists |
codex |
~/.codex/config.toml, ~/.codex/AGENTS.md
|
TOML, Markdown |
~/.codex/ exists |
gemini |
~/.gemini/settings.json, ~/.gemini/GEMINI.md
|
JSON, Markdown |
~/.gemini/ exists |
grok |
~/.grok/config.toml |
TOML |
~/.grok/ exists |
cursor |
~/.cursor/mcp.json |
JSON |
~/.cursor/ exists |
omp |
~/.omp/agent/mcp.json |
JSON |
~/.omp/ exists |
cline |
~/.cline/mcp.json |
JSON |
~/.cline/ exists |
copilot |
~/.copilot/mcp-config.json |
JSON |
~/.copilot/ exists |
kilo-code |
.kilo/kilo.jsonc (or an existing root kilo.jsonc), ~/.config/kilo/kilo.jsonc, .kilocode/rules/symforge.md
|
JSONC, Markdown | user file only, when ~/.config/kilo/ exists |
roo |
.roo/mcp.json |
JSON | never |
vscode |
.vscode/mcp.json |
JSON | never |
continue |
.continue/mcpServers/symforge.json |
JSON | never |
The Cline path is the Cline CLI file; the Cline IDE extension's storage path is not written. The Roo global settings file is likewise not written.
Every client gets a stdio server entry named symforge whose command is the
absolute path of the running binary and whose args are empty. The stdio server
is symforge with no subcommand, so no argument is needed. init merges into
the existing symforge entry only: every other server, and every field you set
on the SymForge entry, is preserved. Where SYMFORGE_SURFACE is written it is
written only when absent, so a value you set is never overwritten.
Claude Code
-
~/.claude.json:mcpServers.symforgewithcommand,args,disabled: false,env.SYMFORGE_SURFACE=full, and analwaysAllowlist of the SymForge tool names (merged as a union with anything already there). -
~/.claude/settings.json: four hook entries that runsymforge hook ...(PostToolUseonRead|Edit|Write|Grep,PreToolUseonGrep|Read|Glob|Edit,SessionStartonstartup|resume, andUserPromptSubmit), plus every SymForge tool name inallowedTools. Existing SymForge hook entries are replaced in place; other hooks are kept. -
~/.claude/CLAUDE.md: the managed guidance block (see Guidance block). - An existing project
.mcp.jsonthat already namessymforgehas its launch pair repaired.initnever creates a project.mcp.json.
Claude Desktop
-
mcpServers.symforgewithenv.SYMFORGE_SURFACE=compact. This is the one client written with the compact surface: the three-toolsymforge,symforge_edit,statussurface (see Tool-Reference). -
env.SYMFORGE_WORKSPACE_ROOTis set to the project root discovered from the directory you raninitin, when one is found. - On Windows, Claude Desktop starts servers with the working directory
C:\WINDOWS\System32, where SymForge cannot write.inittherefore writes a wrapper,symforge-desktop.cmd, next to the Desktop config (not beside the npm binary, which npm replaces on every update). The wrappercds into the discovered workspace, or into%USERPROFILE%when none was found, then launches the binary by absolute path. With no workspace root, the index stays empty until a project is opened withindex_folder. - The Linux Desktop path is the conventional
~/.config/Claude/location, not one Anthropic documents.
Codex
-
~/.codex/config.toml:[mcp_servers.symforge]withcommand,args, andenv.SYMFORGE_SURFACE=full. On Linux hosts it also setsenv.SYMFORGE_NO_DAEMON=1. No timeouts are seeded; Codex's defaults apply.project_doc_fallback_filenamesgainsAGENTS.mdandCLAUDE.md. -
~/.codex/AGENTS.md: the managed guidance block. - Codex gets MCP tools only.
initregisters no Codex hooks, so the transparent hook enrichment Claude Code receives does not apply.
Gemini CLI
-
~/.gemini/settings.json:mcpServers.symforgewithcommand,args,trust: true, andenv.SYMFORGE_SURFACE=full. -
~/.gemini/GEMINI.md: the managed guidance block. - If Gemini folder trust is enabled and the current directory is not trusted,
initprints a warning: stdio servers will not connect there until the workspace is trusted in Gemini.
Grok
-
~/.grok/config.toml:[mcp_servers.symforge]withcommand,args,enabled = true, andenv.RUST_LOG = "off". No guidance file is written and no surface variable is set. Grok'sargsare always replaced with an empty list. The file is global, so no workspace root is written; a workspace root pinned by an olderinitis removed.
Cursor
-
~/.cursor/mcp.json:mcpServers.symforgewithcommand,args, andenv.SYMFORGE_SURFACE=full. The file is global and read by every Cursor window, soinitwrites nocwdand noSYMFORGE_WORKSPACE_ROOT; the server binds from the workspace roots Cursor declares. Acwdplus root pin written by an olderinitis migrated away. An existing project.cursor/mcp.jsonthat namessymforgehas its launch pair repaired.
Oh My Pi (omp)
-
~/.omp/agent/mcp.json:mcpServers.symforgewithcommand,args, andenv.SYMFORGE_SURFACE=full.alwaysAllowanddisabledare not written, because OMP does not read them.
Cline and VS Code portable (copilot)
-
~/.cline/mcp.jsonand~/.copilot/mcp-config.json:mcpServers.symforgewithcommand,args, andenv.SYMFORGE_SURFACE=full.
Remote entries are left alone. An existing symforge entry that has a
url, httpUrl or serverUrl, or a remote type (http, sse, ws,
streamable-http, remote), is not a stdio launch; init does not add a
command to it. An entry whose args hold something other than a wrapper path,
for example serve, is not overwritten: init stops with an error instead.
Kilo Code, Roo, VS Code (vscode) and Continue write files inside the
repository you run init from. Run symforge init --client <name> from that
repository. all never creates their project files.
| Client | Files written under the working directory |
|---|---|
kilo-code |
.kilo/kilo.jsonc (an existing .kilo/kilo.json, or a root kilo.jsonc or kilo.json, is used instead when present); .kilocode/rules/symforge.md
|
roo |
.roo/mcp.json |
vscode |
.vscode/mcp.json |
continue |
.continue/mcpServers/symforge.json |
kilo-code also writes the user-level file ~/.config/kilo/kilo.jsonc.
-
Kilo Code uses its own schema: a top-level
mcpobject,type: "local",commandas an array holding the executable and its args,environment(notenv),enabled: true, andenvironment.SYMFORGE_SURFACE=full. AmcpServers.symforgeobject from an olderinitis moved undermcp. A JSONC file thatserde_jsoncannot parse (comments, for example) is left untouched and the run stops with a parse error. -
VS Code uses a top-level
serversobject, notmcpServers, withtype: "stdio". -
Roo and Continue use
mcpServerswithcommand,argsandenv.SYMFORGE_SURFACE=full.
When all runs, it always prints
skipped: Kilo Code (project-local config is written only when named; run symforge init --client kilo-code),
and also registers the user file ~/.config/kilo/kilo.jsonc when
~/.config/kilo/ exists. If a
project file for one of these clients already names symforge, a later init
(including all) repairs its launch pair in place; it never creates the file.
Beyond the per-client files:
- Atomic writes. Each config is written to a temporary file and renamed into place. A symlinked config stays a symlink. A UTF-8 byte-order mark on an existing file is stripped on read, so Windows-edited configs parse.
-
A parse error stops the run. The failing file is not modified, clients
registered earlier in the run keep their changes, and later clients are not
registered. Project launch-pair repair, gitignore hygiene and the
.symforge/step are skipped too, andsymforge init completeis not printed. Fix the file and re-run. (init --scan --applydiffers: it reports the error and continues with the other clients.) - Guidance is idempotent. An unchanged guidance block does not touch the file's modification time.
-
Git hygiene. In a git repository with a root
.gitignorethat does not already ignore.symforge/,initappends/.symforge/. It never creates a.gitignore: with none, or outside a repository, nothing changes. Either way it prints a receipt linegitignore_hygiene=<status> changed=<true|false>. -
Runtime directory. It ensures the
.symforge/directory exists for the working directory. -
PATH shadow warning. If a different
symforgeprecedes the registered one onPATH, it prints the exact fix.
Claude Code, Codex, Gemini CLI and Kilo Code receive the same Markdown block,
between <!-- SYMFORGE START --> and <!-- SYMFORGE END --> markers, in
~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.gemini/GEMINI.md and
.kilocode/rules/symforge.md. Re-running init replaces what is between the
markers and leaves the rest of the file alone. The block is a short task-to-tool
map. Other clients receive no guidance file; the Agent-Setup-Prompt covers
them.
symforge init --scan inspects the clients without installing a stdio server.
It writes nothing unless --apply is also given.
symforge init --scan
symforge init --scan --serve-url http://127.0.0.1:8787/mcp
symforge init --scan --serve-url http://127.0.0.1:8787/mcp --apply| Flag | Effect |
|---|---|
--scan |
Report each known client's attach state. --client is ignored. |
--serve-url <url> |
The symforge serve URL to attach to. Requires --scan. With it and no --apply, prints a dry-run plan. |
--serve-key <key> |
Bearer key for that URL. Requires --serve-url. Omit for a keyless loopback server. |
--apply |
Write the HTTP entry. Requires --scan and --serve-url; without a URL it stops with an error. |
--scan covers six clients: Claude Code (~/.claude.json), Claude Desktop,
Codex (~/.codex/config.toml), Gemini CLI (~/.gemini/settings.json), Kilo Code
(.kilocode/mcp.json in the working directory), and Cursor (~/.cursor/mcp.json).
The Kilo Code path is Kilo's legacy file, not the .kilo/kilo.jsonc that
init --client kilo-code writes; whether current Kilo reads an HTTP entry there
is unverified.
Grok, Oh My Pi, Cline, Roo, VS Code, Copilot and Continue are not scanned.
A bare scan (no --serve-url) labels each client not installed, no SymForge entry,
SymForge entry present, SymForge entry present (url differs from the target)
(or the bearer key, or both), or config does not parse: <reason>. The stale
message names which field differs and never prints a key.
--apply plans first, then for each client that needs a change:
- copies the existing file to
<config>.<UTC timestamp>.bak, - writes the new entry atomically.
Clients that are not installed, or already current, are skipped; a config that
does not parse is reported as an error and left alone, without aborting the rest.
Output is a [written], [skipped] or [error] line per client on stderr.
The entry replaces the existing symforge entry wholesale: JSON clients get
{"type": "http", "url": ..., "headers": {"Authorization": "Bearer <key>"}}
under mcpServers.symforge, and Codex gets url and bearer_token under
[mcp_servers.symforge]. A stdio launch pair that was there is gone, so this
switches that client from stdio to HTTP. The key is stored in the config file in
clear text, and a key passed with --serve-key is visible in your shell history
and process list. To switch back, run symforge init --client <name>.
Starting the server and the dashboard is covered under Commands and on Runtime-Model.
| Command | Purpose |
|---|---|
symforge (no subcommand) |
Run the stdio MCP server. This is what clients launch. |
--version |
Print the version and exit. |
init |
Register clients, or scan and attach over HTTP (above). --client defaults to all. |
setup |
Guided operator wizard: scan harnesses, configure, start the dashboard. Flags: --non-interactive, --installation-type in-harness|server|both, --port, --harnesses <ids>, --yes. |
serve |
Streamable HTTP MCP at /mcp with the operator dashboard at /admin. Default 127.0.0.1:8787; if that port is taken and --listen was not given, an OS-assigned free port is used. Flags: --listen, --api-key, --api-key-env. |
admin |
Open the running operator dashboard, reusing a server on the remembered port or starting one. --no-open prints the URL only. |
daemon |
Run the shared local daemon that lets sessions share one index. |
hook |
Claude Code hook entry points: read, edit, write, grep, session-start, prompt-submit, pre-tool. |
trust |
Audit, accept or revoke trust for project-local .symforge configuration (trust project-config status|accept --hash|revoke, each with --project <root>). |
analytics |
Inspect, summarize, export or reset an existing local analytics database (status, summary, export --limit, reset; each accepts --db-path). The 11.7.0 server never creates one. |
update |
Update an npm-managed install. See Update. |
| Symptom | Cause and fix |
|---|---|
symforge: command not found after install |
The npm global bin directory is not on PATH. See PATH. |
Launcher reports a missing symforge-linux-x64 package under WSL |
The install landed in the Windows prefix. See WSL. |
init stops with "refusing to register ... temporary SymForge binary" |
You ran it from an npx cache, a temp directory or a smoke worktree. Run npm install -g symforge, then symforge init from that install. |
init parse error on a client file |
The file is not valid JSON or TOML (JSONC comments in a Kilo file count). The run stopped there: that file was not modified and later clients were not registered. Fix it and re-run. |
init stops on an existing entry's args
|
The entry launches something other than the plain stdio server. Edit or remove it by hand. |
| A client reports MCP schema errors naming another server | Strict clients reject the whole MCP set when any one server advertises invalid JSON Schema. Check the other servers first. |
| Gemini CLI never connects | Folder trust is enabled and the workspace is untrusted; see the warning init printed. |
| Tools return an empty or loading index | Call health, then index_folder on the workspace root. See Runtime-Model. |
Next: give your agent the Agent-Setup-Prompt, then the Tool-Reference.
Need the short version? The README links each topic to its page here.
Install and client setup: Install-and-Client-Setup