Configuration

DimCode stores all persistent data locally. By default it lives under ~/.dimcode/.

Tip: Prefer configuring inside the TUI (Ctrl+P, /connect, /models, /tool-settings) instead of editing JSON by hand.

Directory layout (default)

~/.dimcode/
  config.json                 # provider connections + UI settings
  tools.json                  # tool config (WebSearch, MCP)
  dimcode/
    cache.json                # cached preferences + session metadata
    state/                    # session state store (messages, diffs, etc.)
    bin/
      binary-upgrade.json     # standalone binary upgrade metadata
    upgrade-toast.json        # last upgrade notification

Path resolution rules

Base directories

DimCode uses two base directories:

• Config dir: stores config.json
• Cache dir: stores cache.json, state/, bin/, and upgrade metadata

Resolution:

1. If DIMCODE_HOME is set:
   • Config dir: $DIMCODE_HOME
   • Cache dir: $DIMCODE_HOME/dimcode
2. Else if XDG_CONFIG_HOME is set:
   • Config dir: $XDG_CONFIG_HOME/.dimcode
   • Cache dir: $XDG_CONFIG_HOME/.dimcode/dimcode
3. Else (default):
   • Config dir: ~/.dimcode
   • Cache dir: ~/.dimcode/dimcode

tools.json location

tools.json uses a separate resolution rule:

1. If DIMCODE_HOME is set: $DIMCODE_HOME/tools.json
2. Else if XDG_CONFIG_HOME is set: $XDG_CONFIG_HOME/dimcode/tools.json
3. Else: ~/.dimcode/tools.json

State dir override

You can override the state store location without moving everything else:

• DIMCODE_STATE_DIR=/absolute/path/to/state

What each file does

config.json

Purpose: provider connections, active provider/model, and custom providers/models (plus a few UI-level settings).

Typical shape (simplified):

{
  "version": 1,
  "updatedAt": 0,
  "settings": {
    "providerId": "openai",
    "activeModelByProvider": {
      "openai": "gpt-4.1-mini",
      "openrouter": "openrouter/auto",
      "ollama": "qwen2.5-coder:14b"
    },
    "providerConnections": {
      "openai": {
        "apiKey": "****",
        "baseUrl": "https://api.openai.com/v1"
      },
      "openrouter": {
        "apiKey": "****"
      },
      "ollama": {
        "baseUrl": "http://localhost:11434/v1",
        "models": [{ "id": "qwen2.5-coder:14b" }]
      }
    },
    "customProviders": [
      {
        "id": "cp_abc123",
        "name": "My Gateway",
        "adapter": "openai-responses",
        "baseUrl": "http://localhost:8080/v1",
        "apiKey": "****",
        "models": [{ "id": "my-model" }]
      }
    ]
  }
}

Notes:

• Prefer using /connect in the TUI instead of editing JSON by hand.
• customProviders is where DimCode stores custom endpoints you create in the Connect Provider flow.
• customProvider (if present) is legacy and may be migrated into customProviders automatically.

cache.json

Purpose: cached preferences and session metadata.

Common fields include:

• settings.model (default model id)
• settings.temperature
• settings.contextWindow
• settings.toolApprovals (auto / all / manual depending on UI mode)

The exact contents may evolve across versions; treat it as internal cache.

tools.json

Purpose: tool-specific configuration, like WebSearch and MCP servers.

Typical shape (simplified):

{
  "version": 1,
  "updatedAt": 0,
  "settings": {
    "websearch": {
      "apiKey": "",
      "apiEndpoint": "https://google.serper.dev/search?format=json",
      "numResults": 10
    },
    "mcpServers": []
  }
}

Config precedence (who wins)

At runtime, environment variables override saved files. This is useful for CI and for temporary overrides.

Common env vars:

• OPENAI_API_KEY (OpenAI-compatible credentials)
• OPENAI_BASE_URL / DIMCODE_OPENAI_BASE_URL (OpenAI-compatible endpoint)
• OPENAI_API_BASE_URL (legacy; used by some SDK examples)
• GOOGLE_API_KEY (Gemini credentials)
• DIMCODE_GEMINI_BASE_URL (Gemini endpoint override)
• ANTHROPIC_API_KEY (Anthropic credentials)
• DIMCODE_ANTHROPIC_BASE_URL (Anthropic endpoint override)
• DIMCODE_PROVIDER_ADAPTER (openai / openai-responses / gemini / anthropic)
• DIMCODE_MODEL (model id)
• DIMCODE_TEMPERATURE
• DIMCODE_CONTEXT_WINDOW
• DIMCODE_TOOL_APPROVALS (auto / all)
• DIMCODE_SESSION_ID (session ID for exec mode)
• DIMCODE_SERVER_TOKEN (server authentication token)
• DIMCODE_DISABLE_AUTOUPDATE=1 (disable update checks)
• DIMCODE_AUTOUPDATE=0 (disable background installs)

Reset / clean start

If you want to fully reset local state (this will remove sessions):

rm -rf ~/.dimcode/dimcode/state
rm -f ~/.dimcode/config.json ~/.dimcode/tools.json ~/.dimcode/dimcode/cache.json ~/.dimcode/dimcode/auth.json

Then start dim again and re-run /connect.