Configuration

context-mode runs with sane defaults, so most installs need no configuration at all. When you do need to change where data lives, override host detection, or tune how often guidance is re-injected, you do it through a handful of environment variables and your host's settings file. Everything stays local; there is nothing to configure in a cloud account.

Environment variables

Set these in your shell profile, your agent CLI's environment, or the process that launches the host. Unset variables fall back to the defaults below.

CONTEXT_MODE_DIR

CONTEXT_MODE_DIR is the root under which context-mode writes everything for a host — the sessions and content directories are created beneath it.

• Used verbatim — the leading tilde is not expanded and a relative path is not resolved, so always pass a fully resolved absolute path.
• Empty or whitespace-only values are ignored — the host's adapter default is used instead.

export CONTEXT_MODE_DIR=/Users/you/.context-mode

CONTEXT_MODE_DATA_DIR

CONTEXT_MODE_DATA_DIR is a universal storage-root override that every adapter honors:

• Relocates only context-mode-owned state — sessions, indexed content, and per-project memory.
• Never touches the host's own config — settings.json, hooks.json, and config.toml stay where the host expects them.
• Expands a leading tilde and resolves relative paths — unlike CONTEXT_MODE_DIR.

export CONTEXT_MODE_DATA_DIR=~/context-mode-data

Use this when the host's home directory is on a read-only or NFS volume and you want context-mode storage on a writable disk without patching the host's own config location — for example:

• CI runners
• Dev containers
• Shared workspaces

CONTEXT_MODE_PLATFORM

context-mode detects the host it runs inside and adapts its hook and tool behavior to match. When detection is wrong — for example, in a wrapper script or a non-standard launch — set CONTEXT_MODE_PLATFORM to the host's identifier to force the correct integration.

export CONTEXT_MODE_PLATFORM=opencode

Suppressing duplicate tools

In hosts that load context-mode as a native plugin, such as OpenCode and Kilo, the ctx_* tools can appear twice if a legacy MCP entry also exists. Set CONTEXT_MODE_EMBEDDED_PLUGIN_TOOLS to 1 to suppress the duplicate set so each tool shows up once.

export CONTEXT_MODE_EMBEDDED_PLUGIN_TOOLS=1

Stricter fetch mode

ctx_fetch_and_index decides which network targets are reachable based on this mode:

By default, loopback and private ranges stay allowed so you can fetch from local dev servers and internal hosts. Set CTX_FETCH_STRICT=1 to block them too — useful in hosted or CI environments where the runtime is not your own machine.

export CTX_FETCH_STRICT=1

Permissions

Permissions are expressed as deny and allow rules in your host's settings file, which uses the Claude settings.json format:

• Rule syntax — written as Tool(match) patterns, where match accepts * wildcards.
• Deny wins — a denied pattern is blocked even if a broader allow rule would otherwise admit it.

{
  "permissions": {
    "deny": ["Bash(rm -rf *)", "Bash(curl *)"],
    "allow": ["Bash(git *)", "Bash(npm *)"]
  }
}

Storage layout

Everything context-mode persists lives under the root resolved from CONTEXT_MODE_DIR. There are two directories:

• A sessions directory holds the SessionDB — per-session state and the stats that power the /context-mode:ctx-stats slash command.
• A content directory holds indexed content — the FTS5 knowledge base that ctx_search queries.

ls "$CONTEXT_MODE_DIR"

Because both directories sit under one root, moving or backing up context-mode's data is a single directory operation.

Next steps