Skip to content

Install and Client Setup

special-place-administrator edited this page Oct 11, 2026 · 1 revision

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.

Install

Prerequisite: Node.js 18 or newer, and npm.

npm install -g symforge
symforge --version

The 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.

PATH

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.

WSL

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.

Build from source with cargo

The crate is also published on crates.io, and the release workflow publishes it with every release:

cargo install symforge

This 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.

Update

symforge update

symforge 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.

Configure a client

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.
  • all runs only the user-level clients already present on the machine, using the same test as init --scan. For each user-level client it passes over it prints one skipped: <client> (no <directory>; run symforge init --client <name>) line on stderr, and it always prints a fixed skipped: Kilo Code (...) line. The workspace-local clients roo, vscode and continue are never written by all and print nothing; run them by name.

Every init message goes to stderr. A normal run ends with symforge init complete.

Client reference

--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.

What init writes for each client

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.symforge with command, args, disabled: false, env.SYMFORGE_SURFACE=full, and an alwaysAllow list of the SymForge tool names (merged as a union with anything already there).
  • ~/.claude/settings.json: four hook entries that run symforge hook ... (PostToolUse on Read|Edit|Write|Grep, PreToolUse on Grep|Read|Glob|Edit, SessionStart on startup|resume, and UserPromptSubmit), plus every SymForge tool name in allowedTools. 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.json that already names symforge has its launch pair repaired. init never creates a project .mcp.json.

Claude Desktop

  • mcpServers.symforge with env.SYMFORGE_SURFACE=compact. This is the one client written with the compact surface: the three-tool symforge, symforge_edit, status surface (see Tool-Reference).
  • env.SYMFORGE_WORKSPACE_ROOT is set to the project root discovered from the directory you ran init in, when one is found.
  • On Windows, Claude Desktop starts servers with the working directory C:\WINDOWS\System32, where SymForge cannot write. init therefore writes a wrapper, symforge-desktop.cmd, next to the Desktop config (not beside the npm binary, which npm replaces on every update). The wrapper cds 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 with index_folder.
  • The Linux Desktop path is the conventional ~/.config/Claude/ location, not one Anthropic documents.

Codex

  • ~/.codex/config.toml: [mcp_servers.symforge] with command, args, and env.SYMFORGE_SURFACE=full. On Linux hosts it also sets env.SYMFORGE_NO_DAEMON=1. No timeouts are seeded; Codex's defaults apply. project_doc_fallback_filenames gains AGENTS.md and CLAUDE.md.
  • ~/.codex/AGENTS.md: the managed guidance block.
  • Codex gets MCP tools only. init registers no Codex hooks, so the transparent hook enrichment Claude Code receives does not apply.

Gemini CLI

  • ~/.gemini/settings.json: mcpServers.symforge with command, args, trust: true, and env.SYMFORGE_SURFACE=full.
  • ~/.gemini/GEMINI.md: the managed guidance block.
  • If Gemini folder trust is enabled and the current directory is not trusted, init prints a warning: stdio servers will not connect there until the workspace is trusted in Gemini.

Grok

  • ~/.grok/config.toml: [mcp_servers.symforge] with command, args, enabled = true, and env.RUST_LOG = "off". No guidance file is written and no surface variable is set. Grok's args are always replaced with an empty list. The file is global, so no workspace root is written; a workspace root pinned by an older init is removed.

Cursor

  • ~/.cursor/mcp.json: mcpServers.symforge with command, args, and env.SYMFORGE_SURFACE=full. The file is global and read by every Cursor window, so init writes no cwd and no SYMFORGE_WORKSPACE_ROOT; the server binds from the workspace roots Cursor declares. A cwd plus root pin written by an older init is migrated away. An existing project .cursor/mcp.json that names symforge has its launch pair repaired.

Oh My Pi (omp)

  • ~/.omp/agent/mcp.json: mcpServers.symforge with command, args, and env.SYMFORGE_SURFACE=full. alwaysAllow and disabled are not written, because OMP does not read them.

Cline and VS Code portable (copilot)

  • ~/.cline/mcp.json and ~/.copilot/mcp-config.json: mcpServers.symforge with command, args, and env.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.

Workspace-local clients

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 mcp object, type: "local", command as an array holding the executable and its args, environment (not env), enabled: true, and environment.SYMFORGE_SURFACE=full. A mcpServers.symforge object from an older init is moved under mcp. A JSONC file that serde_json cannot parse (comments, for example) is left untouched and the run stops with a parse error.
  • VS Code uses a top-level servers object, not mcpServers, with type: "stdio".
  • Roo and Continue use mcpServers with command, args and env.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.

What every init run does

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, and symforge init complete is not printed. Fix the file and re-run. (init --scan --apply differs: 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 .gitignore that does not already ignore .symforge/, init appends /.symforge/. It never creates a .gitignore: with none, or outside a repository, nothing changes. Either way it prints a receipt line gitignore_hygiene=<status> changed=<true|false>.
  • Runtime directory. It ensures the .symforge/ directory exists for the working directory.
  • PATH shadow warning. If a different symforge precedes the registered one on PATH, it prints the exact fix.

Guidance block

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.

Scan and attach over HTTP

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:

  1. copies the existing file to <config>.<UTC timestamp>.bak,
  2. 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.

Commands

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.

Troubleshooting

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.

Clone this wiki locally