Configuration

ide-bridge has three configuration surfaces: the checked-in project file, environment variables, and the daemon's runtime state file.

`.ide-bridge.yaml`

Created by ide-bridge init in your project root. Commit this file — it carries the stable project_id across machines and teammates.

project_id: acme-billing-service

# Optional overrides:
# identity:
#   prefer: explicit          # explicit | git | path
# fidelity:
#   produce_max: L3
#   consume_max: L3
# exclude_paths:
#   - node_modules
#   - .venv
#   - build

Field reference

| Field | Type | Default | Description | |---|---|---|---| | project_id | string | (derived) | Stable identifier for this project. All IDEs opening the same directory will share this bundle. | | identity.prefer | "explicit" \| "git" \| "path" | "explicit" | Which resolution tier to use first. explicit means .ide-bridge.yaml wins; git uses remote+branch; path uses a directory fingerprint. | | fidelity.produce_max | L0 \| L1 \| L2 \| L3 | L3 | Cap how much context this project writes on save. Useful to limit data stored for sensitive repos. | | fidelity.consume_max | L0 \| L1 \| L2 \| L3 | L3 | Cap how much context the daemon returns on load. | | exclude_paths | string[] | [] | Paths excluded from git-state extraction (appended to the adapter's built-in ignore list). |

Project identity resolution

When a tool call arrives without an explicit project_id, the daemon resolves identity in three tiers — stopping at the first match:

Explicit — reads project_id from .ide-bridge.yaml in the calling IDE's cwd.
Git — derives an ID from the git remote URL + current branch (origin/main → origin-main).
Path fingerprint — hashes the absolute directory path as a last resort.

The explicit tier always wins when .ide-bridge.yaml is present. Use ide-bridge init (or ide-bridge init --gitignore for single-user) to lock the ID.

Environment variables

Override storage paths and log verbosity without editing any file.

| Variable | Default | Purpose | |---|---|---| | IDE_BRIDGE_HOME | ~/.ide-bridge | Root directory for all ide-bridge data: bundles, history, transcripts, daemon state. | | IDE_BRIDGE_CURSOR_STORAGE | OS-default Cursor workspaceStorage | Full path to Cursor's workspaceStorage directory. Set this if Cursor is installed in a non-standard location or you use multiple Cursor profiles. | | IDE_BRIDGE_LOG_LEVEL | info | Pino log level: trace, debug, info, warn, error, fatal, or silent. |

Setting variables

Add to your shell profile (~/.zshrc, ~/.bashrc):

export IDE_BRIDGE_HOME="$HOME/.config/ide-bridge"
export IDE_BRIDGE_LOG_LEVEL="debug"

Or prefix a single command:

IDE_BRIDGE_LOG_LEVEL=debug ide-bridge start

`~/.ide-bridge/config.json`

The daemon writes its runtime state here when it starts. Do not edit this file manually — the daemon owns it.

{
  "pid": 12345,
  "port": 31415,
  "startedAt": "2026-04-17T10:00:00.000Z"
}

| Field | Description | |---|---| | pid | Process ID of the running daemon. Used by ide-bridge stop to send SIGTERM. | | port | The port the daemon is actually listening on (may differ from 31415 on conflict). | | startedAt | ISO timestamp of daemon start. |

ide-bridge status reads this file and verifies the process is alive before reporting "running". If the file exists but the process is gone (stale), ide-bridge start overwrites it safely.

Port conflict behavior

The daemon binds to 127.0.0.1:31415 by default. If that port is taken, it probes upward automatically:

:31415 → :31416 → :31417 → ... → :31425

The first free port wins. The chosen port is written to ~/.ide-bridge/config.json and logged on startup:

ide-bridge listening on http://127.0.0.1:31416/mcp  ← port shifted

Update your IDE MCP configs if the port shifts. To keep the port stable, ensure nothing else claims :31415 at login time (the service installer handles this by starting ide-bridge before most user processes).

Next: MCP tools →