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. The path is used verbatim: the leading tilde is not expanded and a relative path is not resolved, so always pass a fully resolved absolute path. An empty or whitespace-only value is ignored and 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. It relocates only context-mode-owned state — sessions, indexed content, and per-project memory — and never touches the host's own config (settings.json, hooks.json, config.toml stay where the host expects them). Unlike CONTEXT_MODE_DIR, it expands a leading tilde and resolves relative paths.

export CONTEXT_MODE_DATA_DIR=~/context-mode-data

Use this when the host's home directory is on a read-only or NFS volume (CI runners, dev containers, shared workspaces) and you want context-mode storage on a writable disk without patching the host's own config location.

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 always blocks link-local, IMDS (cloud metadata), and reserved addresses. By default it still allows loopback and private RFC1918 ranges so you can fetch from local dev servers and internal hosts. Set CTX_FETCH_STRICT=1 to block loopback and private addresses as well — 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. Rules are written as Tool(match) patterns, where match accepts * wildcards. Deny always wins over allow, so 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 *)"]
  }
}

These rules are not limited to direct tool calls. context-mode enforces the same deny and allow patterns inside ctx_execute, ctx_execute_file, and ctx_batch_execute, so a command blocked at the host is also blocked when it is run from the sandbox. See Security for the full enforcement model.

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. To wipe indexed content and reset session stats instead of deleting files by hand, use the /context-mode:ctx-purge slash command (or the ctx_purge tool with confirm: true).

Next steps