Runtime Model

Runtime Model

Use this page for

understanding startup, daemon mode, snapshots, sidecar state, local stores, analytics, and environment variables.

Startup

At startup, SymForge:

1. discovers a project root unless auto-indexing is disabled;
2. decides whether to use a local in-process index or a shared daemon session;
3. loads a snapshot when one is valid;
4. indexes the workspace when a fresh index is needed;
5. starts the watcher and serves MCP tools over stdio.

If no project root is found, SymForge can still start, but health will show an empty or unavailable project state and the recovery path is usually index_folder(path).

Local In-Process Mode

Local mode keeps the active LiveIndex inside the MCP server process. This is the simplest and most deterministic path. It is the right mental model for most single-client sessions.

Daemon Mode

Run:

symforge daemon

Daemon mode lets multiple local sessions share project/session state. Clients can fall back to local in-process mode if daemon routing is unavailable.

Set SYMFORGE_NO_DAEMON=1 when you want to force local mode.

Snapshots

Index snapshots persist at:

.symforge/index.bin

Snapshots are a startup accelerator, not the final authority. Current workspace bytes, file watcher events, analyze_file_impact, and index_folder keep the runtime honest.

checkpoint_now writes a snapshot on demand (optionally verifying it reads back after the write). Corrupt or version-incompatible snapshots are never silently served: they are moved to .symforge/quarantine/index-snapshots/ with metadata, and health reports the load source and verification state.

Worktree-Aware Editing

Every edit tool accepts an optional working_directory naming a sibling git worktree. Supplying it is explicit call-time routing consent: SymForge validates the worktree, maps the indexed path into it, writes there, and the response self-describes with wrote_to, indexed_path, and rerouted.

Guarantees:

• Routed edits compound. When the worktree target has diverged from the indexed copy (for example, after an earlier routed edit to the same file), the single-symbol edit tools re-read and re-parse the target bytes as the edit base, and the envelope reports Source authority: worktree target (rebased).
• The index stays truthful. A routed write never replaces the index entry for the indexed copy with worktree bytes.
• Batch tools fail closed on divergence. batch_edit, batch_insert, and batch_rename splice index-resolved byte ranges, so a rerouted batch onto a diverged target refuses with an actionable error instead of overwriting earlier routed edits.

This is the mechanism for running parallel agent sessions: one shared index, one worktree per session, every routed write receipted.

Watcher And Reconciliation

The watcher keeps the index current as files change. Reconciliation handles drift, missed events, and repair sweeps. health reports watcher state, reconcile repairs, overflows, and stale-mutation rejections.

Sidecar State

Sidecar metadata is stored under .symforge/ and may include:

• .symforge/sidecar.port
• .symforge/sidecar.pid
• .symforge/sidecar.session

health reports sidecar PID, port, and liveness state when available. Missing or dead sidecar state should be visible, not silently hidden.

Local Stores

Path	Purpose
.symforge/index.bin	Warm-start index snapshot
.symforge/quarantine/index-snapshots/	Preserved corrupt or version-incompatible snapshots with metadata
.symforge/idempotency/	Replay records for mutating tools (plus quarantined corrupt records)
.symforge/tee/	Pre-write copies of files preserved before each structural edit
.symforge/frecency.db	Optional persistent frecency ranking signal
.symforge/coupling.db	Optional co-change coupling store
.symforge/analytics.db	Optional local analytics records
.symforge/sidecar.*	Sidecar PID/port/session metadata

Analytics

Analytics are local, optional, bounded, and redacted. When enabled, tool-call metadata is queued to a background writer instead of written synchronously on the handler hot path.

CLI:

symforge analytics status
symforge analytics summary
symforge analytics export
symforge analytics reset

Disabled analytics should not create an analytics database.

Result And Capability State

Modern tool responses report stable outcome classes where the transport can carry metadata. Health and ranking responses also report optional capability state such as ready, preparing, unavailable, disabled-by-policy, stale, and fallback-used.

This matters because "no result", "invalid request", "ambiguous selector", and "internal failure" require different agent behavior.

Environment Variables

Variable	Effect
SYMFORGE_HOME	Home directory for installed binary and daemon metadata
SYMFORGE_AUTO_INDEX	Enables startup project discovery and indexing
SYMFORGE_NO_DAEMON	Forces local in-process mode
SYMFORGE_SIDECAR_BIND	Bind host for local sidecar state
SYMFORGE_DAEMON_BIND	Bind host for daemon state; loopback hosts accepted by default
SYMFORGE_DAEMON_ALLOW_NON_LOOPBACK	Explicit truthy opt-in required before the daemon binds a non-loopback host
SYMFORGE_DAEMON_AUTH_TOKEN	Optional local bearer token for daemon project, session, tool, and sidecar routes
SYMFORGE_CHECKPOINT_INTERVAL_SECS	Optional periodic snapshot interval for local in-process mode (bounded 30-3600 seconds; unset/0/false disables)
SYMFORGE_RECONCILE_INTERVAL	Watcher reconciliation interval in seconds; 0 disables periodic sweeps
SYMFORGE_CB_THRESHOLD	Parse-failure circuit-breaker threshold
SYMFORGE_FRECENCY	Frecency policy: session default, persistent when truthy, disabled when false/off/disabled
SYMFORGE_COUPLING	Co-change policy: lazy default, warm on startup when truthy, disabled when false/off/disabled
SYMFORGE_DEBUG_RANKING	Ranking diagnostic policy
SYMFORGE_WORKTREE_AWARE	Worktree routing policy for edit calls
SYMFORGE_EXCLUDE_UNTRACKED	Opt-in: demote untracked recognized-extension files to metadata-only indexing
SYMFORGE_ANALYTICS_DB_PATH	Override analytics database location
SYMFORGE_FRECENCY_DB_PATH	Override frecency database location
SYMFORGE_COUPLING_DB_PATH	Override co-change database location
SYMFORGE_PROJECT_CONFIG_TRUST_MODE	Trust behavior for project-local SymForge configuration

Recovery Sequence

When SymForge looks wrong in a client:

1. call health;
2. inspect index/runtime/sidecar state;
3. call index_folder(path) if the workspace is empty, stale, or wrong;
4. call validate_file_syntax for malformed files;
5. call analyze_file_impact after targeted file edits;
6. retry the original query.