Runtime Model

Runtime Model

Use this page for

understanding daemon mode, snapshots, hook-sidecar behavior, and environment variables.

Startup

At startup, SymForge:

1. discovers a project root unless auto-indexing is disabled
2. attempts to connect to or start a local daemon
3. falls back to local in-process mode if needed
4. starts with an empty index if no project root is found

Daemon mode

Run:

symforge daemon

Daemon mode is useful when multiple sessions should share one index.

Persistence

Index snapshots persist at:

.symforge/index.bin

This improves restart speed and reduces unnecessary reindexing work.

Hooks and sidecar

Hook and sidecar behavior matters most for clients such as Claude Code that integrate SymForge into read/edit interception flows.

Relevant project-local files may include:

• .symforge/sidecar.port
• .symforge/sidecar.pid
• .symforge/sidecar.session
• .symforge/hook-adoption.log

When hook infrastructure is unavailable, the intended behavior is fail-open with diagnostics rather than a hard block.

Parameter compatibility

Some MCP clients stringify parameters. SymForge accepts common stringified forms for:

• booleans
• numbers
• arrays
• arrays of stringified objects

This is mainly to reduce friction across heterogeneous MCP clients and extensions.

Environment variables

Variable	Default	Effect
SYMFORGE_HOME	~/.symforge	Home directory for binary and daemon metadata
SYMFORGE_AUTO_INDEX	true	Enables project discovery and startup indexing
SYMFORGE_HOOK_VERBOSE	unset	Set to 1 for hook stderr diagnostics
SYMFORGE_CB_THRESHOLD	0.20	Parse-failure circuit-breaker threshold
SYMFORGE_SIDECAR_BIND	127.0.0.1	Sidecar bind host for local in-process mode

Operational guidance

• Use health to inspect daemon and index state.
• Use index_folder to refresh stale or missing project state.
• Use analyze_file_impact after targeted edits.
• Treat daemon mode as optional optimization, not a requirement for normal use.

Tip

If SymForge appears unavailable in a client, the first recovery sequence is usually health followed by index_folder, not immediate fallback to raw file tools.